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