pEp.foundation
/
pEpEngine
16
2
Fork 17
Code Issues 23 Pull Requests 2 Releases 48 Wiki Activity

Doc cleanup (some)

Browse Source
doxygen-key-id
Krista 'DarthMama' Bennett 2 years ago
parent d1a863a528
commit d36e0718a8
35 changed files with 1037 additions and 1027 deletions
Show Stats Download Patch File Download Diff File

32
src/aux_mime_msg.h
Unescape Escape View File

@ -26,13 +26,13 @@ extern "C" {
*
* @brief Encrypt a MIME message, with MIME output
*
* @param[in] session session handle
* @param[in] mimetext MIME encoded text to encrypt
* @param[in] size size of input mime text
* @param[in] extra extra keys for encryption
* @param[in] session session handle
* @param[in] mimetext MIME encoded text to encrypt
* @param[in] size size of input mime text
* @param[in] extra extra keys for encryption
* @param[out] mime_ciphertext encrypted, encoded message
* @param[in] enc_format encrypted format
* @param[in] flags flags to set special encryption features
* @param[in] enc_format encrypted format
* @param[in] flags flags to set special encryption features
*
* @retval PEP_STATUS_OK if everything worked
* @retval PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
@ -64,14 +64,14 @@ DYNAMIC_API PEP_STATUS MIME_encrypt_message(
* ignoring recipients and other identities from
* the message, with MIME output
*
* @param[in] session session handle
* @param[in] target_id self identity this message should be encrypted for
* @param[in] mimetext MIME encoded text to encrypt
* @param[in] size size of input mime text
* @param[in] extra extra keys for encryption
* @param[in] session session handle
* @param[in] target_id self identity this message should be encrypted for
* @param[in] mimetext MIME encoded text to encrypt
* @param[in] size size of input mime text
* @param[in] extra extra keys for encryption
* @param[out] mime_ciphertext encrypted, encoded message
* @param[in] enc_format encrypted format
* @param[in] flags flags to set special encryption features
* @param[in] enc_format encrypted format
* @param[in] flags flags to set special encryption features
*
* @retval PEP_STATUS_OK if everything worked
* @retval PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
@ -103,9 +103,9 @@ DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self(
*
* @brief Decrypt a MIME message, with MIME output
*
* @param[in] session session handle
* @param[in] mimetext MIME encoded text to decrypt
* @param[in] size size of mime text to decode (in order to decrypt)
* @param[in] session session handle
* @param[in] mimetext MIME encoded text to decrypt
* @param[in] size size of mime text to decode (in order to decrypt)
* @param[out] mime_plaintext decrypted, encoded message
* @param[in,out] keylist in: stringlist with additional keyids for reencryption if needed
* (will be freed and replaced with output keylist)

52
src/baseprotocol.h
Unescape Escape View File

@ -17,9 +17,9 @@ extern "C" {
#define _BASE_PROTO_MIME_TYPE_DIST "application/pEp.distribution"
/**
* @enum base_protocol_type
* @enum base_protocol_type
*
* @brief TODO
* @brief TODO
*
*/
typedef enum _base_protocol_type {
@ -65,14 +65,14 @@ PEP_STATUS base_decorate_message(
*
* @brief Prepare a sync message with payload
*
* @param[in] session session handle
* @param[in] me identity to use for the sender
* @param[in] partner identity to use for the receiver
* @param[in] type base protocol type
* @param[in] payload payload to send
* @param[in] size size of payload
* @param[in] fpr optional key to sign or NULL
* @param[out] result returned message with payload on success
* @param[in] session session handle
* @param[in] me identity to use for the sender
* @param[in] partner identity to use for the receiver
* @param[in] type base protocol type
* @param[in] payload payload to send
* @param[in] size size of payload
* @param[in] fpr optional key to sign or NULL
* @param[out] result returned message with payload on success
*
* @retval PEP_STATUS_OK on success
* @retval error_status on failure
@ -100,14 +100,14 @@ PEP_STATUS base_prepare_message(
*
* @brief Extract a sync message from a pEp message
*
* @param[in] session session handle
* @param[in] msg message to analyze
* @param[in] type base protocol type to extract
* @param[out] size size of extracted payload, or 0 if not found
* @param[out] payload extracted payload, if sync message is found.
* otherwise, NULL
* @param[out] fpr if message was correctly signed then fpr of signature's
* key, otherwise NULL
* @param[in] session session handle
* @param[in] msg message to analyze
* @param[in] type base protocol type to extract
* @param[out] size size of extracted payload, or 0 if not found
* @param[out] payload extracted payload, if sync message is found.
* otherwise, NULL
* @param[out] fpr if message was correctly signed then fpr of signature's
* key, otherwise NULL
*
* @retval PEP_STATUS_OK if no error occurred, whether or not sync message was found
* @retval error_status any other value on error
@ -138,14 +138,14 @@ PEP_STATUS base_extract_message(
* base_prepare_message in that it calls messageToSend(NULL) in case there is a missing
* or wrong passphrase, but more explanation is required here.
*
* @param[in] session session handle
* @param[in] me identity to use for the sender
* @param[in] partner identity to use for the receiver
* @param[in] type base protocol type
* @param[in] payload payload to send
* @param[in] size size of payload
* @param[in] fpr optional key to sign or NULL
* @param[out] result returned message with payload on success
* @param[in] session session handle
* @param[in] me identity to use for the sender
* @param[in] partner identity to use for the receiver
* @param[in] type base protocol type
* @param[in] payload payload to send
* @param[in] size size of payload
* @param[in] fpr optional key to sign or NULL
* @param[out] result returned message with payload on success
*
* @ownership
* - On (and only on) success, ownership of payload is assigned to the result structure

18
src/blacklist.h
Unescape Escape View File

@ -17,8 +17,8 @@ extern "C" {
*
* @brief Add to blacklist
*
* @param[in] session session to use
* @param[in] fpr fingerprint of key to blacklist
* @param[in] session session to use
* @param[in] fpr fingerprint of key to blacklist
*
* @warning there is no point in blacklisting an own key; for any own
* identity, this will be ignored. The correct function to use
@ -36,8 +36,8 @@ DYNAMIC_API PEP_STATUS blacklist_add(PEP_SESSION session, const char *fpr);
*
* @brief Delete from blacklist
*
* @param[in] session session to use
* @param[in] fpr fingerprint of key to be removed from blacklist
* @param[in] session session to use
* @param[in] fpr fingerprint of key to be removed from blacklist
*
*
*/
@ -50,9 +50,9 @@ DYNAMIC_API PEP_STATUS blacklist_delete(PEP_SESSION session, const char *fpr);
*
* @brief Is listed in blacklist
*
* @param[in] session session to use
* @param[in] fpr fingerprint of key to blacklist
* @param[out] bool flags if key is blacklisted
* @param[in] session session to use
* @param[in] fpr fingerprint of key to blacklist
* @param[out] bool flags if key is blacklisted
*
*
*/
@ -69,8 +69,8 @@ DYNAMIC_API PEP_STATUS blacklist_is_listed(
*
* @brief Retrieve full blacklist of key fingerprints
*
* @param[in] session session to use
* @param[out] blacklist copy of blacklist
* @param[in] session session to use
* @param[out] blacklist copy of blacklist
*
* @ownership the ownership of the copy of blacklist goes to the caller
*

42
src/bloblist.h
Unescape Escape View File

@ -17,9 +17,9 @@ extern "C" {
#endif
/**
* @enum content_disposition_type
* @enum content_disposition_type
*
* @brief TODO
* @brief TODO
*
*/
typedef enum {
@ -29,9 +29,9 @@ typedef enum {
} content_disposition_type;
/**
* @struct bloblist_t
* @struct bloblist_t
*
* @brief TODO
* @brief TODO
*
*/
typedef struct _bloblist_t {
@ -55,10 +55,10 @@ typedef struct _bloblist_t {
*
* @brief Allocate a new bloblist
*
* @param[in] blob blob to add to the list
* @param[in] size size of the blob
* @param[in] mime_type MIME type of the blob data or NULL if unknown
* @param[in] filename file name of origin of blob data or NULL if unknown
* @param[in] blob blob to add to the list
* @param[in] size size of the blob
* @param[in] mime_type MIME type of the blob data or NULL if unknown
* @param[in] filename file name of origin of blob data or NULL if unknown
*
* @retval pointer to new bloblist_t or NULL if out of memory
*
@ -82,7 +82,7 @@ DYNAMIC_API bloblist_t *new_bloblist(char *blob, size_t size, const char *mime_t
*
* @brief Free bloblist
*
* @param[in] bloblist bloblist to free
* @param[in] bloblist bloblist to free
*
*
*/
@ -95,7 +95,7 @@ DYNAMIC_API void free_bloblist(bloblist_t *bloblist);
*
* @brief Duplicate bloblist
*
* @param[in] src bloblist to duplicate
* @param[in] src bloblist to duplicate
*
* @retval pointer to a new bloblist_t or NULL if out of memory
*
@ -111,11 +111,11 @@ DYNAMIC_API bloblist_t *bloblist_dup(const bloblist_t *src);
*
* @brief Add reference to a blob to bloblist
*
* @param[in] bloblist bloblist to add to
* @param[in] blob blob
* @param[in] size size of the blob
* @param[in] mime_type MIME type of the blob or NULL if unknown
* @param[in] filename file name of the blob or NULL if unknown
* @param[in] bloblist bloblist to add to
* @param[in] blob blob
* @param[in] size size of the blob
* @param[in] mime_type MIME type of the blob or NULL if unknown
* @param[in] filename file name of the blob or NULL if unknown
*
* @retval pointer to the last element of bloblist or NULL if out of memory or
* @retval NULL passed in as blob value
@ -141,7 +141,7 @@ DYNAMIC_API bloblist_t *bloblist_add(bloblist_t *bloblist, char *blob, size_t si
*
* @brief Get length of bloblist
*
* @param[in] bloblist bloblist struct to determine length of
* @param[in] bloblist bloblist struct to determine length of
*
* @retval length of bloblist in number of elements
*
@ -157,8 +157,8 @@ DYNAMIC_API int bloblist_length(const bloblist_t *bloblist);
* @brief Set blob content disposition and parameters
* when necessary
*
* @param[in] blob bloblist struct to change disposition for
* @param[in] disposition disposition type (see enum)
* @param[in] blob bloblist struct to change disposition for
* @param[in] disposition disposition type (see enum)
*
*
*/
@ -169,10 +169,10 @@ DYNAMIC_API void set_blob_disposition(bloblist_t* blob,
/**
* <!-- bloblist_join() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *first bloblist_t
* @param[in] *second bloblist_t
* @param[in] first bloblist_t*
* @param[in] second bloblist_t*
*
*/
DYNAMIC_API bloblist_t* bloblist_join(bloblist_t* first, bloblist_t* second);

20
src/cryptotech.h
Unescape Escape View File

@ -11,9 +11,9 @@
#include "bloblist.h"
/**
* @enum PEP_cryptotech
* @enum PEP_cryptotech
*
* @brief TODO
* @brief TODO
*
*/
typedef enum _PEP_cryptotech {
@ -221,9 +221,9 @@ typedef PEP_STATUS (*config_cipher_suite_t)(PEP_SESSION session,
/**
* @struct PEP_cryptotech_t
* @struct PEP_cryptotech_t
*
* @brief TODO
* @brief TODO
*
*/
typedef struct _PEP_cryptotech_t {
@ -262,20 +262,20 @@ typedef uint64_t cryptotech_mask;
/**
* <!-- init_cryptotech() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] in_first bool
* @param[in] session PEP_SESSION
* @param[in] in_first bool
*
*/
PEP_STATUS init_cryptotech(PEP_SESSION session, bool in_first);
/**
* <!-- release_cryptotech() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] out_last bool
* @param[in] session PEP_SESSION
* @param[in] out_last bool
*
*/
void release_cryptotech(PEP_SESSION session, bool out_last);

18
src/email.h
Unescape Escape View File

@ -8,15 +8,25 @@
#include "transport.h"
/**
* <!-- email_sendto() -->
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] msg message*
*
*/
PEP_STATUS email_sendto(PEP_SESSION session, const message *msg);
/**
* <!-- email_readnext() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] **msg message
* @param[in] **via PEP_transport_t
* @param[in] session PEP_SESSION
* @param[in] msg message**
* @param[in] via PEP_transport_t**
*
*/
PEP_STATUS email_readnext(PEP_SESSION session, message **msg, PEP_transport_t **via);

148
src/etpan_mime.h
Unescape Escape View File

@ -19,12 +19,12 @@
/**
* <!-- part_new_empty() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *content structmailmime_content
* @param[in] *mime_fields structmailmime_fields
* @param[in] *param_keyvals stringpair_list_t
* @param[in] force_single int
* @param[in] content struct mailmime_content*
* @param[in] mime_fields struct mailmime_fields*
* @param[in] param_keyvals stringpair_list_t*
* @param[in] force_single int
*
*/
struct mailmime * part_new_empty(
@ -37,7 +37,7 @@ struct mailmime * part_new_empty(
/**
* <!-- get_pgp_encrypted_part() -->
*
* @brief TODO
* @brief TODO
*
*
*/
@ -46,13 +46,13 @@ struct mailmime * get_pgp_encrypted_part(void);
/**
* <!-- get_text_part() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *resource pEp_rid_list_t
* @param[in] *mime_type constchar
* @param[in] *text constchar
* @param[in] length size_t
* @param[in] encoding_type int
* @param[in] resource pEp_rid_list_t*
* @param[in] mime_type const char*
* @param[in] text const char*
* @param[in] length size_t
* @param[in] encoding_type int
*
*/
struct mailmime * get_text_part(
@ -66,13 +66,13 @@ struct mailmime * get_text_part(
/**
* <!-- get_file_part() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *resource pEp_rid_list_t
* @param[in] *mime_type constchar
* @param[in] *data char
* @param[in] length size_t
* @param[in] set_attachment_forward_comment bool
* @param[in] resource pEp_rid_list_t*
* @param[in] mime_type const char*
* @param[in] data char*
* @param[in] length size_t
* @param[in] set_attachment_forward_comment bool
*
*/
struct mailmime * get_file_part(
@ -86,9 +86,9 @@ struct mailmime * get_file_part(
/**
* <!-- part_multiple_new() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *type constchar
* @param[in] type const char*
*
*/
struct mailmime * part_multiple_new(const char *type);
@ -98,11 +98,11 @@ typedef void *(*_new_func_t)(void *);
/**
* <!-- _new_field() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] type int
* @param[in] new_func _new_func_t
* @param[in] *value void
* @param[in] type int
* @param[in] new_func _new_func_t
* @param[in] value void*
*
*/
struct mailimf_field * _new_field(
@ -114,9 +114,9 @@ struct mailimf_field * _new_field(
/**
* <!-- _free_field() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *field structmailimf_field
* @param[in] field struct mailimf_field*
*
*/
void _free_field(struct mailimf_field *field);
@ -124,12 +124,12 @@ void _free_field(struct mailimf_field *field);
/**
* <!-- _append_field() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *list clist
* @param[in] type int
* @param[in] new_func _new_func_t
* @param[in] *value void
* @param[in] list clist*
* @param[in] type int
* @param[in] new_func _new_func_t
* @param[in] value void*
*
*/
int _append_field(
@ -142,18 +142,18 @@ int _append_field(
/**
* <!-- timestamp_to_etpantime() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *ts consttimestamp
* @param[in] ts const timestamp*
*
*/
struct mailimf_date_time * timestamp_to_etpantime(const timestamp *ts);
/**
* <!-- etpantime_to_timestamp() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *et conststructmailimf_date_time
* @param[in] et const struct mailimf_date_time*
*
*/
timestamp * etpantime_to_timestamp(const struct mailimf_date_time *et);
@ -161,10 +161,10 @@ timestamp * etpantime_to_timestamp(const struct mailimf_date_time *et);
/**
* <!-- mailbox_from_string() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *name constchar
* @param[in] *address constchar
* @param[in] name const char**
* @param[in] address const char**
*
*/
struct mailimf_mailbox * mailbox_from_string(
@ -175,10 +175,10 @@ struct mailimf_mailbox * mailbox_from_string(
/**
* <!-- create_optional_field() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *field constchar
* @param[in] *value constchar
* @param[in] field const char*
* @param[in] value const char*
*
*/
struct mailimf_field * create_optional_field(
@ -189,11 +189,11 @@ struct mailimf_field * create_optional_field(
/**
* <!-- _append_optional_field() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *list clist
* @param[in] *field constchar
* @param[in] *value constchar
* @param[in] list clist*
* @param[in] field const char*
* @param[in] value const char*
*
*/
int _append_optional_field(
@ -205,95 +205,95 @@ int _append_optional_field(
/**
* <!-- _get_fields() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *mime structmailmime
* @param[in] mime struct mailmime*
*
*/
clist * _get_fields(struct mailmime * mime);
/**
* <!-- _get_content() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *mime structmailmime
* @param[in] mime struct mailmime*
*
*/
struct mailmime_content * _get_content(struct mailmime * mime);
/**
* <!-- _get_filename_or_cid() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *mime structmailmime
* @param[in] mime struct mailmime*
*
*/
char * _get_filename_or_cid(struct mailmime *mime);
/**
* <!-- _get_resource_id_list() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *mime structmailmime
* @param[in] mime struct mailmime*
*
*/
pEp_rid_list_t* _get_resource_id_list(struct mailmime *mime);
/**
* <!-- _build_uri() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *uri_prefix char
* @param[in] *resource char
* @param[in] uri_prefix char*
* @param[in] resource char*
*
*/
char* _build_uri(char* uri_prefix, char* resource);
/**
* <!-- _is_multipart() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *content structmailmime_content
* @param[in] *subtype constchar
* @param[in] content struct mailmime_content*
* @param[in] subtype const char*
*
*/
bool _is_multipart(struct mailmime_content *content, const char *subtype);
/**
* <!-- _is_PGP_MIME() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *content structmailmime_content
* @param[in] content struct mailmime_content*
*
*/
bool _is_PGP_MIME(struct mailmime_content *content);
/**
* <!-- _is_text_part() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *content structmailmime_content
* @param[in] *subtype constchar
* @param[in] content struct mailmime_content*
* @param[in] subtype const char*
*
*/
bool _is_text_part(struct mailmime_content *content, const char *subtype);
/**
* <!-- must_field_value_be_encoded() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *field_value constchar
* @param[in] field_value const char*
*
*/
bool must_field_value_be_encoded(const char* field_value);
/**
* <!-- must_chunk_be_encoded() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *value constvoid
* @param[in] size size_t
* @param[in] ignore_fws bool
* @param[in] value const void*
* @param[in] size size_t
* @param[in] ignore_fws bool
*
*/
bool must_chunk_be_encoded(const void* value, size_t size, bool ignore_fws);
@ -302,11 +302,11 @@ bool must_chunk_be_encoded(const void* value, size_t size, bool ignore_fws);
/**
* <!-- _get_content_type() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *content conststructmailmime_content
* @param[in] **type char
* @param[in] **charset char
* @param[in] content const struct mailmime_content*
* @param[in] type char**
* @param[in] charset char**
*
*/
int _get_content_type(

4
src/fsm_common.h
Unescape Escape View File

@ -15,9 +15,9 @@ extern "C" {
// error values
/**
* @enum fsm_error
* @enum fsm_error
*
* @brief TODO
* @brief TODO
*
*/
typedef enum _fsm_error {

12
src/growing_buf.h
Unescape Escape View File

@ -20,9 +20,9 @@ extern "C" {
// i.e. for encoding to XER
/**
* @struct growing_buf_t
* @struct growing_buf_t
*
* @brief TODO
* @brief TODO
*
*/
typedef struct growing_buf {
@ -49,7 +49,7 @@ growing_buf_t *new_growing_buf(void);
*
* @brief Free growing buffer
*
* @param[in] buf buffer to free
* @param[in] buf buffer to free
*
*
*/
@ -62,9 +62,9 @@ void free_growing_buf(growing_buf_t *buf);
*
* @brief Append new data to growing buffer
*
* @param[in] src new data
* @param[in] size size of new data
* @param[in] dst growing buffer where new data will be appended
* @param[in] src new data
* @param[in] size size of new data
* @param[in] dst growing buffer where new data will be appended
*
* @retval 1 on succes, -1 on failure
*

22
src/identity_list.h
Unescape Escape View File

@ -18,7 +18,7 @@ extern "C" {
*
* @brief Allocate a new identity list
*
* @param[in] ident identity to move for first element
* @param[in] ident identity to move for first element
*
* @retval new identity_list or NULL if out of memory
*
@ -35,7 +35,7 @@ DYNAMIC_API identity_list *new_identity_list(pEp_identity *ident);
*
* @brief Duplicate identity_list (deep copy)
*
* @param[in] id_list identity_list to copy
* @param[in] id_list identity_list to copy
*
* @retval new identity_list or NULL if out of memory
*
@ -50,7 +50,7 @@ DYNAMIC_API identity_list *identity_list_dup(const identity_list *src);
*
* @brief Free memory allocated by identity_list
*
* @param[in] id_list identity_list to free
* @param[in] id_list identity_list to free
*
* @warning this function frees all identities in the list additional to the
* identity_list itself
@ -65,8 +65,8 @@ DYNAMIC_API void free_identity_list(identity_list *id_list);
*
* @brief Add identity to an identity_list
*
* @param[in] id_list identity_list to add to
* @param[in] ident identity being added
* @param[in] id_list identity_list to add to
* @param[in] ident identity being added
*
* @retval pointer to the last element in identity_list or NULL if out of memory
*
@ -82,8 +82,8 @@ DYNAMIC_API identity_list *identity_list_add(identity_list *id_list, pEp_identit
*
* @brief Join second identity_list to the first.
*
* @param[in] first_list identity_list to add to
* @param[in] second_list identity list to add
* @param[in] first_list identity_list to add to
* @param[in] second_list identity list to add
*
* @retval pointer to the HEAD of the new list, or NULL if both lists are empty.
*
@ -96,7 +96,7 @@ DYNAMIC_API identity_list *identity_list_join(identity_list *first_list, identit
*
* @brief Get length of identity_list
*
* @param[in] id_list identity_list struct to determine length of
* @param[in] id_list identity_list struct to determine length of
*
* @retval length of identity_list in number of elements
*
@ -109,10 +109,10 @@ DYNAMIC_API int identity_list_length(const identity_list *id_list);
/**
* <!-- set_all_userids_in_list() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *id_list identity_list
* @param[in] *user_id constchar
* @param[in] id_list identity_list*
* @param[in] user_id const char*
*
*/
PEP_STATUS set_all_userids_in_list(identity_list* id_list, const char* user_id);

22
src/internal_format.h
Unescape Escape View File

@ -18,11 +18,11 @@ extern "C" {
*
* @brief Encode to the internal message format
*
* @param[in] value blob
* @param[in] size size of value
* @param[in] mime_type string of MIME type
* @param[out] code blob in Internal Message Format
* @param[out] code_size size of code
* @param[in] value blob
* @param[in] size size of value
* @param[in] mime_type string of MIME type
* @param[out] code blob in Internal Message Format
* @param[out] code_size size of code
*
* @warning call this for the data in an attachment
* for unsupported MIME types this function is returning NULL for code and
@ -49,12 +49,12 @@ DYNAMIC_API PEP_STATUS encode_internal(
*
* @brief Decode from internal message format
*
* @param[in] code blob in Internal Message Format
* @param[in] code_size size of code
* @param[in] tech crypto tech for MIME type, PEP_crypt_none for auto
* @param[out] value blob or string for longmsg
* @param[out] size size of value
* @param[out] mime_type string with MIME type or NULL for longmsg
* @param[in] code blob in Internal Message Format
* @param[in] code_size size of code
* @param[in] tech crypto tech for MIME type, PEP_crypt_none for auto
* @param[out] value blob or string for longmsg
* @param[out] size size of value
* @param[out] mime_type string with MIME type or NULL for longmsg
*
* @warning this functions copies data from the code
* value goes into the ownership of the caller

110
src/key_reset.h
Unescape Escape View File

@ -31,12 +31,12 @@ extern "C" {
* If no key is provided, reset the identity default.
* Note that reset keys will be removed as defaults for all users and identities.
*
* @param[in] session session handle
* @param[in] fpr fingerprint of key to reset. If NULL, we reset the default key
* @param[in] session session handle
* @param[in] fpr fingerprint of key to reset. If NULL, we reset the default key
* this identity if there is one, and the user default if not.
* @param[in] ident identity for which the key reset should occur. Must contain
* user_id and address. Must not be NULL.
* Note: ident->fpr field will be ignored.
* @param[in] ident identity for which the key reset should occur. Must contain
* user_id and address. Must not be NULL.
* Note: ident->fpr field will be ignored.
*
*
*/
@ -59,15 +59,15 @@ DYNAMIC_API PEP_STATUS key_reset_identity(
* For a reset of all own user keys, call key_reset_all_own_keys() instead.
* Note that reset keys will be removed as defaults for all users and identities.
*
* @param[in] session session handle
* @param[in] user_id user_id for which the key reset should occur. If this
* @param[in] session session handle
* @param[in] user_id user_id for which the key reset should occur. If this
* is the own user_id, fpr MUST NOT be NULL.
* @param[in] fpr fingerprint of key to reset.
* If NULL, we reset all default
* keys for this user and all of its identities.
* *** However, it is forbidden to use the own user_id
* here when the fpr is NULL. For this functionality,
* call key_reset_all_own_keys ***
* @param[in] fpr fingerprint of key to reset.
* If NULL, we reset all default
* keys for this user and all of its identities.
* *** However, it is forbidden to use the own user_id
* here when the fpr is NULL. For this functionality,
* call key_reset_all_own_keys ***
*
*
*/
@ -87,7 +87,7 @@ DYNAMIC_API PEP_STATUS key_reset_user(
* key reset information to people we have recently
* contacted.
*
* @param[in] session session handle
* @param[in] session session handle
*
* @warning HOWEVER, apps and adapters must decide if this is a reasonable state;
* since the period where no own user exists will necessarily be very short
@ -105,9 +105,9 @@ DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session);
/**
* <!-- key_reset_own_grouped_keys() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session PEP_SESSION
*
*/
DYNAMIC_API PEP_STATUS key_reset_own_grouped_keys(PEP_SESSION session);
@ -126,17 +126,17 @@ DYNAMIC_API PEP_STATUS key_reset_own_grouped_keys(PEP_SESSION session);
*
* Can be called manually or through another protocol.
*
* @param[in] session session handle
* @param[in] fpr fingerprint of key to reset. If NULL and ident is NULL,
* @param[in] session session handle
* @param[in] fpr fingerprint of key to reset. If NULL and ident is NULL,
* we reset all keys for the own user. If NULL and ident is
* an own identity, we reset the default key for that
* identity. If that own identity has no default key, we
* reset the user default.
* if it is NULL and there is a non-own identity, we will reset
* if it is NULL and there is a non-own identity, we will reset
* the default key for this identity if present, and user if not.
* @param[in] ident identity for which the key reset should occur.
* @param[in] ident identity for which the key reset should occur.
* if NULL and fpr is non-NULL, we'll reset the key for all
* associated identities. If both ident and fpr are NULL, see
* associated identities. If both ident and fpr are NULL, see
* the fpr arg documentation.
* ***IF there is an ident, it must have a user_id.***
* Note: ident->fpr is always ignored
@ -162,13 +162,13 @@ PEP_STATUS key_reset_own_and_deliver_revocations(PEP_SESSION session,
/**
* <!-- has_key_reset_been_sent() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *from_addr constchar
* @param[in] *user_id constchar
* @param[in] *revoked_fpr constchar
* @param[in] *contacted bool
* @param[in] session PEP_SESSION
* @param[in] from_addr const char*
* @param[in] user_id const char*
* @param[in] revoked_fpr const char*
* @param[in] contacted bool*
*
*/
PEP_STATUS has_key_reset_been_sent(
@ -181,12 +181,12 @@ PEP_STATUS has_key_reset_been_sent(
/**
* <!-- set_reset_contact_notified() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *own_address constchar
* @param[in] *revoke_fpr constchar
* @param[in] *contact_id constchar
* @param[in] session PEP_SESSION
* @param[in] own_address const char*
* @param[in] revoke_fpr const char*
* @param[in] contact_id const char*
*
*/
PEP_STATUS set_reset_contact_notified(
@ -199,10 +199,10 @@ PEP_STATUS set_reset_contact_notified(
/**
* <!-- receive_key_reset() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *reset_msg message
* @param[in] session PEP_SESSION
* @param[in] reset_msg message*
*
*/
PEP_STATUS receive_key_reset(PEP_SESSION session,
@ -211,14 +211,14 @@ PEP_STATUS receive_key_reset(PEP_SESSION session,
/**
* <!-- create_standalone_key_reset_message() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] **dst message
* @param[in] *own_identity pEp_identity
* @param[in] *recip pEp_identity
* @param[in] *old_fpr constchar
* @param[in] *new_fpr constchar
* @param[in] session PEP_SESSION
* @param[in] dst message**
* @param[in] own_identity pEp_identity*
* @param[in] recip pEp_identity*
* @param[in] old_fpr const char*
* @param[in] new_fpr const char*
*
*/
PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
@ -232,12 +232,12 @@ PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
/**
* <!-- send_key_reset_to_recents() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *from_ident pEp_identity
* @param[in] *old_fpr constchar
* @param[in] *new_fpr constchar
* @param[in] session PEP_SESSION
* @param[in] from_ident pEp_identity*
* @param[in] old_fpr const char*
* @param[in] new_fpr const char*
*
*/
PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
@ -248,22 +248,22 @@ PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
/**
* <!-- key_reset_commands_to_PER() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *command_list constkeyreset_command_list
* @param[in] **cmds char
* @param[in] *size size_t
* @param[in] command_list const keyreset_command_list*
* @param[in] cmds char**
* @param[in] size size_t*
*
*/
PEP_STATUS key_reset_commands_to_PER(const keyreset_command_list *command_list, char **cmds, size_t *size);
/**
* <!-- PER_to_key_reset_commands() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] *cmds constchar
* @param[in] size size_t
* @param[in] **command_list keyreset_command_list
* @param[in] cmds const char*
* @param[in] size size_t
* @param[in] command_list keyreset_command_list**
*
*/
PEP_STATUS PER_to_key_reset_commands(const char *cmds, size_t size, keyreset_command_list **command_list);

114
src/keymanagement.h
Unescape Escape View File

@ -125,14 +125,14 @@ DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
/**
* <!-- _myself() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *identity pEp_identity
* @param[in] do_keygen bool
* @param[in] do_renew bool
* @param[in] ignore_flags bool
* @param[in] read_only bool
* @param[in] session PEP_SESSION
* @param[in] identity pEp_identity*
* @param[in] do_keygen bool
* @param[in] do_renew bool
* @param[in] ignore_flags bool
* @param[in] read_only bool
*
*/
PEP_STATUS _myself(PEP_SESSION session,
@ -147,7 +147,7 @@ PEP_STATUS _myself(PEP_SESSION session,
*
* @brief Callback being called by do_keymanagement()
*
* @param[in] management data structure to deliver (implementation defined)
* @param[in] management data structure to deliver (implementation defined)
*
* @retval identity to check or NULL to terminate do_keymanagement()
* @retval if given identity must be created with new_identity()
@ -168,8 +168,8 @@ typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
*
* @brief Callback for appending to queue
*
* @param[in] ident identity to examine
* @param[in] management data structure to deliver (implementation defined)
* @param[in] ident identity to examine
* @param[in] management data structure to deliver (implementation defined)
*
* @retval 0 if identity was added successfully to queue or nonzero otherwise
*
@ -184,9 +184,9 @@ typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
*
* @brief Register examine_identity() callback
*
* @param[in] session session to use
* @param[in] examine_identity examine_identity() function to register
* @param[in] management data structure to deliver (implementation defined)
* @param[in] session session to use
* @param[in] examine_identity examine_identity() function to register
* @param[in] management data structure to deliver (implementation defined)
*
*
*/
@ -203,7 +203,7 @@ DYNAMIC_API PEP_STATUS register_examine_function(
*
* @brief Function to be run on an extra thread
*
* @param[in] retrieve_next_identity pointer to retrieve_next_identity()
* @param[in] retrieve_next_identity pointer to retrieve_next_identity()
* callback which returns at least a valid
* address field in the identity struct
*
@ -229,8 +229,8 @@ DYNAMIC_API PEP_STATUS do_keymanagement(
*
* @brief Mark key as being compromised
*
* @param[in] session session to use
* @param[in] ident person and key which was compromised
* @param[in] session session to use
* @param[in] ident person and key which was compromised
*
* @warning ident is INPUT ONLY. If you want updated trust on the identity, you'll have
* to call update_identity or myself respectively after this.
@ -253,8 +253,8 @@ DYNAMIC_API PEP_STATUS key_mistrusted(
*
* @brief Mark a key as trusted for a user
*
* @param[in] session session to use
* @param[in] ident person and key to trust in - this must not be an
* @param[in] session session to use
* @param[in] ident person and key to trust in - this must not be an
* own_identity in which the .me flag is set or
* the user_id is an own user_id.
*
@ -280,8 +280,8 @@ DYNAMIC_API PEP_STATUS trust_personal_key(
* associated with outselves for issues like
* manual key import
*
* @param[in] session session to use
* @param[in] ident own ident containing fpr to trust
* @param[in] session session to use
* @param[in] ident own ident containing fpr to trust
*
* @warning if this is a public key only, keep in mind that if
* the private part of the keypair is later added,
@ -309,8 +309,8 @@ DYNAMIC_API PEP_STATUS trust_own_key(
* @brief Reset trust bit or explicitly mistrusted status for an identity and
* its accompanying key/user_id pair.
*
* @param[in] session session to use
* @param[in] ident identity for person and key whose trust status is to be reset
* @param[in] session session to use
* @param[in] ident identity for person and key whose trust status is to be reset
*
* @warning ident is INPUT ONLY. If you want updated trust on the identity, you'll have
* to call update_identity or myself respectively after this.
@ -383,11 +383,11 @@ DYNAMIC_API PEP_STATUS own_identities_retrieve(
/**
* <!-- contains_priv_key() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *fpr constchar
* @param[in] *has_private bool
* @param[in] session PEP_SESSION
* @param[in] fpr const char*
* @param[in] has_private bool*
*
*/
PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
@ -398,10 +398,10 @@ PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
*
* @brief Retrieve all flagged keypair fingerprints
*
* @param[in] session session to use
* @param[out] keylist list of fingerprints
* @param[in] excluded_flags flags to exclude from results
* @param[in] private_only if true, return only fprs for
* @param[in] session session to use
* @param[out] keylist list of fingerprints
* @param[in] excluded_flags flags to exclude from results
* @param[in] private_only if true, return only fprs for
* which we have the secret part
*
* @warning the ownership of the list goes to the caller
@ -478,9 +478,9 @@ DYNAMIC_API PEP_STATUS set_own_key(
/**
* <!-- clean_own_key_defaults() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session PEP_SESSION
*
*/
DYNAMIC_API PEP_STATUS clean_own_key_defaults(PEP_SESSION session);
@ -488,11 +488,11 @@ DYNAMIC_API PEP_STATUS clean_own_key_defaults(PEP_SESSION session);
/**
* <!-- get_all_keys_for_user() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *user_id constchar
* @param[in] **keys stringlist_t
* @param[in] session PEP_SESSION
* @param[in] user_id const char*
* @param[in] keys stringlist_t**
*
*/
PEP_STATUS get_all_keys_for_user(PEP_SESSION session,
@ -505,42 +505,42 @@ PEP_STATUS get_all_keys_for_user(PEP_SESSION session,
/**
* <!-- add_mistrusted_key() -->
*
* @brief TODO
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *fpr constchar
* @param[in] session PEP_SESSION
* @param[in] fpr const char*
*
*/
PEP_STATUS add_mistrusted_key(PEP_SESSION session, const char* fpr);
/**