src/sync.h
author Edouard Tisserant <edouard@pep-project.org>
Fri, 09 Dec 2016 01:36:57 +0100
changeset 1477 c0d761ae1fd9
parent 1475 f76bc25570df
child 1482 dae999ee1a41
permissions -rw-r--r--
sync: obey new app notification enum names, this time with corresponding actions generated
     1 /*
     2 ====================================
     3 Engine/adapter/app KeySync interface 
     4 ====================================
     5 
     6 In the engine, KeySync is implemented through a state machine [1]. KeySync
     7 state machine is driven [2] by events, triggering actions [3] and transitions
     8 to new states. Events happens on decryption of email messages, on key
     9 generation, on user interaction through the app and in case of timeout when
    10 staying too long in some particular states.
    11 
    12 To use KeySync, the adapter has to create a session dedicated to handle the
    13 protocol, register some callbacks [4] to the engine, and then call protocol's
    14 event consumer loop [5] in a dedicated thread. KeySync actions are executed
    15 as callback invoked from that loop : send pEp messages through app's transport
    16 and display KeySync status and handshake to the user.
    17 
    18 When a session is attached [6] to a KeySync session, decryption of pEp (email)
    19 messages in that session may trigger operations in attached KeySync session. In
    20 case of an adapter capable to serve multiple apps, each app is associated to a
    21 different KeySync session, and sessions created for use in that app are
    22 attached to that session.
    23 
    24 KeySync messages [7], not to be confused with pEp (email) messages, are either
    25 directly events to be processed by the state machine or KeySync payloads
    26 collected from decrypted messages. They are jobs to be processed by the state
    27 machine.
    28 
    29 KeySync messages can be emitted by multiple session, and could naturally come
    30 from different threads. They must be serialized in a locked queue. Attached
    31 sessions inject [8] KeySync messages in the queue. Protocol loop retrieves [9]
    32 them from the queue. KeySync message is received [10] by the state machine,
    33 where event eventually deduced from payload.
    34 
    35 A state timeout event is a particular case. It doesn't traverse the queue, and
    36 isn't emitted by a session. It is triggered by a timeout on the retrieve
    37 operation. Value of the timeout is determined when entering a new state, and is
    38 passed as a parameter of the call to the blocking queue retrieve operation on 
    39 next protocol loop iteraton.
    40 
    41 [1] sync/device_group.fsm , src/sync_fsm.c (generated)
    42 [2] src/sync_driver.c (generated)
    43 [3] src/sync_actions.c , src/sync_send_actions.c (generated)
    44 [4] register_sync_callbacks()
    45 [5] do_sync_protocol()
    46 [6] attach_sync_session()
    47 [7] type sync_msg_t
    48 [8] callback inject_sync_msg
    49 [9] callback retrieve_next_sync_msg
    50 [10] receive_sync_msg() (src/sync_impl.c)
    51 
    52 */
    53 
    54 #pragma once
    55 
    56 #include "message.h"
    57 #include "sync_fsm.h"
    58 
    59 
    60 // this module is for being used WITHOUT the Transport API in transport.h
    61 // DO NOT USE IT WHEN USING Transport API!
    62 
    63 
    64 #ifdef __cplusplus
    65 extern "C" {
    66 #endif
    67 
    68 // messageToSend() - send a message
    69 //
    70 //  parameters:
    71 //      obj (in)        object handle (implementation defined)
    72 //      msg (in)        message struct with message to send
    73 //
    74 //  return value:
    75 //      PEP_STATUS_OK or any other value on error
    76 //
    77 //  caveat:
    78 //      the ownership of msg goes to the callee
    79 
    80 typedef PEP_STATUS (*messageToSend_t)(void *obj, message *msg);
    81 
    82 // TODO add this to generated code.
    83 typedef enum _sync_handshake_signal {
    84     SYNC_NOTIFY_UNDEFINED = 0,
    85 
    86     // request show handshake dialog
    87     SYNC_NOTIFY_INIT_ADD_OUR_DEVICE,
    88     SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE,
    89     SYNC_NOTIFY_INIT_FORM_GROUP,
    90 
    91     // handshake process timed out
    92     SYNC_NOTIFY_TIMEOUT,
    93 
    94     // handshake accepted by user
    95     SYNC_NOTIFY_ACCEPTED_DEVICE_ADDED,
    96     SYNC_NOTIFY_ACCEPTED_GROUP_CREATED
    97 
    98 } sync_handshake_signal;
    99 
   100 // notifyHandshake() - notify UI about sync handshaking process
   101 //
   102 //  parameters:
   103 //      obj (in)        object handle (implementation defined)
   104 //      me (in)         own identity
   105 //      partner (in)    identity of partner
   106 //      signal (in)     reason of the notification
   107 //
   108 //  return value:
   109 //      PEP_STATUS_OK or any other value on error
   110 //
   111 //  caveat:
   112 //      ownership of self and partner go to the callee
   113 
   114 typedef PEP_STATUS (*notifyHandshake_t)(
   115         void *obj,
   116         pEp_identity *me,
   117         pEp_identity *partner,
   118         sync_handshake_signal signal
   119     );
   120 
   121 typedef enum _sync_handshake_result {
   122     SYNC_HANDSHAKE_CANCEL = -1,
   123     SYNC_HANDSHAKE_ACCEPTED = 0,
   124     SYNC_HANDSHAKE_REJECTED = 1
   125 } sync_handshake_result;
   126 
   127 // deliverHandshakeResult() - give the result of the handshake dialog
   128 //
   129 //  parameters:
   130 //      session (in)        session handle
   131 //      result (in)         handshake result
   132 
   133 DYNAMIC_API PEP_STATUS deliverHandshakeResult(
   134         PEP_SESSION session,
   135         Identity partner,
   136         sync_handshake_result result
   137     );
   138 
   139 // sync_msg_t - items queued for serialized handling by protocol engine
   140 typedef struct _sync_msg_t sync_msg_t;
   141 
   142 // inject_sync_msg - inject sync protocol message
   143 //
   144 //  parameters:
   145 //      msg (in)            message to inject
   146 //      management (in)     application defined
   147 //
   148 //  return value:
   149 //      0 if msg could be stored successfully or nonzero otherwise
   150 
   151 typedef int (*inject_sync_msg_t)(void *msg, void *management);
   152 
   153 
   154 // retrieve_next_sync_msg - receive next sync message
   155 //
   156 //  parameters:
   157 //      management (in)     application defined
   158 //      timeout (in,out)    do not wait longer than timeout for message
   159 //
   160 //  return value:
   161 //      next message or :
   162 //      NULL and timeout == 0 for termination
   163 //      NULL and timeout != 0 for timeout occurence
   164 
   165 typedef void *(*retrieve_next_sync_msg_t)(void *management, time_t *timeout);
   166 
   167 
   168 // register_sync_callbacks() - register adapter's callbacks
   169 //
   170 //  parameters:
   171 //      session (in)                session where to store obj handle
   172 //      management (in)             application defined
   173 //      messageToSend (in)          callback for sending message
   174 //      notifyHandshake (in)        callback for doing the handshake
   175 //      retrieve_next_sync_msg (in) callback for receiving sync messages
   176 //
   177 //  return value:
   178 //      PEP_STATUS_OK or any other value on errror
   179 //
   180 //  caveat:
   181 //      call that BEFORE you're using any other part of the engine
   182 
   183 DYNAMIC_API PEP_STATUS register_sync_callbacks(
   184         PEP_SESSION session,
   185         void *management,
   186         messageToSend_t messageToSend,
   187         notifyHandshake_t notifyHandshake,
   188         inject_sync_msg_t inject_sync_msg,
   189         retrieve_next_sync_msg_t retrieve_next_sync_msg
   190     );
   191 
   192 // attach_sync_session() - attach session to a session running keysync state machine 
   193 //
   194 //  parameters:
   195 //      session (in)                session to attach
   196 //      sync_session (in)           session running keysync
   197 //
   198 //  return value:
   199 //      PEP_STATUS_OK or any other value on errror
   200 //
   201 //  caveat:
   202 //      register_sync_callbacks must have been called on sync_session
   203 //      call that BEFORE you're using that session in any other part of the engine
   204 
   205 DYNAMIC_API PEP_STATUS attach_sync_session(
   206         PEP_SESSION session,
   207         PEP_SESSION sync_session
   208     );
   209 
   210 // detach_sync_session() - detach previously attached sync session
   211 //
   212 //  parameters:
   213 //      session (in)                session to detach 
   214 
   215 DYNAMIC_API PEP_STATUS detach_sync_session(PEP_SESSION session);
   216 
   217 // unregister_sync_callbacks() - unregister adapter's callbacks
   218 //
   219 //  parameters:
   220 //      session (in)                session to unregister
   221 
   222 DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
   223 
   224 // do_sync_protocol() - function to be run on an extra thread
   225 //
   226 //  parameters:
   227 //      session                 pEp session to use
   228 //      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
   229 //                              which returns at least a valid address field in
   230 //                              the identity struct
   231 //      obj                     application defined sync object
   232 //
   233 //  return value:
   234 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   235 //      value on failure
   236 //
   237 //  caveat:
   238 //      to ensure proper working of this library, a thread has to be started
   239 //      with this function immediately after initialization
   240 
   241 DYNAMIC_API PEP_STATUS do_sync_protocol(
   242         PEP_SESSION session,
   243         void *obj
   244     );
   245 
   246 // free_sync_msg() - free sync_msg_t struct when not passed to do_sync_protocol  
   247 //
   248 //  parameters:
   249 //      sync_msg (in)            pointer to sync_msg_t struct to free
   250 
   251 DYNAMIC_API void free_sync_msg(sync_msg_t *sync_msg);
   252 
   253 // decode_sync_msg() - decode sync message from PER into XER
   254 //
   255 //  parameters:
   256 //      data (in)               PER encoded data
   257 //      size (in)               size of PER encoded data
   258 //      text (out)              XER text of the same sync message
   259 
   260 DYNAMIC_API PEP_STATUS decode_sync_msg(
   261         const char *data,
   262         size_t size,
   263         char **text
   264     );
   265 
   266 
   267 // encode_sync_msg() - encode sync message from XER into PER
   268 //
   269 //  parameters:
   270 //      text (in)               string with XER text of the sync message
   271 //      data (out)              PER encoded data
   272 //      size (out)              size of PER encoded data
   273 
   274 DYNAMIC_API PEP_STATUS encode_sync_msg(
   275         const char *text,
   276         char **data,
   277         size_t *size
   278     );
   279 
   280 
   281 #ifdef __cplusplus
   282 }
   283 #endif
   284