Delta Chat Core C-API
 All Classes Functions Typedefs Groups Pages
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 deaddrop and the archive "link" automatically as needed. The UI can just render these items differently then. Although the deaddrop link is currently always the first entry and only present on new messages, there is the rough idea that it can be optionally always present and sorted into the list by date. Rendering the deaddrop in the described way would not add extra work in the UI then.

Member Function Documentation

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 eg. 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.
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 eg. 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_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
Context object associated with the chatlist. NULL if none or on errors.
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 eg. 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 (eg. the chat may be empty), 0 is returned.
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 (eg. 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 (see dc_msg_get_state()). 0 if not applicable.
Parameters
chatlistThe chatlist to query as returned eg. 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.
void dc_chatlist_unref ( dc_chatlist_t chatlist)

Free a chatlist object.

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

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