Delta Chat Core C Interface
Macros
DC_EVENT

These constants are used as event-id in events returned by dc_get_next_event(). More...

Macros

#define DC_EVENT_CHAT_EPHEMERAL_TIMER_MODIFIED   2021
 Chat ephemeral timer changed.
 
#define DC_EVENT_CHAT_MODIFIED   2020
 Chat changed. More...
 
#define DC_EVENT_CONFIGURE_PROGRESS   2041
 Inform about the configuration progress started by dc_configure(). More...
 
#define DC_EVENT_CONTACTS_CHANGED   2030
 Contact(s) created, renamed, verified, blocked or deleted. More...
 
#define DC_EVENT_DELETED_BLOB_FILE   151
 Emitted when a blob file was successfully deleted. More...
 
#define DC_EVENT_ERROR   400
 The library-user should report an error to the end-user. More...
 
#define DC_EVENT_ERROR_NETWORK   401
 An action cannot be performed because there is no network available. More...
 
#define DC_EVENT_ERROR_SELF_NOT_IN_GROUP   410
 An action cannot be performed because the user is not in the group. More...
 
#define DC_EVENT_IMAP_CONNECTED   102
 Emitted when IMAP connection is established and login was successful. More...
 
#define DC_EVENT_IMAP_MESSAGE_DELETED   104
 Emitted when a message was successfully marked as deleted on the IMAP server. More...
 
#define DC_EVENT_IMAP_MESSAGE_MOVED   105
 Emitted when a message was successfully moved on IMAP. More...
 
#define DC_EVENT_IMEX_FILE_WRITTEN   2052
 A file has been exported. More...
 
#define DC_EVENT_IMEX_PROGRESS   2051
 Inform about the import/export progress started by dc_imex(). More...
 
#define DC_EVENT_INCOMING_MSG   2005
 There is a fresh message. More...
 
#define DC_EVENT_INFO   100
 The library-user may write an informational string to the log. More...
 
#define DC_EVENT_LOCATION_CHANGED   2035
 Location of one or more contact has changed. More...
 
#define DC_EVENT_MSG_DELIVERED   2010
 A single message is sent successfully. More...
 
#define DC_EVENT_MSG_FAILED   2012
 A single message could not be sent. More...
 
#define DC_EVENT_MSG_READ   2015
 A single message is read by the receiver. More...
 
#define DC_EVENT_MSGS_CHANGED   2000
 Messages or chats changed. More...
 
#define DC_EVENT_MSGS_NOTICED   2008
 Messages were marked noticed or seen. More...
 
#define DC_EVENT_NEW_BLOB_FILE   150
 Emitted when a new blob file was successfully written. More...
 
#define DC_EVENT_SECUREJOIN_INVITER_PROGRESS   2060
 Progress information of a secure-join handshake from the view of the inviter (Alice, the person who shows the QR code). More...
 
#define DC_EVENT_SECUREJOIN_JOINER_PROGRESS   2061
 Progress information of a secure-join handshake from the view of the joiner (Bob, the person who scans the QR code). More...
 
#define DC_EVENT_SMTP_CONNECTED   101
 Emitted when SMTP connection is established and login was successful. More...
 
#define DC_EVENT_SMTP_MESSAGE_SENT   103
 Emitted when a message was successfully sent to the SMTP server. More...
 
#define DC_EVENT_WARNING   300
 The library-user should write a warning string to the log. More...
 

Detailed Description

These constants are used as event-id in events returned by dc_get_next_event().

Events typically come with some additional data, use dc_event_get_data1_int(), dc_event_get_data2_int() and dc_event_get_data2_str() to read this data. The meaning of the data depends on the event.

Macro Definition Documentation

◆ DC_EVENT_CHAT_MODIFIED

#define DC_EVENT_CHAT_MODIFIED   2020

Chat changed.

The name or the image of a chat group was changed or members were added or removed. Or the verify state of a chat has changed. See dc_set_chat_name(), dc_set_chat_profile_image(), dc_add_contact_to_chat() and dc_remove_contact_from_chat().

Parameters
data1(int) chat_id
data20

◆ DC_EVENT_CONFIGURE_PROGRESS

#define DC_EVENT_CONFIGURE_PROGRESS   2041

Inform about the configuration progress started by dc_configure().

Parameters
data1(int) 0=error, 1-999=progress in permille, 1000=success and done
data2(char*) progress comment, error message or NULL if not applicable

