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.

310 lines
7.3 KiB

4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
  1. /**
  2. * @file sync_api.h
  3. * @brief sync API
  4. * @license GNU General Public License 3.0 - see LICENSE.txt
  5. */
  6. #pragma once
  7. #include "message.h"
  8. #ifdef __cplusplus
  9. extern "C" {
  10. #endif
  11. /**
  12. * @enum sync_handshake_signal
  13. *
  14. * @brief TODO
  15. *
  16. */
  17. typedef enum _sync_handshake_signal {
  18. SYNC_NOTIFY_UNDEFINED = 0,
  19. // request show handshake dialog
  20. SYNC_NOTIFY_INIT_ADD_OUR_DEVICE = 1,
  21. SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE = 2,
  22. SYNC_NOTIFY_INIT_FORM_GROUP = 3,
  23. // SYNC_NOTIFY_INIT_MOVE_OUR_DEVICE = 4,
  24. // handshake process timed out
  25. SYNC_NOTIFY_TIMEOUT = 5,
  26. // handshake accepted by user
  27. SYNC_NOTIFY_ACCEPTED_DEVICE_ADDED = 6,
  28. SYNC_NOTIFY_ACCEPTED_GROUP_CREATED = 7,
  29. SYNC_NOTIFY_ACCEPTED_DEVICE_ACCEPTED = 8,
  30. // handshake dialog must be closed
  31. // SYNC_NOTIFY_OVERTAKEN = 9,
  32. // forming group
  33. // SYNC_NOTIFY_FORMING_GROUP = 10,
  34. // these two notifications must be evaluated by applications, which are
  35. // using a Desktop Adapter
  36. SYNC_NOTIFY_START = 126,
  37. SYNC_NOTIFY_STOP = 127,
  38. // message cannot be sent, need passphrase
  39. SYNC_PASSPHRASE_REQUIRED = 128,
  40. // notification of actual group status
  41. SYNC_NOTIFY_SOLE = 254,
  42. SYNC_NOTIFY_IN_GROUP = 255
  43. } sync_handshake_signal;
  44. /**
  45. * <!-- notifyHandshake() -->
  46. *
  47. * @brief Notify UI about sync handshaking process
  48. *
  49. * @param[in] obj object handle (implementation defined)
  50. * @param[in] me own identity
  51. * @param[in] partner identity of partner
  52. * @param[in] signal reason of the notification
  53. *
  54. * @retval PEP_STATUS_OK or any other value on error
  55. *
  56. * @warning ownership of me and partner go to the callee
  57. *
  58. */
  59. typedef PEP_STATUS (*notifyHandshake_t)(
  60. pEp_identity *me,
  61. pEp_identity *partner,
  62. sync_handshake_signal signal
  63. );
  64. /**
  65. * @enum sync_handshake_result
  66. *
  67. * @brief TODO
  68. *
  69. */
  70. typedef enum _sync_handshake_result {
  71. SYNC_HANDSHAKE_CANCEL = -1,
  72. SYNC_HANDSHAKE_ACCEPTED = 0,
  73. SYNC_HANDSHAKE_REJECTED = 1
  74. } sync_handshake_result;
  75. /**
  76. * <!-- deliverHandshakeResult() -->
  77. *
  78. * @brief Provide the result of the handshake dialog
  79. *
  80. * @param[in] session session handle
  81. * @param[in] result handshake result
  82. * @param[in] identities_sharing own_identities sharing data in this group
  83. *
  84. * @warning identities_sharing may be NULL; in this case all identities are sharing
  85. * data in the group
  86. * identities_sharing may only contain own identities
  87. *
  88. */
  89. DYNAMIC_API PEP_STATUS deliverHandshakeResult(
  90. PEP_SESSION session,
  91. sync_handshake_result result,
  92. const identity_list *identities_sharing
  93. );
  94. /**
  95. * <!-- retrieve_next_sync_event() -->
  96. *
  97. * @brief Receive next sync event
  98. *
  99. * @param[in] management application defined; usually a locked queue
  100. * @param[in] threshold threshold in seconds for timeout
  101. *
  102. * @retval next event
  103. *
  104. * @warning an implementation of retrieve_next_sync_event must return
  105. * new_sync_timeout_event() in case of timeout
  106. *
  107. */
  108. typedef SYNC_EVENT (*retrieve_next_sync_event_t)(void *management,
  109. unsigned threshold);
  110. /**
  111. * <!-- register_sync_callbacks() -->
  112. *
  113. * @brief Register adapter's callbacks
  114. *
  115. * @param[in] session session where to register callbacks
  116. * @param[in] management application defined; usually a locked queue
  117. * @param[in] notifyHandshake callback for doing the handshake
  118. * @param[in] retrieve_next_sync_event callback for receiving sync event
  119. *
  120. * @retval PEP_STATUS_OK or any other value on errror
  121. *
  122. * @warning use this function in an adapter where you're processing the sync
  123. * state machine
  124. * implement start_sync() in this adapter and provide it to the
  125. * application, so it can trigger startup
  126. * in case of parallelization start_sync() and register_sync_callbacks()
  127. * will run in parallel
  128. * do not return from start_sync() before register_sync_callbacks() was
  129. * executed
  130. * when execution of the sync state machine ends a call to
  131. * unregister_sync_callbacks() is recommended
  132. *
  133. */
  134. DYNAMIC_API PEP_STATUS register_sync_callbacks(
  135. PEP_SESSION session,
  136. void *management,
  137. notifyHandshake_t notifyHandshake,
  138. retrieve_next_sync_event_t retrieve_next_sync_event
  139. );
  140. /**
  141. * <!-- unregister_sync_callbacks() -->
  142. *
  143. * @brief TODO
  144. *
  145. * @param[in] session PEP_SESSION
  146. *
  147. */
  148. DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
  149. /**
  150. * <!-- do_sync_protocol() -->
  151. *
  152. * @brief Function to be run on an extra thread
  153. *
  154. * @retval PEP_STATUS_OK if thread has to terminate successfully or any other
  155. * @retval value on failure
  156. *
  157. *
  158. */
  159. DYNAMIC_API PEP_STATUS do_sync_protocol(
  160. PEP_SESSION session,
  161. void *obj
  162. );
  163. /**
  164. * <!-- do_sync_protocol_step() -->
  165. *
  166. * @brief Function for single threaded implementations
  167. *
  168. *
  169. */
  170. DYNAMIC_API PEP_STATUS do_sync_protocol_step(
  171. PEP_SESSION session,
  172. void *obj,
  173. SYNC_EVENT event
  174. );
  175. /**
  176. * <!-- is_sync_thread() -->
  177. *
  178. * @brief Determine if this is sync thread's session
  179. *
  180. * paramters:
  181. * session (in) pEp session to test
  182. *
  183. * @retval true if this is sync thread's session, false otherwise
  184. *
  185. *
  186. */
  187. DYNAMIC_API bool is_sync_thread(PEP_SESSION session);
  188. /**
  189. * <!-- new_sync_timeout_event() -->
  190. *
  191. * @brief Create a Sync timeout event
  192. *
  193. * @retval returns a new Sync timeout event, or NULL on failure
  194. *
  195. *
  196. */
  197. DYNAMIC_API SYNC_EVENT new_sync_timeout_event();
  198. /**
  199. * <!-- enter_device_group() -->
  200. *
  201. * @brief Enter a device group
  202. *
  203. * @param[in] session pEp session
  204. * @param[in] identities_sharing own_identities sharing data in this group
  205. *
  206. * @warning identities_sharing may be NULL; in this case all identities are sharing
  207. * data in the group
  208. * identities_sharing may only contain own identities
  209. * this call can be repeated if sharing information changes
  210. *
  211. */
  212. DYNAMIC_API PEP_STATUS enter_device_group(
  213. PEP_SESSION session,
  214. const identity_list *identities_sharing
  215. );
  216. /**
  217. * <!-- disable_sync() -->
  218. *
  219. * @brief Leave a device group and shutdown sync
  220. *
  221. *
  222. */
  223. PEP_STATUS disable_sync(PEP_SESSION session);
  224. /**
  225. * <!-- leave_device_group() -->
  226. *
  227. * @brief Issue a group key reset request and
  228. * leave the device group, shutting down sync
  229. *
  230. *
  231. */
  232. DYNAMIC_API PEP_STATUS leave_device_group(PEP_SESSION session);
  233. /**
  234. * <!-- enable_identity_for_sync() -->
  235. *
  236. * @brief Enable sync for this identity
  237. *
  238. *
  239. */
  240. DYNAMIC_API PEP_STATUS enable_identity_for_sync(PEP_SESSION session,
  241. pEp_identity *ident);
  242. /**
  243. * <!-- disable_identity_for_sync() -->
  244. *
  245. * @brief Disable sync for this identity
  246. *
  247. *
  248. */
  249. DYNAMIC_API PEP_STATUS disable_identity_for_sync(PEP_SESSION session,
  250. pEp_identity *ident);
  251. #ifdef __cplusplus
  252. }
  253. #endif