src/sync.h
author Edouard Tisserant <edouard@pep-project.org>
Sat, 26 Nov 2016 03:54:06 +0100
branchENGINE-133
changeset 1445 5d233bcdde76
parent 1236 991afc1aa2a1
child 1459 ab329d7db8d7
permissions -rw-r--r--
ENGINE-133 added timeout in sync state machine, relying on callback sync message retrieve timeout - adapters need update
     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 //      timeout (in,out)    do not wait longer than timeout for message
    88 //
    89 //  return value:
    90 //      next message or :
    91 //      NULL + timeout == 0 for termination
    92 //      NULL + timeout != 0 for timeout occurence
    93 
    94 typedef void *(*retrieve_next_sync_msg_t)(void *management, time_t *timeout);
    95 
    96 
    97 // register_sync_callbacks() - register adapter's callbacks
    98 //
    99 //  parameters:
   100 //      session (in)                session where to store obj handle
   101 //      obj (in)                    object handle (implementation defined)
   102 //      messageToSend (in)          callback for sending message
   103 //      showHandshake (in)          callback for doing the handshake
   104 //      retrieve_next_sync_msg (in) callback for receiving sync messages
   105 //
   106 //  return value:
   107 //      PEP_STATUS_OK or any other value on errror
   108 //
   109 //  caveat:
   110 //      call that BEFORE you're using any other part of the engine
   111 
   112 DYNAMIC_API PEP_STATUS register_sync_callbacks(
   113         PEP_SESSION session,
   114         void *obj,
   115         messageToSend_t messageToSend,
   116         showHandshake_t showHandshake,
   117         inject_sync_msg_t inject_sync_msg,
   118         retrieve_next_sync_msg_t retrieve_next_sync_msg
   119     );
   120 
   121 // attach_sync_session() - attach session to a session running keysync state machine 
   122 //
   123 //  parameters:
   124 //      session (in)                session to attach
   125 //      sync_session (in)           session running keysync
   126 //
   127 //  return value:
   128 //      PEP_STATUS_OK or any other value on errror
   129 //
   130 //  caveat:
   131 //      register_sync_callbacks must have been called on sync_session
   132 //      call that BEFORE you're using that session in any other part of the engine
   133 
   134 DYNAMIC_API PEP_STATUS attach_sync_session(
   135         PEP_SESSION session,
   136         PEP_SESSION sync_session
   137     );
   138 
   139 // detach_sync_session() - detach previously attached sync session
   140 //
   141 //  parameters:
   142 //      session (in)                session to detach 
   143 
   144 DYNAMIC_API PEP_STATUS detach_sync_session(PEP_SESSION session);
   145 
   146 // unregister_sync_callbacks() - unregister adapter's callbacks
   147 //
   148 //  parameters:
   149 //      session (in)                session to unregister
   150 
   151 DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
   152 
   153 // do_sync_protocol() - function to be run on an extra thread
   154 //
   155 //  parameters:
   156 //      session                 pEp session to use
   157 //      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
   158 //                              which returns at least a valid address field in
   159 //                              the identity struct
   160 //      management              management data to give to keymanagement
   161 //                              (implementation defined)
   162 //
   163 //  return value:
   164 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   165 //      value on failure
   166 //
   167 //  caveat:
   168 //      to ensure proper working of this library, a thread has to be started
   169 //      with this function immediately after initialization
   170 //      do_keymanagement() calls retrieve_next_identity(management)
   171 
   172 DYNAMIC_API PEP_STATUS do_sync_protocol(
   173         PEP_SESSION session,
   174         void *management
   175     );
   176 
   177 // free_sync_msg() - free sync_msg_t struct when not passed to do_sync_protocol  
   178 //
   179 //  parameters:
   180 //      sync_msg (in)            pointer to sync_msg_t struct to free
   181 
   182 DYNAMIC_API void free_sync_msg(sync_msg_t *sync_msg);
   183 
   184 // decode_sync_msg() - decode sync message from PER into XER
   185 //
   186 //  parameters:
   187 //      data (in)               PER encoded data
   188 //      size (in)               size of PER encoded data
   189 //      text (out)              XER text of the same sync message
   190 
   191 DYNAMIC_API PEP_STATUS decode_sync_msg(
   192         const char *data,
   193         size_t size,
   194         char **text
   195     );
   196 
   197 
   198 // encode_sync_msg() - encode sync message from XER into PER
   199 //
   200 //  parameters:
   201 //      text (in)               string with XER text of the sync message
   202 //      data (out)              PER encoded data
   203 //      size (out)              size of PER encoded data
   204 
   205 DYNAMIC_API PEP_STATUS encode_sync_msg(
   206         const char *text,
   207         char **data,
   208         size_t *size
   209     );
   210 
   211 
   212 #ifdef __cplusplus
   213 }
   214 #endif
   215