src/sync_api.h
author us@chu.huenfield.org
Tue, 25 Dec 2018 14:46:45 +0100
branchsync
changeset 3209 c15b4ca2b52a
parent 3108 f6f11b35af07
child 3383 da42a8ac645f
permissions -rw-r--r--
Replace use of Sequoia's backend with a custom key store.

- Sequoia's key store doesn't meet pep's needs (in particular, the
ability to search on a key's user id) and trying to shoehorn pep's
needs onto Sequoia's key store abstractions is just introducing
overhead with no appreciable gain in functionality.

- This patch changes the Sequoia backend to use a local sqlite
database to store the public keys.
     1 // This file is under GNU General Public License 3.0
     2 // see LICENSE.txt
     3 
     4 #pragma once
     5 
     6 
     7 #include "message.h"
     8 
     9 
    10 #ifdef __cplusplus
    11 extern "C" {
    12 #endif
    13 
    14 
    15 typedef enum _sync_handshake_signal {
    16     SYNC_NOTIFY_UNDEFINED = 0,
    17 
    18     // request show handshake dialog
    19     SYNC_NOTIFY_INIT_ADD_OUR_DEVICE,
    20     SYNC_NOTIFY_INIT_ADD_OTHER_DEVICE,
    21     SYNC_NOTIFY_INIT_FORM_GROUP,
    22     SYNC_NOTIFY_INIT_MOVE_OUR_DEVICE,
    23 
    24     // handshake process timed out
    25     SYNC_NOTIFY_TIMEOUT,
    26 
    27     // handshake accepted by user
    28     SYNC_NOTIFY_ACCEPTED_DEVICE_ADDED,
    29     SYNC_NOTIFY_ACCEPTED_GROUP_CREATED,
    30     SYNC_NOTIFY_ACCEPTED_DEVICE_MOVED,
    31 
    32     // handshake dialog must be closed
    33     SYNC_NOTIFY_OVERTAKEN
    34 } sync_handshake_signal;
    35 
    36 
    37 // notifyHandshake() - notify UI about sync handshaking process
    38 //
    39 //  parameters:
    40 //      obj (in)        object handle (implementation defined)
    41 //      me (in)         own identity
    42 //      partner (in)    identity of partner
    43 //      signal (in)     reason of the notification
    44 //
    45 //  return value:
    46 //      PEP_STATUS_OK or any other value on error
    47 //
    48 //  caveat:
    49 //      ownership of self and partner go to the callee
    50 
    51 typedef PEP_STATUS (*notifyHandshake_t)(
    52         pEp_identity *me,
    53         pEp_identity *partner,
    54         sync_handshake_signal signal
    55     );
    56 
    57 typedef enum _sync_handshake_result {
    58     SYNC_HANDSHAKE_CANCEL = -1,
    59     SYNC_HANDSHAKE_ACCEPTED = 0,
    60     SYNC_HANDSHAKE_REJECTED = 1
    61 } sync_handshake_result;
    62 
    63 // deliverHandshakeResult() - give the result of the handshake dialog
    64 //
    65 //  parameters:
    66 //      session (in)        session handle
    67 //      result (in)         handshake result
    68 
    69 DYNAMIC_API PEP_STATUS deliverHandshakeResult(
    70         PEP_SESSION session,
    71         pEp_identity *partner,
    72         sync_handshake_result result
    73     );
    74 
    75 
    76 // retrieve_next_sync_event - receive next sync event
    77 //
    78 //  parameters:
    79 //      management (in)     application defined; usually a locked queue
    80 //      threshold (in)      threshold in seconds for timeout
    81 //
    82 //  return value:
    83 //      next event
    84 //
    85 //  caveat:
    86 //      an implementation of retrieve_next_sync_event must return
    87 //      new_sync_timeout_event() in case of timeout
    88 
    89 typedef SYNC_EVENT (*retrieve_next_sync_event_t)(void *management,
    90         unsigned threshold);
    91 
    92 
    93 // register_sync_callbacks() - register adapter's callbacks
    94 //
    95 //  parameters:
    96 //      session (in)                    session where to store obj handle
    97 //      management (in)                 application defined; usually a locked queue
    98 //      notifyHandshake (in)            callback for doing the handshake
    99 //      retrieve_next_sync_event (in)   callback for receiving sync event
   100 //
   101 //  return value:
   102 //      PEP_STATUS_OK or any other value on errror
   103 //
   104 //  caveat:
   105 //      call that BEFORE you're using any other part of the engine
   106 
   107 DYNAMIC_API PEP_STATUS register_sync_callbacks(
   108         PEP_SESSION session,
   109         void *management,
   110         notifyHandshake_t notifyHandshake,
   111         retrieve_next_sync_event_t retrieve_next_sync_event
   112     );
   113 
   114 DYNAMIC_API void unregister_sync_callbacks(PEP_SESSION session);
   115 
   116 
   117 // do_sync_protocol() - function to be run on an extra thread
   118 //
   119 //  parameters:
   120 //      session                 pEp session to use
   121 //      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
   122 //                              which returns at least a valid address field in
   123 //                              the identity struct
   124 //      obj                     application defined sync object
   125 //
   126 //  return value:
   127 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   128 //      value on failure
   129 
   130 DYNAMIC_API PEP_STATUS do_sync_protocol(
   131         PEP_SESSION session,
   132         void *obj
   133     );
   134 
   135 
   136 // do_sync_protocol_step() - function for single threaded implementations
   137 //
   138 //  parameters:
   139 //      session                 pEp session to use
   140 //      retrieve_next_sync_msg  pointer to retrieve_next_identity() callback
   141 //                              which returns at least a valid address field in
   142 //                              the identity struct
   143 //      obj                     application defined sync object
   144 //      event                   Sync event to process
   145 
   146 DYNAMIC_API PEP_STATUS do_sync_protocol_step(
   147         PEP_SESSION session,
   148         void *obj,
   149         SYNC_EVENT event
   150     );
   151 
   152 
   153 // is_sync_thread() - determine if this is sync thread's session
   154 //
   155 //  paramters:
   156 //      session                 pEp session to test
   157 //
   158 //  return value:
   159 //      true if this is sync thread's session, false otherwise
   160 
   161 DYNAMIC_API bool is_sync_thread(PEP_SESSION session);
   162 
   163 
   164 // new_sync_timeout_event() - create a Sync timeout event
   165 //
   166 //  return value:
   167 //      returns a new Sync timeout event, or NULL on failure
   168 
   169 DYNAMIC_API SYNC_EVENT new_sync_timeout_event();
   170 
   171 
   172 #ifdef __cplusplus
   173 }
   174 #endif
   175