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

#include <deltachat.h>

Public Member Functions
int	dc_chat_can_send (const dc_chat_t *chat)
	Check if messages can be sent to a given chat.

uint32_t	dc_chat_get_color (const dc_chat_t *chat)
	Get a color for the chat.

uint32_t	dc_chat_get_id (const dc_chat_t *chat)
	Get the chat ID.

char *	dc_chat_get_mailinglist_addr (const dc_chat_t *chat)
	Returns the address where messages are sent to if the chat is a mailing list.

char *	dc_chat_get_name (const dc_chat_t *chat)
	Get name of a chat.

char *	dc_chat_get_profile_image (const dc_chat_t *chat)
	Get the chat's profile image.

int64_t	dc_chat_get_remaining_mute_duration (const dc_chat_t *chat)
	Get the exact state of the mute of a chat.

int	dc_chat_get_type (const dc_chat_t *chat)
	Get chat type as one of the DC_CHAT_TYPE constants:

int	dc_chat_get_visibility (const dc_chat_t *chat)
	Get visibility of chat.

int	dc_chat_is_contact_request (const dc_chat_t *chat)
	Check if a chat is a contact request chat.

int	dc_chat_is_device_talk (const dc_chat_t *chat)
	Check if a chat is a device-talk.

int	dc_chat_is_muted (const dc_chat_t *chat)
	Check whether the chat is currently muted (can be changed by dc_set_chat_mute_duration()).

int	dc_chat_is_protected (const dc_chat_t *chat)
	Check if a chat is protected.

int	dc_chat_is_protection_broken (const dc_chat_t *chat)
	Checks if the chat was protected, and then an incoming message broke this protection.

int	dc_chat_is_self_talk (const dc_chat_t *chat)
	Check if a chat is a self talk.

int	dc_chat_is_sending_locations (const dc_chat_t *chat)
	Check if locations are sent to the chat at the time the object was created using dc_get_chat().

int	dc_chat_is_unpromoted (const dc_chat_t *chat)
	Check if a group chat is still unpromoted.

void	dc_chat_unref (dc_chat_t *chat)
	Free a chat object.

Detailed Description

An object representing a single chat in memory.

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

Member Function Documentation

◆ dc_chat_can_send()

int dc_chat_can_send ( const dc_chat_t * chat )

Check if messages can be sent to a given chat.

This is not true e.g. for contact requests or for the device-talk, cmp. dc_chat_is_device_talk().

Calling dc_send_msg() for these chats will fail and the UI may decide to hide input controls therefore.

Parameters

chat	The chat object.

Returns: 1=chat is writable, 0=chat is not writable.

◆ dc_chat_get_color()

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 e-mail 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

chat	The chat object.

Returns: The color as 0x00rrggbb with rr=red, gg=green, bb=blue each in the range 0-255.

◆ dc_chat_get_id()

uint32_t dc_chat_get_id ( const dc_chat_t * chat )

Get the chat ID.

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

Special IDs:

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

chat	The chat object.

Returns: The chat ID. 0 on errors.

◆ dc_chat_get_mailinglist_addr()

char * dc_chat_get_mailinglist_addr ( const dc_chat_t * chat )

Returns the address where messages are sent to if the chat is a mailing list.

If you just want to know if a mailing list can be written to, use dc_chat_can_send() instead.

Parameters

chat	The chat object.

Returns: The mailing list address. Must be released using dc_str_unref() after usage. If there is no such address, an empty string is returned, NULL is never returned.

◆ dc_chat_get_name()

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 e.g. to dc_create_group_chat() or received by a group-creation message.

To change the name, use dc_set_chat_name()

Parameters

chat	The chat object.

Returns: The chat name as a string. Must be released using dc_str_unref() after usage. Never NULL.

◆ dc_chat_get_profile_image()

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

chat	The chat object.

Returns: Path and file of the profile image, if any. NULL otherwise. Must be released using dc_str_unref() after usage.

◆ dc_chat_get_remaining_mute_duration()

int64_t dc_chat_get_remaining_mute_duration ( const dc_chat_t * chat )

Get the exact state of the mute of a chat.

Parameters

chat	The chat object.

Returns: 0=not muted, -1=forever muted, (x>0)=remaining seconds until the mute is lifted.

◆ dc_chat_get_type()

int dc_chat_get_type ( const dc_chat_t * chat )

Get chat type as one of the DC_CHAT_TYPE constants:

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. These chats are created by dc_create_chat_by_contact_id().
DC_CHAT_TYPE_GROUP - a group chat, chats_contacts contain all group members, incl. DC_CONTACT_ID_SELF. Groups are created by dc_create_group_chat().
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. Mailing lists are created as needed by incoming messages and usually require some special server; they cannot be created by a function call as the other chat types. Moreover, for now, mailing lists are read-only.
DC_CHAT_TYPE_BROADCAST - a broadcast list, the recipients will get messages in a one-to-one chats and the sender will get answers in a one-to-one as well. chats_contacts contain all recipients but DC_CONTACT_ID_SELF. Broadcasts are created by dc_create_broadcast_list().

Parameters

chat	The chat object.

Returns: The chat type.

◆ dc_chat_get_visibility()

int dc_chat_get_visibility ( const dc_chat_t * chat )

Get visibility of chat.

See DC_CHAT_VISIBILITY for detailed information about the visibilities.

Parameters

chat	The chat object.

Returns: One of DC_CHAT_VISIBILITY

◆ dc_chat_is_contact_request()

int dc_chat_is_contact_request ( const dc_chat_t * chat )

Check if a chat is a contact request chat.

UI should display such chats with a [New] badge in the chatlist.

When such chat is opened, user should be presented with a set of options instead of the message composition area, for example:

Accept chat (dc_accept_chat())
Block chat (dc_block_chat())
Delete chat (dc_delete_chat())

Parameters

chat	The chat object.

Returns: 1=chat is a contact request chat, 0=chat is not a contact request chat.

◆ dc_chat_is_device_talk()

int dc_chat_is_device_talk ( const dc_chat_t * chat )

Check if a chat is a device-talk.

Device-talks contain update information and some hints that are added during the program runs, multi-device etc.

From the UI view, device-talks are not very special, the user can delete and forward messages, archive the chat, set notifications etc.

Messages can be added to the device-talk using dc_add_device_msg()

Parameters

chat	The chat object.

Returns: 1=chat is device talk, 0=chat is no device talk.

◆ dc_chat_is_muted()

int dc_chat_is_muted ( const dc_chat_t * chat )

Check whether the chat is currently muted (can be changed by dc_set_chat_mute_duration()).

Parameters

chat	The chat object.

Returns: 1=muted, 0=not muted

◆ dc_chat_is_protected()

int dc_chat_is_protected ( const dc_chat_t * chat )

Check if a chat is protected.

End-to-end encryption is guaranteed in protected chats and only verified contacts as determined by dc_contact_is_verified() can be added to protected chats.

Protected chats are created using dc_create_group_chat() by setting the 'protect' parameter to 1. 1:1 chats become protected or unprotected automatically if verified_one_on_one_chats setting is enabled.

UI should display a green checkmark in the chat title, in the chatlist item and in the chat profile if chat protection is enabled.

Parameters

chat	The chat object.

Returns: 1=chat protected, 0=chat is not protected.

◆ dc_chat_is_protection_broken()

int dc_chat_is_protection_broken ( const dc_chat_t * chat )

Checks if the chat was protected, and then an incoming message broke this protection.

This function is only useful if the UI enabled the verified_one_on_one_chats feature flag, otherwise it will return false for all chats.

1:1 chats are automatically set as protected when a contact is verified. When a message comes in that is not encrypted / signed correctly, the chat is automatically set as unprotected again. dc_chat_is_protection_broken() will return true until dc_accept_chat() is called.

The UI should let the user confirm that this is OK with a message like Bob sent a message from another device. Tap to learn more and then call dc_accept_chat().

Parameters

chat	The chat object.

Returns: 1=chat protection broken, 0=otherwise.

◆ dc_chat_is_self_talk()

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

chat	The chat object.

Returns: 1=chat is self talk, 0=chat is no self talk.

◆ dc_chat_is_sending_locations()

int dc_chat_is_sending_locations ( const dc_chat_t * chat )

Check if locations are sent to the chat at the time the object was created using dc_get_chat().

To check if locations are sent to any chat, use dc_is_sending_locations_to_chat().

Parameters

chat	The chat object.

Returns: 1=locations are sent to chat, 0=no locations are sent to chat.

◆ dc_chat_is_unpromoted()

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

chat	The 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.

◆ dc_chat_unref()

void dc_chat_unref ( dc_chat_t * chat )

Free a chat object.

Parameters

chat	Chat object are returned e.g. by dc_get_chat(). If NULL is given, nothing is done.

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

deltachat.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ dc_chat_can_send()

◆ dc_chat_get_color()

◆ dc_chat_get_id()

◆ dc_chat_get_mailinglist_addr()

◆ dc_chat_get_name()

◆ dc_chat_get_profile_image()

◆ dc_chat_get_remaining_mute_duration()

◆ dc_chat_get_type()

◆ dc_chat_get_visibility()

◆ dc_chat_is_contact_request()

◆ dc_chat_is_device_talk()

◆ dc_chat_is_muted()

◆ dc_chat_is_protected()

◆ dc_chat_is_protection_broken()

◆ dc_chat_is_self_talk()

◆ dc_chat_is_sending_locations()

◆ dc_chat_is_unpromoted()

◆ dc_chat_unref()