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.
size_t	dc_chatlist_get_cnt (const dc_chatlist_t *chatlist)
	Find out the number of chats in a chatlist.
dc_context_t *	dc_chatlist_get_context (dc_chatlist_t *chatlist)
	Helper function to get the associated context object.
uint32_t	dc_chatlist_get_msg_id (const dc_chatlist_t *chatlist, size_t index)
	Get a single message ID of a chatlist.
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.
void	dc_chatlist_unref (dc_chatlist_t *chatlist)
	Free a chatlist object.

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

chatlist	The chatlist object as created e.g. by dc_get_chatlist().
index	The 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

chatlist

The 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

chatlist

The 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

chatlist	The chatlist object as created e.g. by dc_get_chatlist().
index	The 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

chatlist	The chatlist to query as returned e.g. from dc_get_chatlist().
index	The index to query in the chatlist.
chat	To 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

chatlist

The 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:

• deltachat.h