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