src/sync.h
author Edouard Tisserant
Tue, 27 Sep 2016 21:51:55 +0200
branchkeysync
changeset 1203 c463238a1942
parent 1172 15a75c0cc78f
child 1236 991afc1aa2a1
permissions -rw-r--r--
Added free_sync_msg, so that adapter can purge sync queue
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@572
     6
vb@572
     7
// this module is for being used WITHOUT the Transport API in transport.h
vb@572
     8
// DO NOT USE IT WHEN USING Transport API!
vb@572
     9
vb@572
    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
vb@572
    29
vb@572
    30
typedef enum _sync_handshake_result {
vb@572
    31
    SYNC_HANDSHAKE_CANCEL = -1,
vb@572
    32
    SYNC_HANDSHAKE_ACCEPTED = 0,
vb@572
    33
    SYNC_HANDSHAKE_REJECTED = 1
vb@572
    34
} sync_handshake_result;
vb@572
    35
vb@609
    36
// showHandshake() - do a handshake by showing the handshake dialog
vb@572
    37
//
vb@572
    38
//  parameters:
vb@599
    39
//      obj (in)        object handle (implementation defined)
vb@1003
    40
//      me (in)         own identity
vb@572
    41
//      partner (in)    identity of partner
vb@572
    42
//
vb@572
    43
//  return value:
vb@604
    44
//      PEP_STATUS_OK or any other value on error
vb@991
    45
//
vb@991
    46
//  caveat:
vb@991
    47
//      ownership of self and partner go to the callee
vb@572
    48
vb@604
    49
typedef PEP_STATUS (*showHandshake_t)(
vb@599
    50
        void *obj,
vb@1003
    51
        pEp_identity *me,
vb@991
    52
        pEp_identity *partner
vb@609
    53
    );
vb@609
    54
vb@609
    55
vb@609
    56
// deliverHandshakeResult() - give the result of the handshake dialog
vb@609
    57
//
vb@609
    58
//  parameters:
vb@1043
    59
//      session (in)        session handle
vb@1043
    60
//      result (in)         handshake result
vb@609
    61
vb@679
    62
DYNAMIC_API PEP_STATUS deliverHandshakeResult(
vb@609
    63
        PEP_SESSION session,
edouard@1160
    64
        Identity partner,
vb@609
    65
        sync_handshake_result result
vb@572
    66
    );
vb@572
    67
edouard@1172
    68
// sync_msg_t - items queued for serialized handling by protocol engine
edouard@1172
    69
typedef struct _sync_msg_t sync_msg_t;
vb@572
    70
vb@1043
    71
// inject_sync_msg - inject sync protocol message
vb@1043
    72
//
vb@1043
    73
//  parameters:
vb@1043
    74
//      msg (in)            message to inject
vb@1043
    75
//      management (in)     application defined
vb@1043
    76
//
vb@1043
    77
//  return value:
vb@1043
    78
//      0 if msg could be stored successfully or nonzero otherwise
vb@1043
    79
vb@1043
    80
typedef int (*inject_sync_msg_t)(void *msg, void *management);
vb@1043
    81
vb@1043
    82
vb@1043
    83
// retrieve_next_sync_msg - receive next sync message
vb@1043
    84
//
vb@1043
    85
//  parameters:
vb@1043
    86
//      management (in)     application defined
vb@1043
    87
//
vb@1043
    88
//  return value:
vb@1043
    89
//      next message or NULL for termination
vb@1043
    90
vb@1043
    91
typedef void *(*retrieve_next_sync_msg_t)(void *management);
vb@1043
    92
vb@1043
    93
vb@572
    94
// register_sync_callbacks() - register adapter's callbacks
vb@572
    95
//
vb@572
    96
//  parameters:
vb@599
    97
//      session (in)                session where to store obj handle
vb@599
    98
//      obj (in)                    object handle (implementation defined)
vb@599
    99
//      messageToSend (in)          callback for sending message
vb@572
   100
//      showHandshake (in)          callback for doing the handshake
vb@1043
   101
//      retrieve_next_sync_msg (in) callback for receiving sync messages
vb@572
   102
//
vb@572
   103