◆ DC_EVENT_CONTACTS_CHANGED

#define DC_EVENT_CONTACTS_CHANGED   2030

Contact(s) created, renamed, verified, blocked or deleted.

Parameters
data1(int) contact_id of the changed contact or 0 on batch-changes or deletion.
data20

◆ DC_EVENT_DELETED_BLOB_FILE

#define DC_EVENT_DELETED_BLOB_FILE   151

Emitted when a blob file was successfully deleted.

Parameters
data10
data2(char*) Path name

◆ DC_EVENT_ERROR

#define DC_EVENT_ERROR   400

The library-user should report an error to the end-user.

As most things are asynchronous, things may go wrong at any time and the user should not be disturbed by a dialog or so. Instead, use a bubble or so.

However, for ongoing processes (e.g. dc_configure()) or for functions that are expected to fail (e.g. dc_continue_key_transfer()) it might be better to delay showing these events until the function has really failed (returned false). It should be sufficient to report only the last error in a message box then.

Parameters
data10
data2(char*) Error string, always set, never NULL. Some error strings are taken from dc_set_stock_translation(), however, most error strings will be in English language.

◆ DC_EVENT_ERROR_NETWORK

#define DC_EVENT_ERROR_NETWORK   401

An action cannot be performed because there is no network available.

The library will typically try over after a some time and when dc_maybe_network() is called.

Network errors should be reported to users in a non-disturbing way, however, as network errors may come in a sequence, it is not useful to raise each an every error to the user.

Moreover, if the UI detects that the device is offline, it is probably more useful to report this to the user instead of the string from data2.

Parameters
data10
data2(char*) Error string, always set, never NULL.

◆ DC_EVENT_ERROR_SELF_NOT_IN_GROUP

#define DC_EVENT_ERROR_SELF_NOT_IN_GROUP   410

An action cannot be performed because the user is not in the group.

Reported e.g. after a call to dc_set_chat_name(), dc_set_chat_profile_image(), dc_add_contact_to_chat(), dc_remove_contact_from_chat(), dc_send_text_msg() or another sending function.

Parameters
data10
data2(char*) Info string in English language.

◆ DC_EVENT_IMAP_CONNECTED

#define DC_EVENT_IMAP_CONNECTED   102

Emitted when IMAP connection is established and login was successful.

Parameters
data10
data2(char*) Info string in English language.

◆ DC_EVENT_IMAP_MESSAGE_DELETED

#define DC_EVENT_IMAP_MESSAGE_DELETED   104

Emitted when a message was successfully marked as deleted on the IMAP server.

Parameters
data10
data2(char*) Info string in English language.

◆ DC_EVENT_IMAP_MESSAGE_MOVED

#define DC_EVENT_IMAP_MESSAGE_MOVED   105

Emitted when a message was successfully moved on IMAP.

Parameters
data10
data2(char*) Info string in English language.

◆ DC_EVENT_IMEX_FILE_WRITTEN

#define DC_EVENT_IMEX_FILE_WRITTEN   2052

A file has been exported.

A file has been written by dc_imex(). This event may be sent multiple times by a single call to dc_imex().

A typical purpose for a handler of this event may be to make the file public to some system services.

Parameters
data10
data2(char*) Path and file name.

◆ DC_EVENT_IMEX_PROGRESS

#define DC_EVENT_IMEX_PROGRESS   2051

Inform about the import/export progress started by dc_imex().

Parameters
data1(int) 0=error, 1-999=progress in permille, 1000=success and done
data20

◆ DC_EVENT_INCOMING_MSG

#define DC_EVENT_INCOMING_MSG   2005

There is a fresh message.

Typically, the user will show an notification when receiving this message.

There is no extra DC_EVENT_MSGS_CHANGED event send together with this event.

Parameters
data1(int) chat_id
data2(int) msg_id

◆ DC_EVENT_INFO

#define DC_EVENT_INFO   100

The library-user may write an informational string to the log.

This event should not be reported to the end-user using a popup or something like that.

Parameters
data10
data2(char*) Info string in English language.

◆ DC_EVENT_LOCATION_CHANGED

#define DC_EVENT_LOCATION_CHANGED   2035

Location of one or more contact has changed.

