p≡p engine
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

238 lines
7.3 KiB

#pragma once
#include "pEpEngine.h"
#ifdef __cplusplus
extern "C" {
#endif
// update_identity() - update identity information
//
// parameters:
// session (in) session to use
// identity (inout) identity information of communication partner
// (identity->fpr is OUT ONLY)
// caveat:
// if this function returns PEP_ct_unknown or PEP_ct_key_expired in
// identity->comm_type, the caller must insert the identity into the
// asynchronous management implementation, so retrieve_next_identity()
// will return this identity later
// at least identity->address must be a non-empty UTF-8 string as input
// update_identity() never writes flags; use set_identity_flags() for
// writing
// this function NEVER reads the incoming fpr, only writes to it.
DYNAMIC_API PEP_STATUS update_identity(
PEP_SESSION session, pEp_identity * identity
);
// myself() - ensures that the own identity is being complete
//
// parameters:
// session (in) session to use
// identity (inout) identity of local user
// at least .address, .username, .user_id must be set
//
// return value:
// PEP_STATUS_OK if identity could be completed or was already complete,
// any other value on error
//
// caveat:
// this function generates a keypair on demand; because it's synchronous
// it can need a decent amount of time to return
// if you need to do this asynchronous, you need to return an identity
// with retrieve_next_identity() where pEp_identity.me is true
DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
// retrieve_next_identity() - callback being called by do_keymanagement()
//
// parameters:
// management (in) data structure to deliver (implementation defined)
//
// return value:
// identity to check or NULL to terminate do_keymanagement()
// if given identity must be created with new_identity()
// the identity struct is going to the ownership of this library
// it must not be freed by the callee
//
// caveat:
// this callback has to block until an identity or NULL can be returned
// an implementation is not provided by this library; instead it has to be
// implemented by the user of this library
typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
// examine_identity() - callback for appending to queue
//
// parameters:
// ident (in) identity to examine
// management (in) data structure to deliver (implementation defined)
//
// return value:
// 0 if identity was added successfully to queue or nonzero otherwise
typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
// register_examine_function() - register examine_identity() callback
//
// parameters:
// session (in) session to use
// examine_identity (in) examine_identity() function to register
// management (in) data structure to deliver (implementation defined)
DYNAMIC_API PEP_STATUS register_examine_function(
PEP_SESSION session,
examine_identity_t examine_identity,
void *management
);
// do_keymanagement() - function to be run on an extra thread
//
// parameters:
// retrieve_next_identity pointer to retrieve_next_identity() callback
// which returns at least a valid address field in
// the identity struct
// management management data to give to keymanagement
// (implementation defined)
//
// return value:
// PEP_STATUS_OK if thread has to terminate successfully or any other
// value on failure
//
// caveat:
// to ensure proper working of this library, a thread has to be started
// with this function immediately after initialization
// do_keymanagement() calls retrieve_next_identity(management)
DYNAMIC_API PEP_STATUS do_keymanagement(
retrieve_next_identity_t retrieve_next_identity,
void *management
);
// key_mistrusted() - mark key as being compromized
//
// parameters:
// session (in) session to use
// ident (in) person and key which was compromized
DYNAMIC_API PEP_STATUS key_mistrusted(
PEP_SESSION session,
pEp_identity *ident
);
// trust_personal_key() - mark a key as trusted with a person
//
// parameters:
// session (in) session to use
// ident (in) person and key to trust in
//
// caveat:
// the fields user_id, address and fpr must be supplied
DYNAMIC_API PEP_STATUS trust_personal_key(
PEP_SESSION session,
pEp_identity *ident
);
// key_reset_trust() - undo trust_personal_key and key_mistrusted() for keys
// we don't own
//
// parameters:
// session (in) session to use
// ident (in) person and key which was compromized
DYNAMIC_API PEP_STATUS key_reset_trust(
PEP_SESSION session,
pEp_identity *ident
);
// own_key_is_listed() - returns true id key is listed as own key
//
// parameters:
// session (in) session to use
// fpr (in) fingerprint of key to test
// bool (out) flags if key is own
DYNAMIC_API PEP_STATUS own_key_is_listed(
PEP_SESSION session,
const char *fpr,
bool *listed
);
// _own_identities_retrieve() - retrieve all own identities
//
// parameters:
// session (in) session to use
// own_identities (out) list of own identities
// excluded_flags (int) flags to exclude from results
//
// caveat:
// the ownership of the copy of own_identities goes to the caller
DYNAMIC_API PEP_STATUS _own_identities_retrieve(
PEP_SESSION session,
identity_list **own_identities,
identity_flags_t excluded_flags
);
// own_identities_retrieve() - retrieve all own identities
//
// parameters:
// session (in) session to use
// own_identities (out) list of own identities
//
// caveat:
// the ownership of the copy of own_identities goes to the caller
DYNAMIC_API PEP_STATUS own_identities_retrieve(
PEP_SESSION session,
identity_list **own_identities
);
PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
bool *has_private);
// _own_keys_retrieve() - retrieve all flagged keypair fingerprints
//
// parameters:
// session (in) session to use
// keylist (out) list of fingerprints
// excluded_flags (int) flags to exclude from results
//
// caveat:
// the ownership of the list goes to the caller
DYNAMIC_API PEP_STATUS _own_keys_retrieve(
PEP_SESSION session,
stringlist_t **keylist,
identity_flags_t excluded_flags
);
// own_keys_retrieve() - retrieve all flagged keypair fingerprints
//
// parameters:
// session (in) session to use
// keylist (out) list of fingerprints
//
// caveat:
// the ownership of the list goes to the caller
DYNAMIC_API PEP_STATUS own_keys_retrieve(
PEP_SESSION session,
stringlist_t **keylist
);
#ifdef __cplusplus
}
#endif