src/keymanagement.h
author vb
Wed, 25 Jun 2014 18:44:58 +0200
changeset 0 16f27efbef98
child 8 26cc9f0228f4
permissions -rw-r--r--
initial commit
vb@0
     1
#ifdef __cplusplus
vb@0
     2
extern "C" {
vb@0
     3
#endif
vb@0
     4
vb@0
     5
// update_identity() - update identity information
vb@0
     6
//
vb@0
     7
//  parameters:
vb@0
     8
//      session (in)        session to use
vb@0
     9
//      identity (inout)    identity information of communication partner
vb@0
    10
//
vb@0
    11
//  caveat:
vb@0
    12
//      if this function returns PEP_ct_unknown in identity->comm_type, the
vb@0
    13
//      caller must insert the identity into the asynchronous management
vb@0
    14
//      implementation, so retrieve_next_identity() will return this identity
vb@0
    15
//      later
vb@0
    16
//      at least identity->address must be a valid C string as input
vb@0
    17
vb@0
    18
DYNAMIC_API PEP_STATUS update_identity(
vb@0
    19
        PEP_SESSION session, pEp_identity * identity
vb@0
    20
    );
vb@0
    21
vb@0
    22
vb@0
    23
// outgoing_comm_type() - minimum comm_type for a list of addresses
vb@0
    24
//
vb@0
    25
//  parameters:
vb@0
    26
//      session (in)        session to use
vb@0
    27
//      addresses (in)      list of addresses
vb@0
    28
//      comm_type (out)     comm_type which can be used to communicate with
vb@0
    29
//                          addresses
vb@0
    30
vb@0
    31
DYNAMIC_API PEP_STATUS outgoing_comm_type(
vb@0
    32
        PEP_SESSION session,
vb@0
    33
        const stringlist_t *addresses,
vb@0
    34
        PEP_comm_type *comm_type
vb@0
    35
    );
vb@0
    36
vb@0
    37
vb@0
    38
// myself() - ensures that the own identity is being complete
vb@0
    39
//
vb@0
    40
//  parameters:
vb@0
    41
//      session (in)        session to use
vb@0
    42
//      identity (inout)    identity of local user
vb@0
    43
//                          at least .address, .username, .user_id must be set
vb@0
    44
//
vb@0
    45
//  return value:
vb@0
    46
//      PEP_STATUS_OK if identity could be completed or was already complete,
vb@0
    47
//      any other value on error
vb@0
    48
//
vb@0
    49
//  caveat:
vb@0
    50
//      this function generates a keypair on demand; because it's synchronous
vb@0
    51
//      it can need a decent amount of time to return
vb@0
    52
//      if you need to do this asynchronous, you need to return an identity
vb@0
    53
//      with retrieve_next_identity() where pEp_identity.me is true
vb@0
    54
vb@0
    55
DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
vb@0
    56
vb@0
    57
vb@0
    58
// retrieve_next_identity() - callback being called by do_keymanagement()
vb@0
    59
//
vb@0
    60
//  parameters:
vb@0
    61
//      management (in)     data structure to deliver (implementation defined)
vb@0
    62
//
vb@0
    63
//  return value:
vb@0
    64
//      identity to check or NULL to terminate do_keymanagement()
vb@0
    65
//      if given identity must be created with new_identity()
vb@0
    66
//      the identity struct is going to the ownership of this library
vb@0
    67
//      it must not be freed by the callee
vb@0
    68
//
vb@0
    69
//  caveat:
vb@0
    70
//      this callback has to block until an identity or NULL can be returned
vb@0
    71
//      an implementation is not provided by this library; instead it has to be
vb@0
    72
//      implemented by the user of this library
vb@0
    73
vb@0
    74
typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
vb@0
    75
vb@0
    76
vb@0
    77
// do_keymanagement() - function to be run on an extra thread
vb@0
    78
//
vb@0
    79
//  parameters:
vb@0
    80
//      retrieve_next_identity  pointer to retrieve_next_identity() callback
vb@0
    81
//                              which returns at least a valid address field in
vb@0
    82
//                              the identity struct
vb@0
    83
//      management              management data to give to keymanagement
vb@0
    84
//                              (implementation defined)
vb@0
    85
//
vb@0
    86
//  return value:
vb@0
    87
//      PEP_STATUS_OK if thread has to terminate successfully or any other
vb@0
    88
//      value on failure
vb@0
    89
//
vb@0
    90
//  caveat:
vb@0
    91
//      to ensure proper working of this library, a thread has to be started
vb@0
    92
//      with this function immediately after initialization
vb@0
    93
//      do_keymanagement() calls retrieve_next_identity(management)
vb@0
    94
vb@0
    95
DYNAMIC_API PEP_STATUS do_keymanagement(
vb@0
    96
        retrieve_next_identity_t retrieve_next_identity,
vb@0
    97
        void *management
vb@0
    98
    );
vb@0
    99
vb@0
   100
#ifdef __cplusplus
vb@0
   101
}
vb@0
   102
#endif
vb@0
   103