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