//  return value:
vb@572
   104
//      PEP_STATUS_OK or any other value on errror
vb@573
   105
//
vb@573
   106
//  caveat:
vb@573
   107
//      call that BEFORE you're using any other part of the engine
vb@572
   108
vb@572
   109
DYNAMIC_API PEP_STATUS register_sync_callbacks(
vb@599
   110
        PEP_SESSION session,
vb@599
   111
        void *obj,
vb@597
   112
        messageToSend_t messageToSend,
vb@1043
   113
        showHandshake_t showHandshake,
vb@1043
   114
        inject_sync_msg_t inject_sync_msg,
vb@1043
   115
        retrieve_next_sync_msg_t retrieve_next_sync_msg
vb@572
   116
    );
vb@572
   117
vb@572
   118
vb@572
   119
// unregister_sync_callbacks() - unregister adapter's callbacks
vb@602
   120
//
vb@602
   121
//  parameters:
vb@602
   122
//      session (in)                session where to store obj handle
vb@572
   123
vb@602
   124
DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
vb@572
   125
vb@572
   126
vb@1116
   127
// do_sync_protocol() - function to be run on an extra thread
vb@1043
   128
//
vb@1043
   129
//  parameters:
vb@1043
   130
//      session                 pEp session to use
vb@1043
   131
//      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
vb@1043
   132
//                              which returns at least a valid address field in
vb@1043
   133
//                              the identity struct
vb@1043
   134
//      management              management data to give to keymanagement
vb@1043
   135
//                              (implementation defined)
vb@1043
   136
//
vb@1043
   137
//  return value:
vb@1043
   138
//      PEP_STATUS_OK if thread has to terminate successfully or any other
vb@1043
   139
//      value on failure
vb@1043
   140
//
vb@1043
   141
//  caveat:
vb@1043
   142
//      to ensure proper working of this library, a thread has to be started
vb@1043
   143
//      with this function immediately after initialization
vb@1043
   144
//      do_keymanagement() calls retrieve_next_identity(management)
vb@1043
   145
vb@1043
   146
DYNAMIC_API PEP_STATUS do_sync_protocol(
vb@1043
   147
        PEP_SESSION session,
vb@1043
   148
        void *management
vb@1043
   149
    );
vb@1043
   150
Edouard@1203
   151
// free_sync_msg() - free sync_msg_t struct when not passed to do_sync_protocol  
Edouard@1203
   152
//
Edouard@1203
   153
//  parameters:
Edouard@1203
   154
//      sync_msg (in)            pointer to sync_msg_t struct to free
Edouard@1203
   155
Edouard@1203
   156
DYNAMIC_API void free_sync_msg(sync_msg_t *sync_msg);
vb@1043
   157
vb@1116
   158
// decode_sync_msg() - decode sync message from PER into XER
vb@1116
   159
//
vb@1116
   160
//  parameters:
vb@1116
   161
//      data (in)               PER encoded data
vb@1116
   162
//      size (in)               size of PER encoded data
vb@1116
   163
//      text (out)              XER text of the same sync message
vb@1116
   164
vb@1116
   165
DYNAMIC_API PEP_STATUS decode_sync_msg(
vb@1116
   166
        const char *data,
vb@1116
   167
        size_t size,
vb@1116
   168
        char **text
vb@1116
   169
    );
vb@1116
   170
vb@1116
   171
vb@1128
   172
// encode_sync_msg() - encode sync message from XER into PER
vb@1128
   173
//
vb@1128
   174
//  parameters:
vb@1128
   175
//      text (in)               string with XER text of the sync message
vb@1128
   176
//      data (out)              PER encoded data
vb@1128
   177
//      size (out)              size of PER encoded data
vb@1128
   178
vb@1128
   179
DYNAMIC_API PEP_STATUS encode_sync_msg(
vb@1128
   180
        const char *text,
vb@1128
   181
        char **data,
vb@1128
   182
        size_t *size
vb@1128
   183
    );
vb@1128
   184
vb@1128
   185
vb@572
   186
#ifdef __cplusplus
vb@572
   187
}
vb@572
   188
#endif
vb@572
   189