src/sync_api.h
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Thu, 04 Jun 2020 11:18:45 +0200
changeset 4729 3df9a2a67597
parent 4383 2df7158f98a1
child 4472 07223ba65c17
child 4776 e476fbd37bd4
permissions -rw-r--r--
forgot test files
krista@2271
     1
// This file is under GNU General Public License 3.0
krista@2271
     2
// see LICENSE.txt
krista@2271
     3
krista@2271
     4
#pragma once
krista@2271
     5
vb@2839
     6
krista@2271
     7
#include "message.h"
vb@2839
     8
krista@2271
     9
krista@2271
    10
#ifdef __cplusplus
krista@2271
    11
extern "C" {
krista@2271
    12
#endif
krista@2271
    13
vb@2836
    14
vb@2830
    15
typedef enum _sync_handshake_signal {
vb@2830
    16
    SYNC_NOTIFY_UNDEFINED = 0,
vb@2830
    17
vb@2830
    18
    // request show handshake dialog
vb@3524
    19
    SYNC_NOTIFY_INIT_ADD_OUR_DEVICE = 1,
vb@3524
    20
    SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE = 2,
vb@3524
    21
    SYNC_NOTIFY_INIT_FORM_GROUP = 3,
vb@3524
    22
    // SYNC_NOTIFY_INIT_MOVE_OUR_DEVICE = 4,
vb@2830
    23
vb@2830
    24
    // handshake process timed out
vb@3524
    25
    SYNC_NOTIFY_TIMEOUT = 5,
vb@2830
    26
vb@2830
    27
    // handshake accepted by user
vb@3524
    28
    SYNC_NOTIFY_ACCEPTED_DEVICE_ADDED = 6,
vb@3524
    29
    SYNC_NOTIFY_ACCEPTED_GROUP_CREATED = 7,
vb@4167
    30
    SYNC_NOTIFY_ACCEPTED_DEVICE_ACCEPTED = 8,
vb@2830
    31
vb@2830
    32
    // handshake dialog must be closed
vb@4167
    33
    // SYNC_NOTIFY_OVERTAKEN = 9,
vb@3525
    34
Hussein@4162
    35
    // forming group
vb@4167
    36
    // SYNC_NOTIFY_FORMING_GROUP = 10,
vb@3971
    37
Hussein@4162
    38
    // notification of actual group status
vb@3525
    39
    SYNC_NOTIFY_SOLE = 254,
vb@3525
    40
    SYNC_NOTIFY_IN_GROUP = 255
vb@2830
    41
} sync_handshake_signal;
vb@2830
    42
krista@2271
    43
krista@2271
    44
// notifyHandshake() - notify UI about sync handshaking process
krista@2271
    45
//
krista@2271
    46
//  parameters:
krista@2271
    47
//      obj (in)        object handle (implementation defined)
krista@2271
    48
//      me (in)         own identity
krista@2271
    49
//      partner (in)    identity of partner
krista@2271
    50
//      signal (in)     reason of the notification
krista@2271
    51
//
krista@2271
    52
//  return value:
krista@2271
    53
//      PEP_STATUS_OK or any other value on error
krista@2271
    54
//
krista@2271
    55
//  caveat:
krista@2271
    56
//      ownership of self and partner go to the callee
krista@2271
    57
krista@2271
    58
typedef PEP_STATUS (*notifyHandshake_t)(
krista@2271
    59
        pEp_identity *me,
krista@2271
    60
        pEp_identity *partner,
krista@2271
    61
        sync_handshake_signal signal
krista@2271
    62
    );
krista@2271
    63
krista@2271
    64
typedef enum _sync_handshake_result {
krista@2271
    65
    SYNC_HANDSHAKE_CANCEL = -1,
krista@2271
    66
    SYNC_HANDSHAKE_ACCEPTED = 0,
krista@2271
    67
    SYNC_HANDSHAKE_REJECTED = 1
krista@2271
    68
} sync_handshake_result;
krista@2271
    69
vb@3383
    70
// deliverHandshakeResult() - provide the result of the handshake dialog
krista@2271
    71
//
krista@2271
    72
//  parameters:
vb@3407
    73
//      session (in)            session handle
vb@3407
    74
//      result (in)             handshake result
vb@3407
    75
//      identities_sharing (in) own_identities sharing data in this group
vb@3407
    76
//
vb@3407
    77
//  caveat:
vb@3407
    78
//      identities_sharing may be NULL; in this case all identities are sharing
vb@3407
    79
//      data in the group
vb@3407
    80
//      identities_sharing may only contain own identities
krista@2271
    81
krista@2271
    82
DYNAMIC_API PEP_STATUS deliverHandshakeResult(
krista@2271
    83
        PEP_SESSION session,
vb@3407
    84
        sync_handshake_result result,
vb@3407
    85
        const identity_list *identities_sharing
krista@2271
    86
    );
krista@2271
    87
krista@2271
    88
vb@2839
    89
// retrieve_next_sync_event - receive next sync event
krista@2271
    90
//
krista@2271
    91
//  parameters:
vb@2850
    92
//      management (in)     application defined; usually a locked queue
vb@2909
    93
//      threshold (in)      threshold in seconds for timeout
krista@2271
    94
//
krista@2271
    95
//  return value:
vb@2839
    96
//      next event
vb@2912
    97
//
vb@2912
    98
//  caveat:
vb@2912
    99
//      an implementation of retrieve_next_sync_event must return
vb@2912
   100
//      new_sync_timeout_event() in case of timeout
krista@2271
   101
vb@2909
   102
typedef SYNC_EVENT (*retrieve_next_sync_event_t)(void *management,
vb@3108
   103
        unsigned threshold);
krista@2271
   104
krista@2271
   105
krista@2271
   106
// register_sync_callbacks() - register adapter's callbacks
krista@2271
   107
//
krista@2271
   108
//  parameters:
vb@4382
   109
//      session (in)                    session where to register callbacks
vb@2850
   110
//      management (in)                 application defined; usually a locked queue
vb@2839
   111
//      notifyHandshake (in)            callback for doing the handshake
vb@2839
   112
//      retrieve_next_sync_event (in)   callback for receiving sync event
krista@2271
   113
//
krista@2271
   114
//  return value:
krista@2271
   115
//      PEP_STATUS_OK or any other value on errror
krista@2271
   116
//
krista@2271
   117
//  caveat:
vb@4379
   118
//      use this function in an adapter where you're processing the sync
vb@4379
   119
//      state machine
vb@4379
   120
//
vb@4379
   121
//      implement start_sync() in this adapter and provide it to the
vb@4379
   122
//      application, so it can trigger startup
vb@4379
   123
//
vb@4380
   124
//      in case of parallelization start_sync() and register_sync_callbacks()
vb@4380
   125
//      will run in parallel
vb@4380
   126
//
vb@4379
   127
//      do not return from start_sync() before register_sync_callbacks() was
vb@4379
   128
//      executed
vb@4381
   129
//
vb@4381
   130
//      when execution of the sync state machine ends a call to
vb@4383
   131
//      unregister_sync_callbacks() is recommended
krista@2271
   132
krista@2271
   133
DYNAMIC_API PEP_STATUS register_sync_callbacks(
krista@2271
   134
        PEP_SESSION session,
krista@2271
   135
        void *management,
krista@2271
   136
        notifyHandshake_t notifyHandshake,
vb@2839
   137
        retrieve_next_sync_event_t retrieve_next_sync_event
krista@2271
   138
    );
krista@2271
   139
krista@2271
   140
DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
krista@2271
   141
vb@2839
   142
krista@2271
   143
// do_sync_protocol() - function to be run on an extra thread
krista@2271
   144
//
krista@2271
   145
//  parameters:
krista@2271
   146
//      session                 pEp session to use
krista@2271
   147
//      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
krista@2271
   148
//                              which returns at least a valid address field in
krista@2271
   149
//                              the identity struct
krista@2271
   150
//      obj                     application defined sync object
krista@2271
   151
//
krista@2271
   152
//  return value:
krista@2271
   153
//      PEP_STATUS_OK if thread has to terminate successfully or any other
krista@2271
   154
//      value on failure
krista@2271
   155
krista@2271
   156
DYNAMIC_API PEP_STATUS do_sync_protocol(
krista@2271
   157
        PEP_SESSION session,
krista@2271
   158
        void *obj
krista@2271
   159
    );
krista@2271
   160
krista@2271
   161
vb@2899
   162
// do_sync_protocol_step() - function for single threaded implementations
vb@2899
   163
//
vb@2899
   164
//  parameters:
vb@2899
   165
//      session                 pEp session to use
vb@2899
   166
//      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
vb@2899
   167
//                              which returns at least a valid address field in
vb@2899
   168
//                              the identity struct
vb@2899
   169
//      obj                     application defined sync object
vb@2899
   170
//      event                   Sync event to process
vb@2899
   171
vb@2899
   172
DYNAMIC_API PEP_STATUS do_sync_protocol_step(
vb@2899
   173
        PEP_SESSION session,
vb@2899
   174
        void *obj,
vb@2899
   175
        SYNC_EVENT event
vb@2899
   176
    );
vb@2899
   177
vb@2899
   178
vb@2899
   179
// is_sync_thread() - determine if this is sync thread's session
vb@2899
   180
//
vb@2899
   181
//  paramters:
vb@3406
   182
//      session (in)            pEp session to test
vb@2899
   183
//
vb@2899
   184
//  return value:
vb@2899
   185
//      true if this is sync thread's session, false otherwise
vb@2899
   186
vb@2899
   187
DYNAMIC_API bool is_sync_thread(PEP_SESSION session);
vb@2899
   188
vb@2899
   189
vb@2911
   190
// new_sync_timeout_event() - create a Sync timeout event
vb@2911
   191
//
vb@2911
   192
//  return value:
vb@2911
   193
//      returns a new Sync timeout event, or NULL on failure
vb@2911
   194
vb@2911
   195
DYNAMIC_API SYNC_EVENT new_sync_timeout_event();
vb@2911
   196
vb@2911
   197
vb@3406
   198
// enter_device_group() - enter a device group
vb@3406
   199
//
vb@3406
   200
//  parameters:
vb@3406
   201
//      session (in)            pEp session
vb@3406
   202
//      identities_sharing (in) own_identities sharing data in this group
vb@3406
   203
//
vb@3406
   204
//  caveat:
vb@3406
   205
//      identities_sharing may be NULL; in this case all identities are sharing
vb@3406
   206
//      data in the group
vb@3406
   207
//      identities_sharing may only contain own identities
vb@3406
   208
//
vb@3406
   209
//      this call can be repeated if sharing information changes
vb@3406
   210
vb@3406
   211
DYNAMIC_API PEP_STATUS enter_device_group(
vb@3406
   212
        PEP_SESSION session,
vb@3406
   213
        const identity_list *identities_sharing
vb@3406
   214
    );
vb@3406
   215
vb@3406
   216
krista@4243
   217
// disable_sync() - leave a device group and shutdown sync
krista@4243
   218
//
krista@4243
   219
//  parameters:
krista@4243
   220
//      session                 pEp session
krista@4243
   221
krista@4243
   222
PEP_STATUS disable_sync(PEP_SESSION session);
krista@4243
   223
vb@4375
   224
krista@4243
   225
// leave_device_group() - Issue a group key reset request and 
krista@4325
   226
// leave the device group, shutting down sync 
vb@3406
   227
//
vb@3406
   228
//  parameters:
vb@3406
   229
//      session                 pEp session
vb@3406
   230
vb@3406
   231
DYNAMIC_API PEP_STATUS leave_device_group(PEP_SESSION session);
vb@3406
   232
vb@4375
   233
vb@3996
   234
// enable_identity_for_sync() - enable sync for this identity
vb@3996
   235
//  parameters:
vb@3996
   236
//      session                 pEp session
vb@4375
   237
//      ident                   own identity to enable
vb@3996
   238
vb@3996
   239
DYNAMIC_API PEP_STATUS enable_identity_for_sync(PEP_SESSION session,
vb@3996
   240
        pEp_identity *ident);
vb@3996
   241
vb@3996
   242
vb@3996
   243
// disable_identity_for_sync() - disable sync for this identity
vb@3996
   244
//  parameters:
vb@3996
   245
//      session                 pEp session
vb@4375
   246
//      ident                   own identity to disable
vb@3996
   247
vb@3996
   248
DYNAMIC_API PEP_STATUS disable_identity_for_sync(PEP_SESSION session,
vb@3996
   249
        pEp_identity *ident);
vb@3996
   250
vb@4240
   251
krista@2271
   252
#ifdef __cplusplus
krista@2271
   253
}
krista@2271
   254
#endif