Delta Chat Core C-API
 All Classes Functions Typedefs Groups Pages
Macros
DC_EVENT

These constants are used as events reported to the callback given to dc_context_new(). More...

Macros

#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, blocked or deleted. More...
 
#define DC_EVENT_ERROR   400
 The library-user should report an error to the end-user. More...
 
#define DC_EVENT_GET_STRING   2091
 Requeste a localized string from the frontend. More...
 
#define DC_EVENT_HTTP_GET   2100
 Request a HTTP-file or HTTPS-file from the frontend. More...
 
#define DC_EVENT_IMAP_CONNECTED   102
 Emitted when IMAP connection is established and login was successful. 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_IS_OFFLINE   2081
 Ask the frontend about the offline state. 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_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 events reported to the callback given to dc_context_new().

If you do not want to handle an event, it is always safe to return 0, so there is no need to add a "case" for every event.

Macro Definition Documentation

#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
Returns
0
#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
data20
Returns
0
#define DC_EVENT_CONTACTS_CHANGED   2030

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

Parameters
data1(int) If not 0, this is the contact_id of an added contact that should be selected.
data20
Returns
0
#define DC_EVENT_ERROR   400

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

Passed to the callback given to dc_context_new().

As most things are asynchrounous, 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 (eg. dc_configure()) or for functions that are expected to fail (eg. 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 messasge box then.

Parameters
data1(int) Error code, see DC_ERROR for a list of constants.
data2(const char*) Error string, always set, never NULL. Frequent error strings are localized using DC_EVENT_GET_STRING, however, most error strings will be in english language. Must not be free()'d or modified and is valid only until the callback returns.
Returns
0
#define DC_EVENT_GET_STRING   2091

Requeste a localized string from the frontend.

Parameters
data1(int) ID of the string to request, one of the DC_STR_* constants.
data2(int) The count. If the requested string contains a placeholder for a numeric value, the ui may use this value to return different strings on different plural forms.
Returns
(const char*) Null-terminated UTF-8 string. The string will be free()'d by the core, so it must be allocated using malloc() or a compatible function. Return 0 if the ui cannot provide the requested string the core will use a default string in english language then.
#define DC_EVENT_HTTP_GET   2100

Request a HTTP-file or HTTPS-file from the frontend.

Parameters
data1(const char*) Null-terminated UTF-8 string containing the URL. The string starts with https:// or http://. Must not be free()'d or modified and is valid only until the callback returns.
data20
Returns
(const char*) The content of the requested file as a null-terminated UTF-8 string; Response headers, encodings etc. must be stripped, only the raw file, which may be binary, should be returned. CAVE: The string will be free()'d by the core, so make sure it is allocated using malloc() or a compatible function. If you cannot provide the content, just return 0 or an empty string.
#define DC_EVENT_IMAP_CONNECTED   102

Emitted when IMAP connection is established and login was successful.

Parameters
data10
data2(const char*) Info string in english language. Must not be free()'d or modified and is valid only until the callback returns.
Returns
0
#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
data1(const char*) Path and file name. Must not be free()'d or modified and is valid only until the callback returns.
data20
Returns
0
#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
Returns
0
#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
Returns
0
#define DC_EVENT_INFO   100

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

Passed to the callback given to dc_context_new().

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

Parameters
data10
data2(const char*) Info string in english language. Must not be free()'d or modified and is valid only until the callback returns.
Returns
0
#define DC_EVENT_IS_OFFLINE   2081

Ask the frontend about the offline state.

This function may be provided by the frontend. If we already know, that we're offline, eg. there is no need to try to connect and things will speed up.

Parameters
data10
data20
Returns
0=online, 1=offline
#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
Returns
0
#define DC_EVENT_MSG_FAILED   2012

A single message could not be sent.

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

Parameters
data1(int) chat_id
data2(int) msg_id
Returns
0
#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
Returns
0
#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
Returns
0
#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.
Returns
0
#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)
Returns
0
#define DC_EVENT_SMTP_CONNECTED   101

Emitted when SMTP connection is established and login was successful.

Parameters
data10
data2(const char*) Info string in english language. Must not be free()'d or modified and is valid only until the callback returns.
Returns
0
#define DC_EVENT_SMTP_MESSAGE_SENT   103

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

Parameters
data10
data2(const char*) Info string in english language. Must not be free()'d or modified and is valid only until the callback returns.
Returns
0
#define DC_EVENT_WARNING   300

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

Passed to the callback given to dc_context_new().

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

Parameters
data10
data2(const char*) Warning string in english language. Must not be free()'d or modified and is valid only until the callback returns.
Returns
0