p≡p engine
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

329 lines
7.8 KiB

/**
* @file sync_api.h
* @brief sync API
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#ifndef SYNC_API_H
#define SYNC_API_H
#include "message.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @enum sync_handshake_signal
*
* @brief TODO
*
*/
typedef enum _sync_handshake_signal {
SYNC_NOTIFY_UNDEFINED = 0,
// request show handshake dialog
SYNC_NOTIFY_INIT_ADD_OUR_DEVICE = 1,
SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE = 2,
SYNC_NOTIFY_INIT_FORM_GROUP = 3,
// SYNC_NOTIFY_INIT_MOVE_OUR_DEVICE = 4,
// handshake process timed out
SYNC_NOTIFY_TIMEOUT = 5,
// handshake accepted by user
SYNC_NOTIFY_ACCEPTED_DEVICE_ADDED = 6,
SYNC_NOTIFY_ACCEPTED_GROUP_CREATED = 7,
SYNC_NOTIFY_ACCEPTED_DEVICE_ACCEPTED = 8,
// handshake dialog must be closed
// SYNC_NOTIFY_OVERTAKEN = 9,
// forming group
// SYNC_NOTIFY_FORMING_GROUP = 10,
// these two notifications must be evaluated by applications, which are
// using a Desktop Adapter
SYNC_NOTIFY_START = 126,
SYNC_NOTIFY_STOP = 127,
// message cannot be sent, need passphrase
SYNC_PASSPHRASE_REQUIRED = 128,
// notify that a (managed or managed, NOT device) group invite message has been received
SYNC_NOTIFY_GROUP_INVITATION = 192, // whatever. This shouldn't be bundled with sync. FIXME.
// notification of actual group status
SYNC_NOTIFY_SOLE = 254,
SYNC_NOTIFY_IN_GROUP = 255
} sync_handshake_signal;
/**
* <!-- notifyHandshake() -->
*
* @brief Notify UI about sync handshaking process
*
* @param[in] obj object handle (implementation defined)
* @param[in] me own identity
* @param[in] partner identity of partner
* @param[in] signal reason of the notification
*
* @retval PEP_STATUS_OK or any other value on error
*
* @warning ownership of me and partner go to the callee
*
*/
typedef PEP_STATUS (*notifyHandshake_t)(
pEp_identity *me,
pEp_identity *partner,
sync_handshake_signal signal
);
/**
* @enum sync_handshake_result
*
* @brief TODO
*
*/
typedef enum _sync_handshake_result {
SYNC_HANDSHAKE_CANCEL = -1,
SYNC_HANDSHAKE_ACCEPTED = 0,
SYNC_HANDSHAKE_REJECTED = 1
} sync_handshake_result;
/**
* <!-- deliverHandshakeResult() -->
*
* @brief Provide the result of the handshake dialog
*
* @param[in] session session handle
* @param[in] result handshake result
* @param[in] identities_sharing own_identities sharing data in this group
*
* @warning identities_sharing may be NULL; in this case all identities are sharing
* data in the group
* identities_sharing may only contain own identities
*
*/
DYNAMIC_API PEP_STATUS deliverHandshakeResult(
PEP_SESSION session,
sync_handshake_result result,
const identity_list *identities_sharing
);
/**
* <!-- retrieve_next_sync_event() -->
*
* @brief Receive next sync event
*
* @param[in] management application defined; usually a locked queue
* @param[in] threshold threshold in seconds for timeout
*
* @retval next event
*
* @warning an implementation of retrieve_next_sync_event must return
* new_sync_timeout_event() in case of timeout
*
*/
typedef SYNC_EVENT (*retrieve_next_sync_event_t)(void *management,
unsigned threshold);
/**
* <!-- register_sync_callbacks() -->
*
* @brief Register adapter's callbacks
*
* @param[in] session session where to register callbacks
* @param[in] management application defined; usually a locked queue
* @param[in] notifyHandshake callback for doing the handshake
* @param[in] retrieve_next_sync_event callback for receiving sync event
*
* @retval PEP_STATUS_OK or any other value on errror
*
* @warning use this function in an adapter where you're processing the sync
* state machine
* implement start_sync() in this adapter and provide it to the
* application, so it can trigger startup
* in case of parallelization start_sync() and register_sync_callbacks()
* will run in parallel
* do not return from start_sync() before register_sync_callbacks() was
* executed
* when execution of the sync state machine ends a call to
* unregister_sync_callbacks() is recommended
*
*/
DYNAMIC_API PEP_STATUS register_sync_callbacks(
PEP_SESSION session,
void *management,
notifyHandshake_t notifyHandshake,
retrieve_next_sync_event_t retrieve_next_sync_event
);
/**
* <!-- unregister_sync_callbacks() -->
*
* @brief TODO
*
* @param[in] session PEP_SESSION
*
*/
DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
/**
* <!-- do_sync_protocol() -->
*
* @brief Function to be run on an extra thread
*
* @retval PEP_STATUS_OK if thread has to terminate successfully or any other
* @retval value on failure
*
*
*/
DYNAMIC_API PEP_STATUS do_sync_protocol(
PEP_SESSION session,
void *obj
);
/**
* <!-- do_sync_protocol_step() -->
*
* @brief Function for single threaded implementations
*
*
*/
DYNAMIC_API PEP_STATUS do_sync_protocol_step(
PEP_SESSION session,
void *obj,
SYNC_EVENT event
);
/**
* <!-- is_sync_thread() -->
*
* @brief Determine if this is sync thread's session
*
* paramters:
* session (in) pEp session to test
*
* @retval true if this is sync thread's session, false otherwise
*
*
*/
DYNAMIC_API bool is_sync_thread(PEP_SESSION session);
/**
* <!-- new_sync_timeout_event() -->
*
* @brief Create a Sync timeout event
*
* @retval returns a new Sync timeout event, or NULL on failure
*
*
*/
DYNAMIC_API SYNC_EVENT new_sync_timeout_event();
/**
* <!-- enter_device_group() -->
*
* @brief Enter a device group
*
* @param[in] session pEp session
* @param[in] identities_sharing own_identities sharing data in this group
*
* @warning identities_sharing may be NULL; in this case all identities are sharing
* data in the group
* identities_sharing may only contain own identities
* this call can be repeated if sharing information changes
*
*/
DYNAMIC_API PEP_STATUS enter_device_group(
PEP_SESSION session,
const identity_list *identities_sharing
);
/**
* <!-- disable_sync() -->
*
* @brief Leave a device group and shutdown sync
*
*
*/
PEP_STATUS disable_sync(PEP_SESSION session);
/**
* <!-- leave_device_group() -->
*
* @brief Issue a group key reset request and
* leave the device group, shutting down sync
*
*
*/
DYNAMIC_API PEP_STATUS leave_device_group(PEP_SESSION session);
/**
* <!-- enable_identity_for_sync() -->
*
* @brief Enable sync for this identity
*
*
*/
DYNAMIC_API PEP_STATUS enable_identity_for_sync(PEP_SESSION session,
pEp_identity *ident);
/**
* <!-- disable_identity_for_sync() -->
*
* @brief Disable sync for this identity
*
*
*/
DYNAMIC_API PEP_STATUS disable_identity_for_sync(PEP_SESSION session,
pEp_identity *ident);
/**
* <!-- disable_all_sync_channels() -->
*
* @brief Disable sync for all identities; use this function to reset
* the state which identities will be synced and which not
* This function is intended to be used at app init
*
*
*/
DYNAMIC_API PEP_STATUS disable_all_sync_channels(PEP_SESSION session);
#ifdef __cplusplus
}
#endif
#endif