src/sync.h
changeset 1467 ff7c60d14af0
parent 1462 b93663bfc7c6
child 1470 616d6a5d5539
     1.1 --- a/src/sync.h	Wed Dec 07 15:41:29 2016 +0100
     1.2 +++ b/src/sync.h	Thu Dec 08 00:51:41 2016 +0100
     1.3 @@ -1,13 +1,60 @@
     1.4 +/*
     1.5 +====================================
     1.6 +Engine/adapter/app KeySync interface 
     1.7 +====================================
     1.8 +
     1.9 +In the engine, KeySync is implemented through a state machine [1]. KeySync
    1.10 +state machine is driven [2] by events, triggering actions [3] and transitions
    1.11 +to new states. Events happens on decryption of email messages, on key
    1.12 +generation, on user interaction through the app and in case of timeout when
    1.13 +staying too long in some particular states.
    1.14 +
    1.15 +To use KeySync, the adapter has to create a session dedicated to handle the
    1.16 +protocol, register some callbacks [4] to the engine, and then call protocol's
    1.17 +event consumer loop [5] in a dedicated thread. KeySync actions are executed
    1.18 +as callback invoked from that loop : send pEp messages through app's transport
    1.19 +and display KeySync status and handshake to the user.
    1.20 +
    1.21 +When a session is attached [6] to a KeySync session, decryption of pEp (email)
    1.22 +messages in that session may trigger operations in attached KeySync session. In
    1.23 +case of an adapter capable to serve multiple apps, each app is associated to a
    1.24 +different KeySync session, and sessions created for use in that app are
    1.25 +attached to that session.
    1.26 +
    1.27 +KeySync messages [7], not to be confused with pEp (email) messages, are either
    1.28 +directly events to be processed by the state machine or KeySync payloads
    1.29 +collected from decrypted messages. They are jobs to be processed by the state
    1.30 +machine.
    1.31 +
    1.32 +KeySync messages can be emitted by multiple session, and could naturally come
    1.33 +from different threads. They must be serialized in a locked queue. Attached
    1.34 +sessions inject [8] KeySync messages in the queue. Protocol loop retrieves [9]
    1.35 +them from the queue. KeySync message is received [10] by the state machine,
    1.36 +where event eventually deduced from payload.
    1.37 +
    1.38 +A state timeout event is a particular case. It doesn't traverse the queue, and
    1.39 +isn't emitted by a session. It is triggered by a timeout on the retrieve
    1.40 +operation. Value of the timeout is determined when entering a new state, and is
    1.41 +passed as a parameter of the call to the blocking queue retrieve operation on 
    1.42 +next protocol loop iteraton.
    1.43 +
    1.44 +[1] sync/device_group.fsm , src/sync_fsm.c (generated)
    1.45 +[2] src/sync_driver.c (generated)
    1.46 +[3] src/sync_actions.c , src/sync_send_actions.c (generated)
    1.47 +[4] register_sync_callbacks()
    1.48 +[5] do_sync_protocol()
    1.49 +[6] attach_sync_session()
    1.50 +[7] type sync_msg_t
    1.51 +[8] callback inject_sync_msg
    1.52 +[9] callback retrieve_next_sync_msg
    1.53 +[10] receive_sync_msg() (src/sync_impl.c)
    1.54 +
    1.55 +*/
    1.56  #pragma once
    1.57  
    1.58  #include "message.h"
    1.59  #include "sync_fsm.h"
    1.60  
    1.61 -
    1.62 -// this module is for being used WITHOUT the Transport API in transport.h
    1.63 -// DO NOT USE IT WHEN USING Transport API!
    1.64 -
    1.65 -
    1.66  #ifdef __cplusplus
    1.67  extern "C" {
    1.68  #endif
    1.69 @@ -89,16 +136,16 @@
    1.70  typedef int (*inject_sync_msg_t)(void *msg, void *management);
    1.71  
    1.72  
    1.73 -// retrieve_next_sync_msg - receive next sync message
    1.74 +// retrieve_next_sync_msg - retrieve next sync message
    1.75  //
    1.76  //  parameters:
    1.77  //      management (in)     application defined
    1.78 -//      timeout (in,out)    do not wait longer than timeout for message
    1.79 +//      timeout (in,out)    do not wait longer than timeout for message (seconds)
    1.80  //
    1.81  //  return value:
    1.82  //      next message or :
    1.83 -//      NULL + timeout == 0 for termination
    1.84 -//      NULL + timeout != 0 for timeout occurence
    1.85 +//      NULL and timeout == 0 for termination
    1.86 +//      NULL and timeout != 0 for timeout occurence
    1.87  
    1.88  typedef void *(*retrieve_next_sync_msg_t)(void *management, time_t *timeout);
    1.89