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