From 398cea6466f6c2ffaa9c6f9feb76bb366f08d5f3 Mon Sep 17 00:00:00 2001 From: bjoern Date: Sat, 18 Sep 2021 13:51:07 +0200 Subject: [PATCH] document DC_STATE and DC_CHAT_TYPE explicitly (#2688) * document DC_STATE explicitly and add real hyperlinks * document DC_CHAT_TYPE explicitly * sort constants alphabetically --- deltachat-ffi/Doxyfile | 2 +- deltachat-ffi/deltachat.h | 185 ++++++++++++++++++++++++++++---------- 2 files changed, 140 insertions(+), 47 deletions(-) diff --git a/deltachat-ffi/Doxyfile b/deltachat-ffi/Doxyfile index 23a2cd731..03365989d 100644 --- a/deltachat-ffi/Doxyfile +++ b/deltachat-ffi/Doxyfile @@ -583,7 +583,7 @@ SORT_MEMBERS_CTORS_1ST = NO # appear in their defined order. # The default value is: NO. -SORT_GROUP_NAMES = NO +SORT_GROUP_NAMES = YES # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by # fully-qualified names, including namespaces. If set to NO, the class list will diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h index d8ddd23e7..ae0b6476e 100644 --- a/deltachat-ffi/deltachat.h +++ b/deltachat-ffi/deltachat.h @@ -1672,7 +1672,7 @@ void dc_forward_msgs (dc_context_t* context, const uint3 * * - For normal chats, the IMAP state is updated, MDN is sent * (if dc_set_config()-options `mdns_enabled` is set) - * and the internal state is changed to DC_STATE_IN_SEEN to reflect these actions. + * and the internal state is changed to @ref DC_STATE_IN_SEEN to reflect these actions. * * - For contact requests, no IMAP or MDNs is done * and the internal state is not changed therefore. @@ -2921,7 +2921,7 @@ uint32_t dc_chatlist_get_msg_id (const dc_chatlist_t* chatlist, siz * * - dc_lot_t::timestamp: the timestamp of the message. 0 if not applicable. * - * - dc_lot_t::state: The state of the message as one of the DC_STATE_* constants (see #dc_msg_get_state()). 0 if not applicable. + * - dc_lot_t::state: The state of the message as one of the @ref DC_STATE constants. 0 if not applicable. * * @memberof dc_chatlist_t * @param chatlist The chatlist to query as returned e.g. from dc_get_chatlist(). @@ -2975,7 +2975,7 @@ dc_context_t* dc_chatlist_get_context (dc_chatlist_t* chatlist); * color: color of this chat * last-message-from: who sent the last message * last-message-text: message (truncated) - * last-message-state: DC_STATE* constant + * last-message-state: @ref DC_STATE constant * last-message-date: * avatar-path: path-to-blobfile * is_verified: yes/no @@ -2999,12 +2999,6 @@ char* dc_chat_get_info_json (dc_context_t* context, size_t chat #define DC_CHAT_ID_LAST_SPECIAL 9 // larger chat IDs are "real" chats, their messages are "real" messages. -#define DC_CHAT_TYPE_UNDEFINED 0 -#define DC_CHAT_TYPE_SINGLE 100 -#define DC_CHAT_TYPE_GROUP 120 -#define DC_CHAT_TYPE_MAILINGLIST 140 - - /** * Free a chat object. * @@ -3031,18 +3025,16 @@ uint32_t dc_chat_get_id (const dc_chat_t* chat); /** - * Get chat type. + * Get chat type as one of the @ref DC_CHAT_TYPE constants: * - * Currently, there are two chat types: - * - * - DC_CHAT_TYPE_SINGLE (100) - a normal chat is a chat with a single contact, + * - @ref DC_CHAT_TYPE_SINGLE - a normal chat is a chat with a single contact, * chats_contacts contains one record for the user. DC_CONTACT_ID_SELF * (see dc_contact_t::id) is added _only_ for a self talk. * - * - DC_CHAT_TYPE_GROUP (120) - a group chat, chats_contacts contain all group + * - @ref DC_CHAT_TYPE_GROUP - a group chat, chats_contacts contain all group * members, incl. DC_CONTACT_ID_SELF * - * - DC_CHAT_TYPE_MAILINGLIST (140) - a mailing list, this is similar to groups, + * - @ref DC_CHAT_TYPE_MAILINGLIST - a mailing list, this is similar to groups, * however, the member list cannot be retrieved completely * and cannot be changed using this api. * moreover, for now, mailist lists are read-only. @@ -3254,18 +3246,6 @@ int64_t dc_chat_get_remaining_mute_duration (const dc_chat_t* chat); #define DC_MSG_ID_LAST_SPECIAL 9 -#define DC_STATE_UNDEFINED 0 -#define DC_STATE_IN_FRESH 10 -#define DC_STATE_IN_NOTICED 13 -#define DC_STATE_IN_SEEN 16 -#define DC_STATE_OUT_PREPARING 18 -#define DC_STATE_OUT_DRAFT 19 -#define DC_STATE_OUT_PENDING 20 -#define DC_STATE_OUT_FAILED 24 -#define DC_STATE_OUT_DELIVERED 26 // to check if a mail was sent, use dc_msg_is_sent() -#define DC_STATE_OUT_MDN_RCVD 28 - - /** * Create new message object. Message objects are needed e.g. for sending messages using * dc_send_msg(). Moreover, they are returned e.g. from dc_get_msg(), @@ -3345,28 +3325,37 @@ int dc_msg_get_viewtype (const dc_msg_t* msg); * Get the state of a message. * * Incoming message states: - * - DC_STATE_IN_FRESH (10) - Incoming _fresh_ message. Fresh messages are neither noticed nor seen and are typically shown in notifications. Use dc_get_fresh_msgs() to get all fresh messages. - * - DC_STATE_IN_NOTICED (13) - Incoming _noticed_ message. E.g. chat opened but message not yet read - noticed messages are not counted as unread but were not marked as read nor resulted in MDNs. Use dc_marknoticed_chat() to mark messages as being noticed. - * - DC_STATE_IN_SEEN (16) - Incoming message, really _seen_ by the user. Marked as read on IMAP and MDN may be sent. Use dc_markseen_msgs() to mark messages as being seen. + * - @ref DC_STATE_IN_FRESH - Incoming _fresh_ message. + * Fresh messages are neither noticed nor seen and are typically shown in notifications. + * Use dc_get_fresh_msgs() to get all fresh messages. + * - @ref DC_STATE_IN_NOTICED - Incoming _noticed_ message. + * E.g. chat opened but message not yet read. + * Noticed messages are not counted as unread but were not marked as read nor resulted in MDNs. + * Use dc_marknoticed_chat() to mark messages as being noticed. + * - @ref DC_STATE_IN_SEEN - Incoming message, really _seen_ by the user. + * Marked as read on IMAP and MDN may be sent. Use dc_markseen_msgs() to mark messages as being seen. * * Outgoing message states: - * - DC_STATE_OUT_PREPARING (18) - For files which need time to be prepared before they can be sent, - * the message enters this state before DC_STATE_OUT_PENDING. - * - DC_STATE_OUT_DRAFT (19) - Message saved as draft using dc_set_draft() - * - DC_STATE_OUT_PENDING (20) - The user has pressed the "send" button but the + * - @ref DC_STATE_OUT_PREPARING - For files which need time to be prepared before they can be sent, + * the message enters this state before @ref DC_STATE_OUT_PENDING. + * - @ref DC_STATE_OUT_DRAFT - Message saved as draft using dc_set_draft() + * - @ref DC_STATE_OUT_PENDING - The user has pressed the "send" button but the * message is not yet sent and is pending in some way. Maybe we're offline (no checkmark). - * - DC_STATE_OUT_FAILED (24) - _Unrecoverable_ error (_recoverable_ errors result in pending messages), you'll receive the event #DC_EVENT_MSG_FAILED. - * - DC_STATE_OUT_DELIVERED (26) - Outgoing message successfully delivered to server (one checkmark). Note, that already delivered messages may get into the state DC_STATE_OUT_FAILED if we get such a hint from the server. + * - @ref DC_STATE_OUT_FAILED - _Unrecoverable_ error (_recoverable_ errors result in pending messages), + * you'll receive the event #DC_EVENT_MSG_FAILED. + * - @ref DC_STATE_OUT_DELIVERED - Outgoing message successfully delivered to server (one checkmark). + * Note, that already delivered messages may get into the state @ref DC_STATE_OUT_FAILED if we get such a hint from the server. * If a sent message changes to this state, you'll receive the event #DC_EVENT_MSG_DELIVERED. - * - DC_STATE_OUT_MDN_RCVD (28) - Outgoing message read by the recipient (two checkmarks; this requires goodwill on the receiver's side) + * - @ref DC_STATE_OUT_MDN_RCVD - Outgoing message read by the recipient + * (two checkmarks; this requires goodwill on the receiver's side) * If a sent message changes to this state, you'll receive the event #DC_EVENT_MSG_READ. * Also messages already read by some recipients - * may get into the state DC_STATE_OUT_FAILED at a later point, + * may get into the state @ref DC_STATE_OUT_FAILED at a later point, * e.g. when in a group, delivery fails for some recipients. * * If you just want to check if a message is sent or not, please use dc_msg_is_sent() which regards all states accordingly. * - * The state of just created message objects is DC_STATE_UNDEFINED (0). + * The state of just created message objects is @ref DC_STATE_UNDEFINED. * The state is always set by the core-library, users of the library cannot set the state directly, but it is changed implicitly e.g. * when calling dc_marknoticed_chat() or dc_markseen_msgs(). * @@ -3630,7 +3619,7 @@ int64_t dc_msg_get_ephemeral_timestamp (const dc_msg_t* msg); * Typically used to show dc_lot_t::text1 with different colors. 0 if not applicable. * - dc_lot_t::text2: contains an excerpt of the message text. * - dc_lot_t::timestamp: the timestamp of the message. - * - dc_lot_t::state: The state of the message as one of the DC_STATE_* constants (see #dc_msg_get_state()). + * - dc_lot_t::state: The state of the message as one of the @ref DC_STATE constants. * * Typically used to display a search result. See also dc_chatlist_get_summary() to display a list of chats. * @@ -4651,6 +4640,110 @@ int64_t dc_lot_get_timestamp (const dc_lot_t* lot); */ +/** + * @defgroup DC_STATE DC_STATE + * + * These constants describe the state of a message. + * The state can be retrieved using dc_msg_get_state() + * and may change by various actions reported by various events + * + * @addtogroup DC_STATE + * @{ + */ + +/** + * Message just created. See dc_msg_get_state() for details. + */ +#define DC_STATE_UNDEFINED 0 + +/** + * Incoming fresh message. See dc_msg_get_state() for details. + */ +#define DC_STATE_IN_FRESH 10 + +/** + * Incoming noticed message. See dc_msg_get_state() for details. + */ +#define DC_STATE_IN_NOTICED 13 + +/** + * Incoming seen message. See dc_msg_get_state() for details. + */ +#define DC_STATE_IN_SEEN 16 + +/** + * Outgoing message being prepared. See dc_msg_get_state() for details. + */ +#define DC_STATE_OUT_PREPARING 18 + +/** + * Outgoing message drafted. See dc_msg_get_state() for details. + */ +#define DC_STATE_OUT_DRAFT 19 + +/** + * Outgoing message waiting to be sent. See dc_msg_get_state() for details. + */ +#define DC_STATE_OUT_PENDING 20 + +/** + * Outgoing message failed sending. See dc_msg_get_state() for details. + */ +#define DC_STATE_OUT_FAILED 24 + +/** + * Outgoing message sent. To check if a mail was actually sent, use dc_msg_is_sent(). + * See dc_msg_get_state() for details. + */ +#define DC_STATE_OUT_DELIVERED 26 + +/** + * Outgoing message sent and seen by recipients(s). See dc_msg_get_state() for details. + */ +#define DC_STATE_OUT_MDN_RCVD 28 + +/** + * @} + */ + + +/** + * @defgroup DC_CHAT_TYPE DC_CHAT_TYPE + * + * These constants describe the type of a chat. + * The chat type can be retrieved using dc_chat_get_type() + * and the type does not change during the chat's lifetime. + * + * @addtogroup DC_CHAT_TYPE + * @{ + */ + +/** + * Undefined chat type. + * Normally, this type is not returned. + */ +#define DC_CHAT_TYPE_UNDEFINED 0 + +/** + * A one-to-one chat with a single contact. See dc_chat_get_type() for details. + */ +#define DC_CHAT_TYPE_SINGLE 100 + +/** + * A group chat. See dc_chat_get_type() for details. + */ +#define DC_CHAT_TYPE_GROUP 120 + +/** + * A mailing list. See dc_chat_get_type() for details. + */ +#define DC_CHAT_TYPE_MAILINGLIST 140 + +/** + * @} + */ + + /** * @defgroup DC_SOCKET DC_SOCKET * @@ -5077,8 +5170,8 @@ void dc_event_unref(dc_event_t* event); /** - * A single message is sent successfully. State changed from DC_STATE_OUT_PENDING to - * DC_STATE_OUT_DELIVERED, see dc_msg_get_state(). + * A single message is sent successfully. State changed from @ref DC_STATE_OUT_PENDING to + * @ref DC_STATE_OUT_DELIVERED. * * @param data1 (int) chat_id * @param data2 (int) msg_id @@ -5088,8 +5181,8 @@ void dc_event_unref(dc_event_t* event); /** * A single message could not be sent. - * State changed from DC_STATE_OUT_PENDING, DC_STATE_OUT_DELIVERED or DC_STATE_OUT_MDN_RCVD - * to DC_STATE_OUT_FAILED, see dc_msg_get_state(). + * State changed from @ref DC_STATE_OUT_PENDING, @ref DC_STATE_OUT_DELIVERED or @ref DC_STATE_OUT_MDN_RCVD + * to @ref DC_STATE_OUT_FAILED. * * @param data1 (int) chat_id * @param data2 (int) msg_id @@ -5098,8 +5191,8 @@ void dc_event_unref(dc_event_t* event); /** - * A single message is read by the receiver. State changed from DC_STATE_OUT_DELIVERED to - * DC_STATE_OUT_MDN_RCVD, see dc_msg_get_state(). + * A single message is read by the receiver. State changed from @ref DC_STATE_OUT_DELIVERED to + * @ref DC_STATE_OUT_MDN_RCVD. * * @param data1 (int) chat_id * @param data2 (int) msg_id