src/sync.h
author Edouard Tisserant <edouard@pep-project.org>
Sat, 24 Sep 2016 09:27:25 +0200
branchkeysync
changeset 1172 15a75c0cc78f
parent 1160 a176739cd3c3
child 1203 c463238a1942
permissions -rw-r--r--
Sync : changed sync queue payload type so that sync protocol can receive event such as keygen or decrypt failure asynchronously from other sessions. Fixed problem with ownership of payload leading to memory leak in some case.
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
vb@1043
   151
vb@1116
   152
// decode_sync_msg() - decode sync message from PER into XER
vb@1116
   153
//
vb@1116
   154
//  parameters:
vb@1116
   155
//      data (in)               PER encoded data
vb@1116
   156
//      size (in)               size of PER encoded data
vb@1116
   157
//      text (out)              XER text of the same sync message
vb@1116
   158
vb@1116
   159
DYNAMIC_API PEP_STATUS decode_sync_msg(
vb@1116
   160
        const char *data,
vb@1116
   161
        size_t size,
vb@1116
   162
        char **text
vb@1116
   163
    );
vb@1116
   164
vb@1116
   165
vb@1128
   166
// encode_sync_msg() - encode sync message from XER into PER
vb@1128
   167
//
vb@1128
   168
//  parameters:
vb@1128
   169
//      text (in)               string with XER text of the sync message
vb@1128
   170
//      data (out)              PER encoded data
vb@1128
   171
//      size (out)              size of PER encoded data
vb@1128
   172
vb@1128
   173
DYNAMIC_API PEP_STATUS encode_sync_msg(
vb@1128
   174
        const char *text,
vb@1128
   175
        char **data,
vb@1128
   176
        size_t *size
vb@1128
   177
    );
vb@1128
   178
vb@1128
   179
vb@572
   180
#ifdef __cplusplus
vb@572
   181
}
vb@572
   182
#endif
vb@572
   183