src/sync.h
author Volker Birk <vb@pep.foundation>
Thu, 08 Dec 2016 10:00:52 +0100
branchENGINE-133
changeset 1469 43e45b53e5cb
parent 1462 b93663bfc7c6
child 1472 426533979556
permissions -rw-r--r--
handshaking nicer
     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 typedef enum _sync_handshake_signal {
    30     SYNC_HANDSHAKE_UNDEFINED = 0,
    31 
    32     // request show handshake dialog
    33     SYNC_HANDSHAKE_INIT_ADD_OUR_DEVICE,
    34     SYNC_HANDSHAKE_INIT_ADD_OTHER_DEVICE,
    35     SYNC_HANDSHAKE_INIT_FORM_GROUP,
    36 
    37     // handshake process was cancelled
    38     SYNC_HANDSHAKE_CANCELED,
    39 
    40     // handshake accepted by user
    41     SYNC_HANDSHAKE_ACCEPTED_DEVICE_ADDED,
    42     SYNC_HANDSHAKE_ACCEPTED_GROUP_CREATED,
    43 
    44     // handshake was rejected by user
    45     SYNC_HANDSHAKE_REJECTED
    46 } sync_handshake_signal;
    47 
    48 // notifyHandshake() - notify UI about sync handshaking process
    49 //
    50 //  parameters:
    51 //      obj (in)        object handle (implementation defined)
    52 //      me (in)         own identity
    53 //      partner (in)    identity of partner
    54 //      signal (in)     reason of the notification
    55 //
    56 //  return value:
    57 //      PEP_STATUS_OK or any other value on error
    58 //
    59 //  caveat:
    60 //      ownership of self and partner go to the callee
    61 
    62 typedef PEP_STATUS (*notifyHandshake_t)(
    63         void *obj,
    64         pEp_identity *me,
    65         pEp_identity *partner,
    66         sync_handshake_signal signal
    67     );
    68 
    69 typedef enum _sync_handshake_result {
    70     SYNC_HANDSHAKE_CANCEL = -1,
    71     SYNC_HANDSHAKE_ACCEPTED = 0,
    72     SYNC_HANDSHAKE_REJECTED = 1
    73 } sync_handshake_result;
    74 
    75 // deliverHandshakeResult() - give the result of the handshake dialog
    76 //
    77 //  parameters:
    78 //      session (in)        session handle
    79 //      result (in)         handshake result
    80 
    81 DYNAMIC_API PEP_STATUS deliverHandshakeResult(
    82         PEP_SESSION session,
    83         Identity partner,
    84         sync_handshake_result result
    85     );
    86 
    87 // sync_msg_t - items queued for serialized handling by protocol engine
    88 typedef struct _sync_msg_t sync_msg_t;
    89 
    90 // inject_sync_msg - inject sync protocol message
    91 //
    92 //  parameters:
    93 //      msg (in)            message to inject
    94 //      management (in)     application defined
    95 //
    96 //  return value:
    97 //      0 if msg could be stored successfully or nonzero otherwise
    98 
    99 typedef int (*inject_sync_msg_t)(void *msg, void *management);
   100 
   101 
   102 // retrieve_next_sync_msg - receive next sync message
   103 //
   104 //  parameters:
   105 //      management (in)     application defined
   106 //      timeout (in,out)    do not wait longer than timeout for message
   107 //
   108 //  return value:
   109 //      next message or :
   110 //      NULL + timeout == 0 for termination
   111 //      NULL + timeout != 0 for timeout occurence
   112 
   113 typedef void *(*retrieve_next_sync_msg_t)(void *management, time_t *timeout);
   114 
   115 
   116 // register_sync_callbacks() - register adapter's callbacks
   117 //
   118 //  parameters:
   119 //      session (in)                session where to store obj handle
   120 //      management (in)             application defined
   121 //      messageToSend (in)          callback for sending message
   122 //      notifyHandshake (in)        callback for doing the handshake
   123 //      retrieve_next_sync_msg (in) callback for receiving sync messages
   124 //
   125 //  return value:
   126 //      PEP_STATUS_OK or any other value on errror
   127 //
   128 //  caveat:
   129 //      call that BEFORE you're using any other part of the engine
   130 
   131 DYNAMIC_API PEP_STATUS register_sync_callbacks(
   132         PEP_SESSION session,
   133         void *management,
   134         messageToSend_t messageToSend,
   135         notifyHandshake_t notifyHandshake,
   136         inject_sync_msg_t inject_sync_msg,
   137         retrieve_next_sync_msg_t retrieve_next_sync_msg
   138     );
   139 
   140 // attach_sync_session() - attach session to a session running keysync state machine 
   141 //
   142 //  parameters:
   143 //      session (in)                session to attach
   144 //      sync_session (in)           session running keysync
   145 //
   146 //  return value:
   147 //      PEP_STATUS_OK or any other value on errror
   148 //
   149 //  caveat:
   150 //      register_sync_callbacks must have been called on sync_session
   151 //      call that BEFORE you're using that session in any other part of the engine
   152 
   153 DYNAMIC_API PEP_STATUS attach_sync_session(
   154         PEP_SESSION session,
   155         PEP_SESSION sync_session
   156     );
   157 
   158 // detach_sync_session() - detach previously attached sync session
   159 //
   160 //  parameters:
   161 //      session (in)                session to detach 
   162 
   163 DYNAMIC_API PEP_STATUS detach_sync_session(PEP_SESSION session);
   164 
   165 // unregister_sync_callbacks() - unregister adapter's callbacks
   166 //
   167 //  parameters:
   168 //      session (in)                session to unregister
   169 
   170 DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
   171 
   172 // do_sync_protocol() - function to be run on an extra thread
   173 //
   174 //  parameters:
   175 //      session                 pEp session to use
   176 //      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
   177 //                              which returns at least a valid address field in
   178 //                              the identity struct
   179 //      obj                     application defined sync object
   180 //
   181 //  return value:
   182 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   183 //      value on failure
   184 //
   185 //  caveat:
   186 //      to ensure proper working of this library, a thread has to be started
   187 //      with this function immediately after initialization
   188 
   189 DYNAMIC_API PEP_STATUS do_sync_protocol(
   190         PEP_SESSION session,
   191         void *obj
   192     );
   193 
   194 // free_sync_msg() - free sync_msg_t struct when not passed to do_sync_protocol  
   195 //
   196 //  parameters:
   197 //      sync_msg (in)            pointer to sync_msg_t struct to free
   198 
   199 DYNAMIC_API void free_sync_msg(sync_msg_t *sync_msg);
   200 
   201 // decode_sync_msg() - decode sync message from PER into XER
   202 //
   203 //  parameters:
   204 //      data (in)               PER encoded data
   205 //      size (in)               size of PER encoded data
   206 //      text (out)              XER text of the same sync message
   207 
   208 DYNAMIC_API PEP_STATUS decode_sync_msg(
   209         const char *data,
   210         size_t size,
   211         char **text
   212     );
   213 
   214 
   215 // encode_sync_msg() - encode sync message from XER into PER
   216 //
   217 //  parameters:
   218 //      text (in)               string with XER text of the sync message
   219 //      data (out)              PER encoded data
   220 //      size (out)              size of PER encoded data
   221 
   222 DYNAMIC_API PEP_STATUS encode_sync_msg(
   223         const char *text,
   224         char **data,
   225         size_t *size
   226     );
   227 
   228 
   229 #ifdef __cplusplus
   230 }
   231 #endif
   232