Delta Chat Core C-API
 All Classes Functions Typedefs Groups Pages
Public Member Functions | List of all members
dc_chat_t Class Reference

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

#include <deltachat.h>

Public Member Functions

int dc_chat_get_archived (const dc_chat_t *chat)
 Get archived state. More...
 
uint32_t dc_chat_get_color (const dc_chat_t *chat)
 Get a color for the chat. More...
 
uint32_t dc_chat_get_id (const dc_chat_t *chat)
 Get chat ID. More...
 
char * dc_chat_get_name (const dc_chat_t *chat)
 Get name of a chat. More...
 
char * dc_chat_get_profile_image (const dc_chat_t *chat)
 Get the chat's profile image. More...
 
char * dc_chat_get_subtitle (const dc_chat_t *chat)
 Get a subtitle for a chat. More...
 
int dc_chat_get_type (const dc_chat_t *chat)
 Get chat type. More...
 
int dc_chat_is_self_talk (const dc_chat_t *chat)
 Check if a chat is a self talk. More...
 
int dc_chat_is_unpromoted (const dc_chat_t *chat)
 Check if a group chat is still unpromoted. More...
 
int dc_chat_is_verified (const dc_chat_t *chat)
 Check if a chat is verified. More...
 
void dc_chat_unref (dc_chat_t *chat)
 Free a chat object. More...
 

Detailed Description

An object representing a single chat in memory.

Chat objects are created using eg. dc_get_chat() and are not updated on database changes; if you want an update, you have to recreate the object.

Member Function Documentation

int dc_chat_get_archived ( const dc_chat_t chat)

Get archived state.

  • 0 = normal chat, not archived, not sticky.
  • 1 = chat archived
  • 2 = chat sticky (reserved for future use, if you do not support this value, just treat the chat as a normal one)

To archive or unarchive chats, use dc_archive_chat(). If chats are archived, this should be shown in the UI by a little icon or text, eg. the search will also return archived chats.

Parameters
chatThe chat object.
Returns
Archived state.
uint32_t dc_chat_get_color ( const dc_chat_t chat)

Get a color for the chat.

For 1:1 chats, the color is calculated from the contact's email address. Otherwise, the chat name is used. The color can be used for an fallback avatar with white initials as well as for headlines in bubbles of group chats.

Parameters
chatThe chat object.
Returns
Color as 0x00rrggbb with rr=red, gg=green, bb=blue each in the range 0-255.
uint32_t dc_chat_get_id ( const dc_chat_t chat)

Get chat ID.

The chat ID is the ID under which the chat is filed in the database.

Special IDs:

  • DC_CHAT_ID_DEADDROP (1) - Virtual chat containing messages which senders are not confirmed by the user.
  • DC_CHAT_ID_STARRED (5) - Virtual chat containing all starred messages-
  • DC_CHAT_ID_ARCHIVED_LINK (6) - A link at the end of the chatlist, if present the UI should show the button "Archived chats"-

"Normal" chat IDs are larger than these special IDs (larger than DC_CHAT_ID_LAST_SPECIAL).

Parameters
chatThe chat object.
Returns
Chat ID. 0 on errors.
char * dc_chat_get_name ( const dc_chat_t chat)

Get name of a chat.

For one-to-one chats, this is the name of the contact. For group chats, this is the name given eg. to dc_create_group_chat() or received by a group-creation message.

To change the name, use dc_set_chat_name()

See also: dc_chat_get_subtitle()

Parameters
chatThe chat object.
Returns
Chat name as a string. Must be free()'d after usage. Never NULL.
char * dc_chat_get_profile_image ( const dc_chat_t chat)

Get the chat's profile image.

For groups, this is the image set by any group member using dc_set_chat_profile_image(). For normal chats, this is the image set by each remote user on their own using dc_set_config(context, "selfavatar", image).

Parameters
chatThe chat object.
Returns
Path and file if the profile image, if any. NULL otherwise. Must be free()'d after usage.
char * dc_chat_get_subtitle ( const dc_chat_t chat)

Get a subtitle for a chat.

The subtitle is eg. the email-address or the number of group members.

See also: dc_chat_get_name()

Parameters
chatThe chat object to calulate the subtitle for.
Returns
Subtitle as a string. Must be free()'d after usage. Never NULL.
int dc_chat_get_type ( const dc_chat_t chat)

Get chat type.

Currently, there are two chat types:

  • DC_CHAT_TYPE_SINGLE (100) - 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 members, incl. DC_CONTACT_ID_SELF
  • DC_CHAT_TYPE_VERIFIED_GROUP (130) - a verified group chat. In verified groups, all members are verified and encryption is always active and cannot be disabled.
Parameters
chatThe chat object.
Returns
Chat type.
int dc_chat_is_self_talk ( const dc_chat_t chat)

Check if a chat is a self talk.

Self talks are normal chats with the only contact DC_CONTACT_ID_SELF.

Parameters
chatThe chat object.
Returns
1=chat is self talk, 0=chat is no self talk
int dc_chat_is_unpromoted ( const dc_chat_t chat)

Check if a group chat is still unpromoted.

After the creation with dc_create_group_chat() the chat is usually unpromoted until the first call to dc_send_text_msg() or another sending function.

With unpromoted chats, members can be added and settings can be modified without the need of special status messages being sent.

While the core takes care of the unpromoted state on its own, checking the state from the UI side may be useful to decide whether a hint as "Send the first message to allow others to reply within the group" should be shown to the user or not.

Parameters
chatThe chat object.
Returns
1=chat is still unpromoted, no message was ever send to the chat, 0=chat is not unpromoted, messages were send and/or received or the chat is not group chat.
int dc_chat_is_verified ( const dc_chat_t chat)

Check if a chat is verified.

Verified chats contain only verified members and encryption is alwasy enabled. Verified chats are created using dc_create_group_chat() by setting the 'verified' parameter to true.

Parameters
chatThe chat object.
Returns
1=chat verified, 0=chat is not verified
void dc_chat_unref ( dc_chat_t chat)

Free a chat object.

Parameters
chatChat object are returned eg. by dc_get_chat(). If NULL is given, nothing is done.
Returns
None.

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