From 9a5330d94ff64541d5ede12d91ebd648716875e4 Mon Sep 17 00:00:00 2001 From: Krista 'DarthMama' Bennett Date: Tue, 8 Sep 2020 10:43:51 +0200 Subject: [PATCH] enum doc placeholders --- src/baseprotocol.h | 6 ++++++ src/bloblist.h | 6 ++++++ src/cryptotech.h | 6 ++++++ src/fsm_common.h | 6 ++++++ src/message.h | 12 +++++++++++ src/message_api.h | 50 ++++++++++++++++++++++++++++++++++++---------- src/pEpEngine.h | 30 ++++++++++++++++++++++++++++ src/pEp_internal.h | 29 +++++++++++++++++++++------ src/resource_id.h | 6 ++++++ src/sync_api.h | 12 +++++++++++ src/transport.h | 6 ++++++ 11 files changed, 153 insertions(+), 16 deletions(-) diff --git a/src/baseprotocol.h b/src/baseprotocol.h index ff287987..ff0f27b4 100644 --- a/src/baseprotocol.h +++ b/src/baseprotocol.h @@ -13,6 +13,12 @@ extern "C" { #endif +/** + * @enum base_protocol_type + * + * @brief TODO + * + */ typedef enum _base_protocol_type { BASE_SIGN = 0, diff --git a/src/bloblist.h b/src/bloblist.h index 3a5ec854..f3ec4f80 100644 --- a/src/bloblist.h +++ b/src/bloblist.h @@ -16,6 +16,12 @@ extern "C" { #endif +/** + * @enum content_disposition_type + * + * @brief TODO + * + */ typedef enum { PEP_CONTENT_DISP_ATTACHMENT = 0, PEP_CONTENT_DISP_INLINE = 1, diff --git a/src/cryptotech.h b/src/cryptotech.h index 048d49ca..5df856c7 100644 --- a/src/cryptotech.h +++ b/src/cryptotech.h @@ -10,6 +10,12 @@ #include "pEpEngine.h" #include "bloblist.h" +/** + * @enum PEP_cryptotech + * + * @brief TODO + * + */ typedef enum _PEP_cryptotech { PEP_crypt_none = 0, PEP_crypt_OpenPGP, diff --git a/src/fsm_common.h b/src/fsm_common.h index 0994e4a1..9a4037c8 100644 --- a/src/fsm_common.h +++ b/src/fsm_common.h @@ -14,6 +14,12 @@ extern "C" { // error values +/** + * @enum fsm_error + * + * @brief TODO + * + */ typedef enum _fsm_error { // these error values are corresponding to // PEP_SYNC_STATEMACHINE_ERROR - value diff --git a/src/message.h b/src/message.h index 82ca4e17..3ae2195a 100644 --- a/src/message.h +++ b/src/message.h @@ -22,12 +22,24 @@ extern "C" { #endif +/** + * @enum PEP_text_format + * + * @brief TODO + * + */ typedef enum _PEP_text_format { PEP_text_format_plain = 0, PEP_text_format_html, PEP_text_format_other = 0xff } PEP_text_format; +/** + * @enum PEP_msg_direction + * + * @brief TODO + * + */ typedef enum _PEP_msg_direction { PEP_dir_incoming = 0, PEP_dir_outgoing diff --git a/src/message_api.h b/src/message_api.h index b58171f1..4af96eb7 100644 --- a/src/message_api.h +++ b/src/message_api.h @@ -57,6 +57,12 @@ PEP_cryptotech determine_encryption_format(message *msg); */ void add_opt_field(message *msg, const char *name, const char *value); +/** + * @enum PEP_encrypt_flags + * + * @brief TODO + * + */ typedef enum _PEP_encrypt_flags { // "default" means whatever the default behaviour for the function is. PEP_encrypt_flag_default = 0x0, @@ -84,6 +90,12 @@ typedef enum _PEP_encrypt_flags { typedef unsigned int PEP_encrypt_flags_t; +/** + * @enum message_wrap_type + * + * @brief TODO + * + */ typedef enum _message_wrap_type { PEP_message_unwrapped, // 1.0 or anything we don't wrap PEP_message_default, // typical inner/outer message 2.0 @@ -145,7 +157,7 @@ DYNAMIC_API PEP_STATUS encrypt_message( * @param[in] src message to encrypt * @param[out] dst pointer to new encrypted message or NULL if no * encryption could take place - * to_fpr fingerprint of the recipient key to which the private key + * @param[in] to_fpr fingerprint of the recipient key to which the private key * should be encrypted * @param[in] enc_format encrypted format * @param[in] flags flags to set special encryption features @@ -210,6 +222,12 @@ DYNAMIC_API PEP_STATUS encrypt_message_for_self( PEP_encrypt_flags_t flags ); +/** + * @enum PEP_rating + * + * @brief TODO + * + */ typedef enum _PEP_rating { PEP_rating_undefined = 0, @@ -238,6 +256,12 @@ typedef enum _PEP_rating { PEP_rating_under_attack = -3 } PEP_rating; +/** + * @enum PEP_color + * + * @brief TODO + * + */ typedef enum _PEP_color { PEP_color_no_color = 0, PEP_color_yellow, @@ -257,6 +281,12 @@ typedef enum _PEP_color { */ DYNAMIC_API PEP_color color_from_rating(PEP_rating rating); +/** + * @enum PEP_decrypt_flags + * + * @brief TODO + * + */ typedef enum _PEP_decrypt_flags { PEP_decrypt_flag_own_private_key = 0x1, PEP_decrypt_flag_consume = 0x2, @@ -621,18 +651,15 @@ DYNAMIC_API PEP_STATUS get_key_rating_for_user( DYNAMIC_API PEP_rating rating_from_comm_type(PEP_comm_type ct); - -// this is the internal function to be used by asynchronous network protocol -// implementations -// -// this function is calling messageToSend(NULL) in case there is a missing or wrong passphrase -// -// do not use it in adapters - /** + * @internal + * * * - * @brief TODO + * @brief This is the internal version of encrypt_message() + * to be used by asynchronous network protocol + * implementations. This function is calls messageToSend(NULL) + * in case there is a missing or wrong passphrase. * * @param[in] session PEP_SESSION * @param[in] *src message @@ -641,6 +668,9 @@ DYNAMIC_API PEP_rating rating_from_comm_type(PEP_comm_type ct); * @param[in] enc_format PEP_enc_format * @param[in] flags PEP_encrypt_flags_t * + * @warning Do NOT use this function in adapters. + * + * @todo KB: line up with the try_base_blahblah docs */ PEP_STATUS try_encrypt_message( PEP_SESSION session, diff --git a/src/pEpEngine.h b/src/pEpEngine.h index 19544b25..2956ae1c 100644 --- a/src/pEpEngine.h +++ b/src/pEpEngine.h @@ -43,6 +43,12 @@ extern "C" { struct _pEpSession; typedef struct _pEpSession * PEP_SESSION; +/** + * @enum PEP_STATUS + * + * @brief TODO + * + */ typedef enum { PEP_STATUS_OK = 0, @@ -154,6 +160,12 @@ typedef enum { PEP_VERSION_MISMATCH = -7, } PEP_STATUS; +/** + * @enum PEP_enc_format + * + * @brief TODO + * + */ typedef enum _PEP_enc_format { PEP_enc_none = 0, // message is not encrypted PEP_enc_pieces = 1, // inline PGP + PGP extensions, was removed @@ -358,6 +370,12 @@ DYNAMIC_API void config_use_only_own_private_keys(PEP_SESSION session, bool enab DYNAMIC_API void config_service_log(PEP_SESSION session, bool enable); +/** + * @enum PEP_CIPHER_SUITE + * + * @brief TODO + * + */ typedef enum { PEP_CIPHER_SUITE_DEFAULT = 0, PEP_CIPHER_SUITE_CV25519 = 1, @@ -636,6 +654,12 @@ DYNAMIC_API PEP_STATUS trustwords( // TODO: increase versions in pEp.asn1 if rating changes +/** + * @enum PEP_comm_type + * + * @brief TODO + * + */ typedef enum _PEP_comm_type { PEP_ct_unknown = 0, @@ -698,6 +722,12 @@ typedef enum _PEP_comm_type { PEP_ct_pEp = 0xff } PEP_comm_type; +/** + * @enum identity_flags + * + * @brief TODO + * + */ typedef enum _identity_flags { // the first octet flags are app defined settings PEP_idf_not_for_sync = 0x0001, // don't use this identity for sync diff --git a/src/pEp_internal.h b/src/pEp_internal.h index 41e22b99..09d56ab8 100644 --- a/src/pEp_internal.h +++ b/src/pEp_internal.h @@ -293,6 +293,7 @@ struct _pEpSession { * */ PEP_STATUS init_transport_system(PEP_SESSION session, bool in_first); + /** * * @@ -304,8 +305,9 @@ PEP_STATUS init_transport_system(PEP_SESSION session, bool in_first); */ void release_transport_system(PEP_SESSION session, bool out_last); -/* NOT to be exposed to the outside!!! */ /** + * @internal + * * * * @brief TODO @@ -317,6 +319,7 @@ void release_transport_system(PEP_SESSION session, bool out_last); * @param[in] **ctext char * @param[in] *csize size_t * + * @warning NOT to be exposed to the outside!!!!! */ PEP_STATUS encrypt_only( PEP_SESSION session, const stringlist_t *keylist, const char *ptext, @@ -358,6 +361,12 @@ void decorate_message( } #endif +/** + * @enum normalize_hex_res_t + * + * @brief TODO + * + */ typedef enum _normalize_hex_rest_t { accept_hex, ignore_hex, @@ -511,13 +520,21 @@ static inline int _same_fpr( // for comparing two full strings. If charstr's length is different from bytestr_size, // we'll return a non-zero value. /** + * @internal + * * * - * @brief TODO - * - * @param[in] *bytestr constunsignedchar - * @param[in] *charstr constchar - * @param[in] bytestr_size int + * @brief Compare an unsigned sequence of bytes with the input string. + * This is really only intended for comparing two full strings. + * If charstr's length is different from bytestr_size, + * we'll return a non-zero value. + * + * @param[in] bytestr byte string (unsigned char data) + * @param[in] charstr character string (NUL-terminated) + * @param[in] bytestr_size length of byte string passed in + * + * @retval 0 if equal + * @retval non-zero if not equal * */ static inline int _unsigned_signed_strcmp(const unsigned char* bytestr, const char* charstr, int bytestr_size) { diff --git a/src/resource_id.h b/src/resource_id.h index 74afb402..c45d0cab 100644 --- a/src/resource_id.h +++ b/src/resource_id.h @@ -7,6 +7,12 @@ #pragma once /* structs to contain info about parsed resource ids (filenames, uids) */ +/** + * @enum pEp_resource_id_type + * + * @brief TODO + * + */ typedef enum _resource_id_type { PEP_RID_FILENAME, PEP_RID_CID diff --git a/src/sync_api.h b/src/sync_api.h index 472ed82c..1f7c641b 100644 --- a/src/sync_api.h +++ b/src/sync_api.h @@ -15,6 +15,12 @@ extern "C" { #endif +/** + * @enum sync_handshake_signal + * + * @brief TODO + * + */ typedef enum _sync_handshake_signal { SYNC_NOTIFY_UNDEFINED = 0, @@ -74,6 +80,12 @@ typedef PEP_STATUS (*notifyHandshake_t)( sync_handshake_signal signal ); +/** + * @enum sync_handshake_result + * + * @brief TODO + * + */ typedef enum _sync_handshake_result { SYNC_HANDSHAKE_CANCEL = -1, SYNC_HANDSHAKE_ACCEPTED = 0, diff --git a/src/transport.h b/src/transport.h index 6774f439..4083fcb0 100644 --- a/src/transport.h +++ b/src/transport.h @@ -13,6 +13,12 @@ extern "C" { #endif +/** + * @enum PEP_transports + * + * @brief TODO + * + */ typedef enum _PEP_transports { // auto transport chooses transport per message automatically PEP_trans_auto = 0,