Parameters
data1(int) contact_id of the contact for which the location has changed. If the locations of several contacts have been changed, e.g. after calling dc_delete_all_locations(), this parameter is set to 0.
data20

◆ DC_EVENT_MSG_DELIVERED

#define DC_EVENT_MSG_DELIVERED   2010

A single message is sent successfully.

State changed from DC_STATE_OUT_PENDING to DC_STATE_OUT_DELIVERED, see dc_msg_get_state().

Parameters
data1(int) chat_id
data2(int) msg_id

◆ DC_EVENT_MSG_FAILED

#define DC_EVENT_MSG_FAILED   2012

A single message could not be sent.

State changed from DC_STATE_OUT_PENDING, DC_STATE_OUT_DELIVERED or DC_STATE_OUT_MDN_RCVD to DC_STATE_OUT_FAILED, see dc_msg_get_state().

Parameters
data1(int) chat_id
data2(int) msg_id

◆ DC_EVENT_MSG_READ

#define DC_EVENT_MSG_READ   2015

A single message is read by the receiver.

State changed from DC_STATE_OUT_DELIVERED to DC_STATE_OUT_MDN_RCVD, see dc_msg_get_state().

Parameters
data1(int) chat_id
data2(int) msg_id

◆ DC_EVENT_MSGS_CHANGED

#define DC_EVENT_MSGS_CHANGED   2000

Messages or chats changed.

One or more messages or chats changed for various reasons in the database:

  • Messages sent, received or removed
  • Chats created, deleted or archived
  • A draft has been set
Parameters
data1(int) chat_id for single added messages
data2(int) msg_id for single added messages

◆ DC_EVENT_MSGS_NOTICED

#define DC_EVENT_MSGS_NOTICED   2008

Messages were marked noticed or seen.

The UI may update badge counters or stop showing a chatlist-item with a bold font.

This event is emitted e.g. when calling dc_markseen_msgs() or dc_marknoticed_chat() or when a chat is answered on another device. Do not try to derive the state of an item from just the fact you received the event; use e.g. dc_msg_get_state() or dc_get_fresh_msg_cnt() for this purpose.

Parameters
data1(int) chat_id
data20

◆ DC_EVENT_NEW_BLOB_FILE

#define DC_EVENT_NEW_BLOB_FILE   150

Emitted when a new blob file was successfully written.

Parameters
data10
data2(char*) Path name

◆ DC_EVENT_SECUREJOIN_INVITER_PROGRESS

#define DC_EVENT_SECUREJOIN_INVITER_PROGRESS   2060

Progress information of a secure-join handshake from the view of the inviter (Alice, the person who shows the QR code).

These events are typically sent after a joiner has scanned the QR code generated by dc_get_securejoin_qr().

Parameters
data1(int) ID of the contact that wants to join.
data2(int) Progress as: 300=vg-/vc-request received, typically shown as "bob@addr joins". 600=vg-/vc-request-with-auth received, vg-member-added/vc-contact-confirm sent, typically shown as "bob@addr verified". 800=vg-member-added-received received, shown as "bob@addr securely joined GROUP", only sent for the verified-group-protocol. 1000=Protocol finished for this contact.

◆ DC_EVENT_SECUREJOIN_JOINER_PROGRESS

#define DC_EVENT_SECUREJOIN_JOINER_PROGRESS   2061

Progress information of a secure-join handshake from the view of the joiner (Bob, the person who scans the QR code).

The events are typically sent while dc_join_securejoin(), which may take some time, is executed.

Parameters
data1(int) ID of the inviting contact.
data2(int) Progress as: 400=vg-/vc-request-with-auth sent, typically shown as "alice@addr verified, introducing myself." (Bob has verified alice and waits until Alice does the same for him)

◆ DC_EVENT_SMTP_CONNECTED

#define DC_EVENT_SMTP_CONNECTED   101

Emitted when SMTP connection is established and login was successful.

Parameters
data10
data2(char*) Info string in English language.

◆ DC_EVENT_SMTP_MESSAGE_SENT

#define DC_EVENT_SMTP_MESSAGE_SENT   103

Emitted when a message was successfully sent to the SMTP server.

Parameters
data10
data2(char*) Info string in English language.

◆ DC_EVENT_WARNING

#define DC_EVENT_WARNING   300

The library-user should write a warning string to the log.

This event should not be reported to the end-user using a popup or something like that.

Parameters
data10
data2(char*) Warning string in English language.