src/sync.h
changeset 1470 616d6a5d5539
parent 1467 ff7c60d14af0
child 1471 7b4a5322de16
     1.1 --- a/src/sync.h	Thu Dec 08 00:51:59 2016 +0100
     1.2 +++ b/src/sync.h	Thu Dec 08 10:14:23 2016 +0100
     1.3 @@ -1,60 +1,13 @@
     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 @@ -74,12 +27,22 @@
    1.70  typedef PEP_STATUS (*messageToSend_t)(void *obj, message *msg);
    1.71  
    1.72  typedef enum _sync_handshake_signal {
    1.73 -    SYNC_HANDSHAKE_DISMISS_DIALOG = 0,
    1.74 -    SYNC_HANDSHAKE_SHOW_DIALOG = 1,
    1.75 -    SYNC_HANDSHAKE_SUCCESS = 2,
    1.76 -    SYNC_HANDSHAKE_FAILURE = 3,
    1.77 -    SYNC_DEVICE_ADDED = 4,
    1.78 -    SYNC_GROUP_CREATED = 5
    1.79 +    SYNC_HANDSHAKE_UNDEFINED = 0,
    1.80 +
    1.81 +    // request show handshake dialog
    1.82 +    SYNC_HANDSHAKE_INIT_ADD_OUR_DEVICE,
    1.83 +    SYNC_HANDSHAKE_INIT_ADD_OTHER_DEVICE,
    1.84 +    SYNC_HANDSHAKE_INIT_FORM_GROUP,
    1.85 +
    1.86 +    // handshake process was cancelled
    1.87 +    SYNC_HANDSHAKE_CANCELED,
    1.88 +
    1.89 +    // handshake accepted by user
    1.90 +    SYNC_HANDSHAKE_ACCEPTED_DEVICE_ADDED,
    1.91 +    SYNC_HANDSHAKE_ACCEPTED_GROUP_CREATED,
    1.92 +
    1.93 +    // handshake was rejected by user
    1.94 +    SYNC_HANDSHAKE_REJECTED
    1.95  } sync_handshake_signal;
    1.96  
    1.97  // notifyHandshake() - notify UI about sync handshaking process
    1.98 @@ -136,16 +99,16 @@
    1.99  typedef int (*inject_sync_msg_t)(void *msg, void *management);
   1.100  
   1.101  
   1.102 -// retrieve_next_sync_msg - retrieve next sync message
   1.103 +// retrieve_next_sync_msg - receive next sync message
   1.104  //
   1.105  //  parameters:
   1.106  //      management (in)     application defined
   1.107 -//      timeout (in,out)    do not wait longer than timeout for message (seconds)
   1.108 +//      timeout (in,out)    do not wait longer than timeout for message
   1.109  //
   1.110  //  return value:
   1.111  //      next message or :
   1.112 -//      NULL and timeout == 0 for termination
   1.113 -//      NULL and timeout != 0 for timeout occurence
   1.114 +//      NULL + timeout == 0 for termination
   1.115 +//      NULL + timeout != 0 for timeout occurence
   1.116  
   1.117  typedef void *(*retrieve_next_sync_msg_t)(void *management, time_t *timeout);
   1.118