src/sync.h
author Volker Birk <vb@pep.foundation>
Thu, 01 Sep 2016 22:47:08 +0200
branchkeysync
changeset 1116 c9a03f2423c1
parent 1043 f786ee22e281
child 1128 51ea505b60e6
permissions -rw-r--r--
decode_sync_msg() for debugging
     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         sync_handshake_result result
    65     );
    66 
    67 
    68 // inject_sync_msg - inject sync protocol message
    69 //
    70 //  parameters:
    71 //      msg (in)            message to inject
    72 //      management (in)     application defined
    73 //
    74 //  return value:
    75 //      0 if msg could be stored successfully or nonzero otherwise
    76 
    77 typedef int (*inject_sync_msg_t)(void *msg, void *management);
    78 
    79 
    80 // retrieve_next_sync_msg - receive next sync message
    81 //
    82 //  parameters:
    83 //      management (in)     application defined
    84 //
    85 //  return value:
    86 //      next message or NULL for termination
    87 
    88 typedef void *(*retrieve_next_sync_msg_t)(void *management);
    89 
    90 
    91 // register_sync_callbacks() - register adapter's callbacks
    92 //
    93 //  parameters:
    94 //      session (in)                session where to store obj handle
    95 //      obj (in)                    object handle (implementation defined)
    96 //      messageToSend (in)          callback for sending message
    97 //      showHandshake (in)          callback for doing the handshake
    98 //      retrieve_next_sync_msg (in) callback for receiving sync messages
    99 //
   100 //  return value:
   101 //      PEP_STATUS_OK or any other value on errror
   102 //
   103 //  caveat:
   104 //      call that BEFORE you're using any other part of the engine
   105 
   106 DYNAMIC_API PEP_STATUS register_sync_callbacks(
   107         PEP_SESSION session,
   108         void *obj,
   109         messageToSend_t messageToSend,
   110         showHandshake_t showHandshake,
   111         inject_sync_msg_t inject_sync_msg,
   112         retrieve_next_sync_msg_t retrieve_next_sync_msg
   113     );
   114 
   115 
   116 // unregister_sync_callbacks() - unregister adapter's callbacks
   117 //
   118 //  parameters:
   119 //      session (in)                session where to store obj handle
   120 
   121 DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
   122 
   123 
   124 // do_sync_protocol() - function to be run on an extra thread
   125 //
   126 //  parameters:
   127 //      session                 pEp session to use
   128 //      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
   129 //                              which returns at least a valid address field in
   130 //                              the identity struct
   131 //      management              management data to give to keymanagement
   132 //                              (implementation defined)
   133 //
   134 //  return value:
   135 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   136 //      value on failure
   137 //
   138 //  caveat:
   139 //      to ensure proper working of this library, a thread has to be started
   140 //      with this function immediately after initialization
   141 //      do_keymanagement() calls retrieve_next_identity(management)
   142 
   143 DYNAMIC_API PEP_STATUS do_sync_protocol(
   144         PEP_SESSION session,
   145         void *management
   146     );
   147 
   148 
   149 // decode_sync_msg() - decode sync message from PER into XER
   150 //
   151 //  parameters:
   152 //      data (in)               PER encoded data
   153 //      size (in)               size of PER encoded data
   154 //      text (out)              XER text of the same sync message
   155 
   156 DYNAMIC_API PEP_STATUS decode_sync_msg(
   157         const char *data,
   158         size_t size,
   159         char **text
   160     );
   161 
   162 
   163 #ifdef __cplusplus
   164 }
   165 #endif
   166