/** * @file sync_api.h * @brief sync API * @license GNU General Public License 3.0 - see LICENSE.txt */ #pragma once #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, // notification of actual group status SYNC_NOTIFY_SOLE = 254, SYNC_NOTIFY_IN_GROUP = 255 } sync_handshake_signal; /** * * * @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; /** * * * @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 ); /** * * * @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); /** * * * @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 ); /** * * * @brief TODO * * @param[in] session PEP_SESSION * */ DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session); /** * * * @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 ); /** * * * @brief Function for single threaded implementations * * */ DYNAMIC_API PEP_STATUS do_sync_protocol_step( PEP_SESSION session, void *obj, SYNC_EVENT event ); /** * * * @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); /** * * * @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(); /** * * * @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 ); /** * * * @brief Leave a device group and shutdown sync * * */ PEP_STATUS disable_sync(PEP_SESSION session); /** * * * @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); /** * * * @brief Enable sync for this identity * * */ DYNAMIC_API PEP_STATUS enable_identity_for_sync(PEP_SESSION session, pEp_identity *ident); /** * * * @brief Disable sync for this identity * * */ DYNAMIC_API PEP_STATUS disable_identity_for_sync(PEP_SESSION session, pEp_identity *ident); #ifdef __cplusplus } #endif