Delta Chat Core C Interface
Loading...
Searching...
No Matches
Public Member Functions | List of all members
dc_chatlist_t Class Reference

An object representing a single chatlist in memory. More...

#include <deltachat.h>

Public Member Functions

uint32_t dc_chatlist_get_chat_id (const dc_chatlist_t *chatlist, size_t index)
 Get a single chat ID of a chatlist. More...
 
size_t dc_chatlist_get_cnt (const dc_chatlist_t *chatlist)
 Find out the number of chats in a chatlist. More...
 
dc_context_tdc_chatlist_get_context (dc_chatlist_t *chatlist)
 Helper function to get the associated context object. More...
 
uint32_t dc_chatlist_get_msg_id (const dc_chatlist_t *chatlist, size_t index)
 Get a single message ID of a chatlist. More...
 
dc_lot_tdc_chatlist_get_summary (const dc_chatlist_t *chatlist, size_t index, dc_chat_t *chat)
 Get a summary for a chatlist index. More...
 
void dc_chatlist_unref (dc_chatlist_t *chatlist)
 Free a chatlist object. More...
 

Detailed Description

An object representing a single chatlist in memory.

Chatlist objects contain chat IDs and, if possible, message IDs belonging to them. The chatlist object is not updated; if you want an update, you have to recreate the object.

For a typical chat overview, the idea is to get the list of all chats via dc_get_chatlist() without any listflags (see below) and to implement a "virtual list" or so (the count of chats is known by dc_chatlist_get_cnt()).

Only for the items that are in view (the list may have several hundreds chats), the UI should call dc_chatlist_get_summary() then. dc_chatlist_get_summary() provides all elements needed for painting the item.

On a click of such an item, the UI should change to the chat view and get all messages from this view via dc_get_chat_msgs(). Again, a "virtual list" is created (the count of messages is known) and for each messages that is scrolled into view, dc_get_msg() is called then.

Why no listflags? Without listflags, dc_get_chatlist() adds the archive "link" automatically as needed. The UI can just render these items differently then.

Member Function Documentation

◆ dc_chatlist_get_chat_id()

uint32_t dc_chatlist_get_chat_id ( const dc_chatlist_t chatlist,
size_t  index 
)

Get a single chat ID of a chatlist.

To get the message object from the message ID, use dc_get_chat().

Parameters
chatlistThe chatlist object as created e.g. by dc_get_chatlist().
indexThe index to get the chat ID for.
Returns
Returns the chat ID of the item at the given index. Index must be between 0 and dc_chatlist_get_cnt()-1.

◆ dc_chatlist_get_cnt()

size_t dc_chatlist_get_cnt ( const dc_chatlist_t chatlist)

Find out the number of chats in a chatlist.

Parameters
chatlistThe chatlist object as created e.g. by dc_get_chatlist().
Returns
Returns the number of items in a dc_chatlist_t object. 0 on errors or if the list is empty.

◆ dc_chatlist_get_context()

dc_context_t * dc_chatlist_get_context ( dc_chatlist_t chatlist)

Helper function to get the associated context object.

Parameters
chatlistThe chatlist object to empty.
Returns
The context object associated with the chatlist. NULL if none or on errors.

◆ dc_chatlist_get_msg_id()

uint32_t dc_chatlist_get_msg_id ( const dc_chatlist_t chatlist,
size_t  index 
)

Get a single message ID of a chatlist.

To get the message object from the message ID, use dc_get_msg().

Parameters
chatlistThe chatlist object as created e.g. by dc_get_chatlist().
indexThe index to get the chat ID for.
Returns
Returns the message_id of the item at the given index. Index must be between 0 and dc_chatlist_get_cnt()-1. If there is no message at the given index (e.g. the chat may be empty), 0 is returned.

◆ dc_chatlist_get_summary()

dc_lot_t * dc_chatlist_get_summary ( const dc_chatlist_t chatlist,
size_t  index,
dc_chat_t chat 
)

Get a summary for a chatlist index.

The summary is returned by a dc_lot_t object with the following fields:

  • dc_lot_t::text1: contains the username or the strings "Me", "Draft" and so on. The string may be colored by having a look at text1_meaning. If there is no such name or it should not be displayed, the element is NULL.
  • dc_lot_t::text1_meaning: one of DC_TEXT1_USERNAME, DC_TEXT1_SELF or DC_TEXT1_DRAFT. 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 or strings as "No messages". May be NULL of there is no such text (e.g. for the archive link)
  • 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. 0 if not applicable.
Parameters
chatlistThe chatlist to query as returned e.g. from dc_get_chatlist().
indexThe index to query in the chatlist.
chatTo speed up things, pass an already available chat object here. If the chat object is not yet available, it is faster to pass NULL.
Returns
The summary as an dc_lot_t object. Must be freed using dc_lot_unref(). NULL is never returned.

◆ dc_chatlist_unref()

void dc_chatlist_unref ( dc_chatlist_t chatlist)

Free a chatlist object.

Parameters
chatlistThe chatlist object to free, created e.g. by dc_get_chatlist(), dc_search_msgs(). If NULL is given, nothing is done.

The documentation for this class was generated from the following file: