Delta Chat Core C Interface
Loading...
Searching...
No Matches
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_can_send (const dc_chat_t *chat)
 Check if messages can be sent to a given chat. 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 the chat ID. More...
 
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. 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...
 
int64_t dc_chat_get_remaining_mute_duration (const dc_chat_t *chat)
 Get the exact state of the mute of a chat. More...
 
int dc_chat_get_type (const dc_chat_t *chat)
 Get chat type as one of the DC_CHAT_TYPE constants: More...
 
int dc_chat_get_visibility (const dc_chat_t *chat)
 Get visibility of chat. More...
 
int dc_chat_is_contact_request (const dc_chat_t *chat)
 Check if a chat is a contact request chat. More...
 
int dc_chat_is_device_talk (const dc_chat_t *chat)
 Check if a chat is a device-talk. More...
 
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()). More...
 
int dc_chat_is_protected (const dc_chat_t *chat)
 Check if a chat is protected. 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_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(). More...
 
int dc_chat_is_unpromoted (const dc_chat_t *chat)
 Check if a group chat is still unpromoted. 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 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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
chatThe 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.

Protected chats contain only verified members and encryption is always enabled. Protected chats are created using dc_create_group_chat() by setting the 'protect' parameter to 1. The status can be changed using dc_set_chat_protection().

Parameters
chatThe chat object.
Returns
1=chat protected, 0=chat is not protected.

◆ 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
chatThe 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
chatThe 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
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.

◆ dc_chat_unref()

void dc_chat_unref ( dc_chat_t chat)

Free a chat object.

Parameters
chatChat 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: