src/sync.h
author Volker Birk <vb@pep.foundation>
Thu, 08 Dec 2016 10:14:23 +0100
changeset 1470 616d6a5d5539
parent 1467 ff7c60d14af0
child 1471 7b4a5322de16
permissions -rw-r--r--
more options for sync_handshake_signal
vb@572
     1
#pragma once
vb@572
     2
vb@572
     3
#include "message.h"
vb@690
     4
#include "sync_fsm.h"
vb@572
     5
vb@1470
     6
vb@1470
     7
// this module is for being used WITHOUT the Transport API in transport.h
vb@1470
     8
// DO NOT USE IT WHEN USING Transport API!
vb@1470
     9
vb@1470
    10
vb@572
    11
#ifdef __cplusplus
vb@572
    12
extern "C" {
vb@572
    13
#endif
vb@572
    14
vb@1043
    15
// messageToSend() - send a message
vb@572
    16
//
vb@572
    17
//  parameters:
vb@599
    18
//      obj (in)        object handle (implementation defined)
vb@598
    19
//      msg (in)        message struct with message to send
vb@572
    20
//
vb@572
    21
//  return value:
vb@604
    22
//      PEP_STATUS_OK or any other value on error
vb@991
    23
//
vb@991
    24
//  caveat:
vb@991
    25
//      the ownership of msg goes to the callee
vb@572
    26
vb@991
    27
typedef PEP_STATUS (*messageToSend_t)(void *obj, message *msg);
vb@572
    28
edouard@1459
    29
typedef enum _sync_handshake_signal {
vb@1470
    30
    SYNC_HANDSHAKE_UNDEFINED = 0,
vb@1470
    31
vb@1470
    32
    // request show handshake dialog
vb@1470
    33
    SYNC_HANDSHAKE_INIT_ADD_OUR_DEVICE,
vb@1470
    34
    SYNC_HANDSHAKE_INIT_ADD_OTHER_DEVICE,
vb@1470
    35
    SYNC_HANDSHAKE_INIT_FORM_GROUP,
vb@1470
    36
vb@1470
    37
    // handshake process was cancelled
vb@1470
    38
    SYNC_HANDSHAKE_CANCELED,
vb@1470
    39
vb@1470
    40
    // handshake accepted by user
vb@1470
    41
    SYNC_HANDSHAKE_ACCEPTED_DEVICE_ADDED,
vb@1470
    42
    SYNC_HANDSHAKE_ACCEPTED_GROUP_CREATED,
vb@1470
    43
vb@1470
    44
    // handshake was rejected by user
vb@1470
    45
    SYNC_HANDSHAKE_REJECTED
edouard@1459
    46
} sync_handshake_signal;
vb@572
    47
edouard@1459
    48
// notifyHandshake() - notify UI about sync handshaking process
vb@572
    49
//
vb@572
    50
//  parameters:
vb@599
    51
//      obj (in)        object handle (implementation defined)
vb@1003
    52
//      me (in)         own identity
vb@572
    53
//      partner (in)    identity of partner
edouard@1459
    54
//      signal (in)     reason of the notification
vb@572
    55
//
vb@572
    56
//  return value:
vb@604
    57
//      PEP_STATUS_OK or any other value on error
vb@991
    58
//
vb@991
    59
//  caveat:
vb@991
    60
//      ownership of self and partner go to the callee
vb@572
    61
edouard@1459
    62
typedef PEP_STATUS (*notifyHandshake_t)(
vb@599
    63
        void *obj,
vb@1003
    64
        pEp_identity *me,
edouard@1459
    65
        pEp_identity *partner,
edouard@1459
    66
        sync_handshake_signal signal
vb@609
    67
    );
vb@609
    68
edouard@1459
    69
typedef enum _sync_handshake_result {
edouard@1459
    70
    SYNC_HANDSHAKE_CANCEL = -1,
edouard@1459
    71
    SYNC_HANDSHAKE_ACCEPTED = 0,
edouard@1459
    72
    SYNC_HANDSHAKE_REJECTED = 1
edouard@1459
    73
} sync_handshake_result;
vb@609
    74
vb@609
    75
// deliverHandshakeResult() - give the result of the handshake dialog
vb@609
    76
//
vb@609
    77
//  parameters:
vb@1043
    78
//      session (in)        session handle
vb@1043
    79
//      result (in)         handshake result
vb@609
    80
vb@679
    81
DYNAMIC_API PEP_STATUS deliverHandshakeResult(
vb@609
    82
        PEP_SESSION session,
edouard@1160
    83
        Identity partner,
vb@609
    84
        sync_handshake_result result
vb@572
    85
    );
vb@572
    86
edouard@1172
    87
// sync_msg_t - items queued for serialized handling by protocol engine
edouard@1172
    88
typedef struct _sync_msg_t sync_msg_t;
vb@572
    89
vb@1043
    90
// inject_sync_msg - inject sync protocol message
vb@1043
    91
//
vb@1043
    92
//  parameters:
vb@1043
    93
//      msg (in)            message to inject
vb@1043
    94
//      management (in)     application defined
vb@1043
    95
//
vb@1043
    96
//  return value:
vb@1043
    97
//      0 if msg could be stored successfully or nonzero otherwise
vb@1043
    98
vb@1043
    99
typedef int (*inject_sync_msg_t)(void *msg, void *management);
vb@1043
   100
vb@1043
   101
vb@1470
   102
// retrieve_next_sync_msg - receive next sync message
vb@1043
   103
//
vb@1043
   104
//  parameters:
vb@1043
   105
//      management (in)     application defined
vb@1470
   106
//      timeout (in,out)    do not wait longer than timeout for message
vb@1043
   107
//
vb@1043
   108
//  return value:
edouard@1445
   109
//      next message or :
vb@1470
   110
//      NULL + timeout == 0 for termination
vb@1470
   111
//      NULL + timeout != 0 for timeout occurence
vb@1043
   112
edouard@1445
   113
typedef void *(*retrieve_next_sync_msg_t)(void *management, time_t *timeout);
vb@1043
   114
vb@1043
   115
vb@572
   116
// register_sync_callbacks() - register adapter's callbacks
vb@572
   117
//
vb@572
   118
//  parameters:
vb@599
   119
//      session (in)                session where to store obj handle
edouard@1462
   120
//      management (in)             application defined
vb@599
   121
//      messageToSend (in)          callback for sending message
edouard@1462
   122
//      notifyHandshake (in)        callback for doing the handshake
vb@1043
   123
//      retrieve_next_sync_msg (in) callback for receiving sync messages
vb@572
   124
//
vb@572
   125
//  return value:
vb@572
   126
//      PEP_STATUS_OK or any other value on errror
vb@573
   127
//
vb@573
   128
//  caveat:
vb@573
   129
//      call that BEFORE you're using any other part of the engine
vb@572
   130
vb@572
   131
DYNAMIC_API PEP_STATUS register_sync_callbacks(
vb@599
   132
        PEP_SESSION session,
edouard@1462
   133
        void *management,
vb@597
   134
        messageToSend_t messageToSend,
edouard@1459
   135
        notifyHandshake_t notifyHandshake,
vb@1043
   136
        inject_sync_msg_t inject_sync_msg,
vb@1043
   137
        retrieve_next_sync_msg_t retrieve_next_sync_msg
vb@572
   138
    );
vb@572
   139
edouard@1236
   140
// attach_sync_session() - attach session to a session running keysync state machine 
edouard@1236
   141
//
edouard@1236
   142
//  parameters:
edouard@1236
   143
//      session (in)                session to attach
edouard@1236
   144
//      sync_session (in)           session running keysync
edouard@1236
   145
//
edouard@1236
   146
//  return value:
edouard@1236
   147
//      PEP_STATUS_OK or any other value on errror
edouard@1236
   148
//
edouard@1236
   149
//  caveat:
edouard@1236
   150
//      register_sync_callbacks must have been called on sync_session
edouard@1236
   151
//      call that BEFORE you're using that session in any other part of the engine
edouard@1236
   152
edouard@1236
   153
DYNAMIC_API PEP_STATUS attach_sync_session(
edouard@1236
   154
        PEP_SESSION session,
edouard@1236
   155
        PEP_SESSION sync_session
edouard@1236
   156
    );
edouard@1236
   157
edouard@1236
   158
// detach_sync_session() - detach previously attached sync session
edouard@1236
   159
//
edouard@1236
   160
//  parameters:
edouard@1236
   161
//      session (in)                session to detach 
edouard@1236
   162
edouard@1236
   163
DYNAMIC_API PEP_STATUS detach_sync_session(PEP_SESSION session);
vb@572
   164
vb@572
   165
// unregister_sync_callbacks() - unregister adapter's callbacks
vb@602
   166
//
vb@602
   167
//  parameters:
edouard@1236
   168
//      session (in)                session to unregister
vb@572
   169
vb@602
   170
DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
vb@572
   171
vb@1116
   172
// do_sync_protocol() - function to be run on an extra thread
vb@1043
   173
//
vb@1043
   174
//  parameters:
vb@1043
   175
//      session                 pEp session to use
vb@1043
   176
//      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
vb@1043
   177
//                              which returns at least a valid address field in
vb@1043
   178
//                              the identity struct
edouard@1462
   179
//      obj                     application defined sync object
vb@1043
   180
//
vb@1043
   181
//  return value:
vb@1043
   182
//      PEP_STATUS_OK if thread has to terminate successfully or any other
vb@1043
   183
//      value on failure
vb@1043
   184
//
vb@1043
   185
//  caveat:
vb@1043
   186
//      to ensure proper working of this library, a thread has to be started
vb@1043
   187
//      with this function immediately after initialization
vb@1043
   188
vb@1043
   189
DYNAMIC_API PEP_STATUS do_sync_protocol(
vb@1043
   190
        PEP_SESSION session,
edouard@1462
   191
        void *obj
vb@1043
   192
    );
vb@1043
   193
Edouard@1203
   194
// free_sync_msg() - free sync_msg_t struct when not passed to do_sync_protocol  
Edouard@1203
   195
//
Edouard@1203
   196
//  parameters:
Edouard@1203
   197
//      sync_msg (in)            pointer to sync_msg_t struct to free
Edouard@1203
   198
Edouard@1203
   199
DYNAMIC_API void free_sync_msg(sync_msg_t *sync_msg);
vb@1043
   200
vb@1116
   201
// decode_sync_msg() - decode sync message from PER into XER
vb@1116
   202
//
vb@1116
   203
//  parameters:
vb@1116
   204
//      data (in)               PER encoded data
vb@1116
   205
//      size (in)               size of PER encoded data
vb@1116
   206
//      text (out)              XER text of the same sync message
vb@1116
   207
vb@1116
   208
DYNAMIC_API PEP_STATUS decode_sync_msg(
vb@1116
   209
        const char *data,
vb@1116
   210
        size_t size,
vb@1116
   211
        char **text
vb@1116
   212
    );
vb@1116
   213
vb@1116
   214
vb@1128
   215
// encode_sync_msg() - encode sync message from XER into PER
vb@1128
   216
//
vb@1128
   217
//  parameters:
vb@1128
   218
//      text (in)               string with XER text of the sync message
vb@1128
   219
//      data (out)              PER encoded data
vb@1128
   220
//      size (out)              size of PER encoded data
vb@1128
   221
vb@1128
   222
DYNAMIC_API PEP_STATUS encode_sync_msg(
vb@1128
   223
        const char *text,
vb@1128
   224
        char **data,
vb@1128
   225
        size_t *size
vb@1128
   226
    );
vb@1128
   227
vb@1128
   228
vb@572
   229
#ifdef __cplusplus
vb@572
   230
}
vb@572
   231
#endif
vb@572
   232