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

An object representing a single account. More...

#include <deltachat.h>

Public Types

typedef uintptr_t(* dc_callback_t )(dc_context_t *, int event, uintptr_t data1, uintptr_t data2)
 Callback function that should be given to dc_context_new(). More...
 

Public Member Functions

int dc_add_address_book (dc_context_t *context, const char *adr_book)
 Add a number of contacts. More...
 
int dc_add_contact_to_chat (dc_context_t *context, uint32_t chat_id, uint32_t contact_id)
 Add a member to a group. More...
 
void dc_archive_chat (dc_context_t *context, uint32_t chat_id, int archive)
 Archive or unarchive a chat. More...
 
void dc_block_contact (dc_context_t *context, uint32_t contact_id, int new_blocking)
 Block or unblock a contact. More...
 
dc_lot_tdc_check_qr (dc_context_t *context, const char *qr)
 Check a scanned QR code. More...
 
void dc_close (dc_context_t *context)
 Close context database opened by dc_open(). More...
 
void dc_configure (dc_context_t *context)
 Configure a context. More...
 
dc_context_tdc_context_new (dc_callback_t cb, void *userdata, const char *os_name)
 Create a new context object. More...
 
void dc_context_unref (dc_context_t *context)
 Free a context object. More...
 
uint32_t dc_create_chat_by_contact_id (dc_context_t *context, uint32_t contact_id)
 Create a normal chat with a single user. More...
 
uint32_t dc_create_chat_by_msg_id (dc_context_t *context, uint32_t msg_id)
 Create a normal chat or a group chat by a messages ID that comes typically from the deaddrop, DC_CHAT_ID_DEADDROP (1). More...
 
uint32_t dc_create_contact (dc_context_t *context, const char *name, const char *addr)
 Add a single contact as a result of an explicit user action. More...
 
uint32_t dc_create_group_chat (dc_context_t *context, int verified, const char *chat_name)
 Create a new group chat. More...
 
void dc_delete_chat (dc_context_t *context, uint32_t chat_id)
 Delete a chat. More...
 
int dc_delete_contact (dc_context_t *context, uint32_t contact_id)
 Delete a contact. More...
 
void dc_delete_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt)
 Delete messages. More...
 
void dc_forward_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt, uint32_t chat_id)
 Forward messages to another chat. More...
 
char * dc_get_blobdir (const dc_context_t *context)
 Get the blob directory. More...
 
int dc_get_blocked_cnt (dc_context_t *context)
 Get the number of blocked contacts. More...
 
dc_array_tdc_get_blocked_contacts (dc_context_t *context)
 Get blocked contacts. More...
 
dc_chat_tdc_get_chat (dc_context_t *context, uint32_t chat_id)
 Get chat object by a chat ID. More...
 
dc_array_tdc_get_chat_contacts (dc_context_t *context, uint32_t chat_id)
 Get contact IDs belonging to a chat. More...
 
uint32_t dc_get_chat_id_by_contact_id (dc_context_t *context, uint32_t contact_id)
 Check, if there is a normal chat with a given contact. More...
 
dc_array_tdc_get_chat_media (dc_context_t *context, uint32_t chat_id, int msg_type, int or_msg_type)
 Returns all message IDs of the given types in a chat. More...
 
dc_array_tdc_get_chat_msgs (dc_context_t *context, uint32_t chat_id, uint32_t flags, uint32_t marker1before)
 Get all message IDs belonging to a chat. More...
 
dc_chatlist_tdc_get_chatlist (dc_context_t *context, int listflags, const char *query_str, uint32_t query_id)
 Get a list of chats. More...
 
char * dc_get_config (dc_context_t *context, const char *key)
 Get a configuration option. More...
 
dc_contact_tdc_get_contact (dc_context_t *context, uint32_t contact_id)
 Get a single contact object. More...
 
char * dc_get_contact_encrinfo (dc_context_t *context, uint32_t contact_id)
 Get encryption info for a contact. More...
 
dc_array_tdc_get_contacts (dc_context_t *context, uint32_t listflags, const char *query)
 Returns known and unblocked contacts. More...
 
dc_msg_tdc_get_draft (dc_context_t *context, uint32_t chat_id)
 Get draft for a chat, if any. More...
 
int dc_get_fresh_msg_cnt (dc_context_t *context, uint32_t chat_id)
 Get the number of fresh messages in a chat. More...
 
dc_array_tdc_get_fresh_msgs (dc_context_t *context)
 Returns the message IDs of all fresh messages of any chat. More...
 
char * dc_get_info (dc_context_t *context)
 Get information about the context. More...
 
char * dc_get_mime_headers (dc_context_t *context, uint32_t msg_id)
 Get the raw mime-headers of the given message. More...
 
dc_msg_tdc_get_msg (dc_context_t *context, uint32_t msg_id)
 Get a single message object of the type dc_msg_t. More...
 
int dc_get_msg_cnt (dc_context_t *context, uint32_t chat_id)
 Get the total number of messages in a chat. More...
 
char * dc_get_msg_info (dc_context_t *context, uint32_t msg_id)
 Get an informational text for a single message. More...
 
uint32_t dc_get_next_media (dc_context_t *context, uint32_t curr_msg_id, int dir)
 Get next/previous message of the same type. More...
 
void * dc_get_userdata (dc_context_t *context)
 Get user data associated with a context object. More...
 
void dc_interrupt_imap_idle (dc_context_t *context)
 Interrupt waiting for imap-jobs. More...
 
void dc_interrupt_smtp_idle (dc_context_t *context)
 Interrupt waiting for smtp-jobs. More...
 
int dc_is_configured (const dc_context_t *context)
 Check if the context is already configured. More...
 
int dc_is_contact_in_chat (dc_context_t *context, uint32_t chat_id, uint32_t contact_id)
 Check if a given contact ID is a member of a group chat. More...
 
int dc_is_open (const dc_context_t *context)
 Check if the context database is open. More...
 
uint32_t dc_lookup_contact_id_by_addr (dc_context_t *context, const char *addr)
 Check if an e-mail address belongs to a known and unblocked contact. More...
 
void dc_marknoticed_all_chats (dc_context_t *context)
 Same as dc_marknoticed_chat() but for all chats. More...
 
void dc_marknoticed_chat (dc_context_t *context, uint32_t chat_id)
 Mark all messages in a chat as noticed. More...
 
void dc_marknoticed_contact (dc_context_t *context, uint32_t contact_id)
 Mark all messages sent by the given contact as noticed. More...
 
void dc_markseen_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt)
 Mark a message as seen, updates the IMAP state and sends MDNs. More...
 
int dc_may_be_valid_addr (const char *addr)
 Rough check if a string may be a valid e-mail address. More...
 
void dc_maybe_network (dc_context_t *context)
 This function can be called whenever there is a hint that the network is available again. More...
 
int dc_open (dc_context_t *context, const char *dbfile, const char *blobdir)
 Open context database. More...
 
void dc_openssl_init_not_required (void)
 Skip OpenSSL initialisation. More...
 
void dc_perform_imap_fetch (dc_context_t *context)
 Fetch new messages, if any. More...
 
void dc_perform_imap_idle (dc_context_t *context)
 Wait for messages or jobs. More...
 
void dc_perform_imap_jobs (dc_context_t *context)
 Execute pending imap-jobs. More...
 
void dc_perform_smtp_idle (dc_context_t *context)
 Wait for smtp-jobs. More...
 
void dc_perform_smtp_jobs (dc_context_t *context)
 Execute pending smtp-jobs. More...
 
int dc_remove_contact_from_chat (dc_context_t *context, uint32_t chat_id, uint32_t contact_id)
 Remove a member from a group. More...
 
dc_array_tdc_search_msgs (dc_context_t *context, uint32_t chat_id, const char *query)
 Search messages containing the given query string. More...
 
uint32_t dc_send_msg (dc_context_t *context, uint32_t chat_id, dc_msg_t *msg)
 Send a message defined by a dc_msg_t object to a chat. More...
 
uint32_t dc_send_text_msg (dc_context_t *context, uint32_t chat_id, const char *text_to_send)
 Send a simple text message a given chat. More...
 
int dc_set_chat_name (dc_context_t *context, uint32_t chat_id, const char *new_name)
 Set group name. More...
 
int dc_set_chat_profile_image (dc_context_t *context, uint32_t chat_id, const char *new_image)
 Set group profile image. More...
 
int dc_set_config (dc_context_t *context, const char *key, const char *value)
 Configure the context. More...
 
void dc_set_draft (dc_context_t *context, uint32_t chat_id, dc_msg_t *msg)
 Save a draft for a chat in the database. More...
 
void dc_star_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt, int star)
 Star/unstar messages by setting the last parameter to 0 (unstar) or 1 (star). More...
 
void dc_stop_ongoing_process (dc_context_t *context)
 Signal an ongoing process to stop. More...
 

Import/Export

char * dc_initiate_key_transfer (dc_context_t *context)
 Initiate Autocrypt Setup Transfer. More...
 
int dc_continue_key_transfer (dc_context_t *context, uint32_t msg_id, const char *setup_code)
 Continue the Autocrypt Key Transfer on another device. More...
 
void dc_imex (dc_context_t *context, int what, const char *param1, const char *param2)
 Import/export things. More...
 
char * dc_imex_has_backup (dc_context_t *context, const char *dir_name)
 Check if there is a backup file. More...
 
int dc_check_password (dc_context_t *context, const char *test_pw)
 Check if the user is authorized by the given password in some way. More...
 

Secure Join

char * dc_get_securejoin_qr (dc_context_t *context, uint32_t group_chat_id)
 Get QR code text that will offer an secure-join verification. More...
 
uint32_t dc_join_securejoin (dc_context_t *context, const char *qr)
 Join an out-of-band-verification initiated on another device with dc_get_securejoin_qr(). More...
 

Detailed Description

An object representing a single account.

Each account is linked to an IMAP/SMTP account and uses a separate SQLite database for offline functionality and for account-related settings.

Member Typedef Documentation

typedef uintptr_t(* dc_callback_t)(dc_context_t *, int event, uintptr_t data1, uintptr_t data2)

Callback function that should be given to dc_context_new().

Parameters
contextThe context object as returned by dc_context_new().
eventone of the DC_EVENT constants
data1depends on the event parameter
data2depends on the event parameter
Returns
return 0 unless stated otherwise in the event parameter documentation

Member Function Documentation

int dc_add_address_book ( dc_context_t context,
const char *  adr_book 
)

Add a number of contacts.

Typically used to add the whole address book from the OS. As names here are typically not well formatted, we call normalize() for each name given.

No email-address is added twice. Trying to add email-addresses that are already in the contact list, results in updating the name unless the name was changed manually by the user. If any email-address or any name is really updated, the event DC_EVENT_CONTACTS_CHANGED is sent.

To add a single contact entered by the user, you should prefer dc_create_contact(), however, for adding a bunch of addresses, this function is much faster.

Parameters
contextthe context object as created by dc_context_new().
adr_bookA multi-line string in the format Name one\nAddress one\nName two\nAddress two. If an email address already exists, the name is updated unless it was edited manually by dc_create_contact() before.
Returns
The number of modified or added contacts.
int dc_add_contact_to_chat ( dc_context_t context,
uint32_t  chat_id,
uint32_t  contact_id 
)

Add a member to a group.

If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.

If the group is a verified group, only verified contacts can be added to the group.

Sends out DC_EVENT_CHAT_MODIFIED and DC_EVENT_MSGS_CHANGED if a status message was sent.

Parameters
contextThe context as created by dc_context_new().
chat_idThe chat ID to add the contact to. Must be a group chat.
contact_idThe contact ID to add to the chat.
Returns
1=member added to group, 0=error
void dc_archive_chat ( dc_context_t context,
uint32_t  chat_id,
int  archive 
)

Archive or unarchive a chat.

Archived chats are not included in the default chatlist returned by dc_get_chatlist(). Instead, if there are any archived chats, the pseudo-chat with the chat_id DC_CHAT_ID_ARCHIVED_LINK will be added the the end of the chatlist.

  • To get a list of archived chats, use dc_get_chatlist() with the flag DC_GCL_ARCHIVED_ONLY.
  • To find out the archived state of a given chat, use dc_chat_get_archived()
  • Messages in archived chats are marked as being noticed, so they do not count as "fresh"
  • Calling this function usually results in the event DC_EVENT_MSGS_CHANGED
Parameters
contextThe context object as returned from dc_context_new().
chat_idThe ID of the chat to archive or unarchive.
archive1=archive chat, 0=unarchive chat, all other values are reserved for future use
Returns
None.
void dc_block_contact ( dc_context_t context,
uint32_t  contact_id,
int  new_blocking 
)

Block or unblock a contact.

May result in a DC_EVENT_CONTACTS_CHANGED event.

Parameters
contextThe context object as created by dc_context_new().
contact_idThe ID of the contact to block or unblock.
new_blocking1=block contact, 0=unblock contact
Returns
None.
int dc_check_password ( dc_context_t context,
const char *  test_pw 
)

Check if the user is authorized by the given password in some way.

This is to prompt for the password eg. before exporting keys/backup.

Parameters
contextThe context as created by dc_context_new().
test_pwPassword to check.
Returns
1=user is authorized, 0=user is not authorized.
dc_lot_t * dc_check_qr ( dc_context_t context,
const char *  qr 
)

Check a scanned QR code.

The function should be called after a QR code is scanned. The function takes the raw text scanned and checks what can be done with it.

The QR code state is returned in dc_lot_t::state as:

  • DC_QR_ASK_VERIFYCONTACT with dc_lot_t::id=Contact ID
  • DC_QR_ASK_VERIFYGROUP withdc_lot_t::text1=Group name
  • DC_QR_FPR_OK with dc_lot_t::id=Contact ID
  • DC_QR_FPR_MISMATCH with dc_lot_t::id=Contact ID
  • DC_QR_FPR_WITHOUT_ADDR with dc_lot_t::test1=Formatted fingerprint
  • DC_QR_ADDR with dc_lot_t::id=Contact ID
  • DC_QR_TEXT with dc_lot_t::text1=Text
  • DC_QR_URL with dc_lot_t::text1=URL
  • DC_QR_ERROR with dc_lot_t::text1=Error string
Parameters
contextThe context object.
qrThe text of the scanned QR code.
Returns
Parsed QR code as an dc_lot_t object. The returned object must be freed using dc_lot_unref() after usage.
void dc_close ( dc_context_t context)

Close context database opened by dc_open().

Before this, connections to SMTP and IMAP are closed; these connections are started automatically as needed eg. by sending for fetching messages. This function is also implicitly called by dc_context_unref(). Multiple calls to this functions are okay, the function takes care not to free objects twice.

Parameters
contextThe context object as created by dc_context_new().
Returns
None.
void dc_configure ( dc_context_t context)

Configure a context.

For this purpose, the function creates a job that is executed in the IMAP-thread then; this requires to call dc_perform_imap_jobs() regularly. If the context is already configured, this function will try to change the configuration.

  • Before you call this function, you must set at least addr and mail_pw using dc_set_config().
  • Use mail_user to use a different user name than addr and send_pw to use a different password for the SMTP server.
    • If no more options are specified, the function uses autoconfigure/autodiscover to get the full configuration from well-known URLs.
    • If more options as mail_server, mail_port, send_server, send_port, send_user or server_flags are specified, autoconfigure/autodiscover is skipped.

While dc_configure() returns immediately, the started configuration-job may take a while.

During configuration, DC_EVENT_CONFIGURE_PROGRESS events are emmited; they indicate a successful configuration as well as errors and may be used to create a progress bar.

Additional calls to dc_configure() while a config-job is running are ignored. To interrupt a configuration prematurely, use dc_stop_ongoing_process(); this is not needed if DC_EVENT_CONFIGURE_PROGRESS reports success.

On a successfull configuration, the core makes a copy of the parameters mentioned above: the original parameters as are never modified by the core.

UI-implementors should keep this in mind - eg. if the UI wants to prefill a configure-edit-dialog with these parameters, the UI should reset them if the user cancels the dialog after a configure-attempts has failed. Otherwise the parameters may not reflect the current configuation.

Parameters
contextThe context object as created by dc_context_new().
Returns
None.

There is no need to call dc_configure() on every program start, the configuration result is saved in the database and you can use the connection directly:

if (!dc_is_configured(context)) {
dc_configure(context);
// wait for progress events
}
dc_context_t * dc_context_new ( dc_callback_t  cb,
void *  userdata,
const char *  os_name 
)

Create a new context object.

After creation it is usually opened, connected and mails are fetched.

Parameters
cba callback function that is called for events (update, state changes etc.) and to get some information from the client (eg. translation for a given string). See DC_EVENT for a list of possible events that may be passed to the callback.
  • The callback MAY be called from any thread, not only the main/GUI thread!
  • The callback MUST NOT call any dc_* and related functions unless stated otherwise!
  • The callback SHOULD return fast, for GUI updates etc. you should post yourself an asynchronous message to your GUI thread, if needed.
  • If not mentioned otherweise, the callback should return 0.
userdatacan be used by the client for any purpuse. He finds it later in dc_get_userdata().
os_nameis only for decorative use and is shown eg. in the X-Mailer: header in the form "Delta Chat <version> for <os_name>". You can give the name of the operating system and/or the used environment here. It is okay to give NULL, in this case X-Mailer: header is set to "Delta Chat <version>".
Returns
A context object with some public members. The object must be passed to the other context functions and must be freed using dc_context_unref() after usage.
void dc_context_unref ( dc_context_t context)

Free a context object.

If app runs can only be terminated by a forced kill, this may be superfluous. Before the context object is freed, connections to SMTP, IMAP and database are closed. You can also do this explicitly by calling dc_close() on your own before calling dc_context_unref().

Parameters
contextThe context object as created by dc_context_new(). If NULL is given, nothing is done.
Returns
None.
int dc_continue_key_transfer ( dc_context_t context,
uint32_t  msg_id,
const char *  setup_code 
)

Continue the Autocrypt Key Transfer on another device.

If you have started the key transfer on another device using dc_initiate_key_transfer() and you've detected a setup message with dc_msg_is_setupmessage(), you should prompt the user for the setup code and call this function then.

You can use dc_msg_get_setupcodebegin() to give the user a hint about the code (useful if the user has created several messages and should not enter the wrong code).

Parameters
contextThe context object.
msg_idID of the setup message to decrypt.
setup_codeSetup code entered by the user. This is the same setup code as returned from dc_initiate_key_transfer() on the other device. There is no need to format the string correctly, the function will remove all spaces and other characters and insert the - characters at the correct places.
Returns
1=key successfully decrypted and imported; both devices will use the same key now; 0=key transfer failed eg. due to a bad setup code.
uint32_t dc_create_chat_by_contact_id ( dc_context_t context,
uint32_t  contact_id 
)

Create a normal chat with a single user.

To create group chats, see dc_create_group_chat().

If a chat already exists, this ID is returned, otherwise a new chat is created; this new chat may already contain messages, eg. from the deaddrop, to get the chat messages, use dc_get_chat_msgs().

Parameters
contextThe context object as returned from dc_context_new().
contact_idThe contact ID to create the chat for. If there is already a chat with this contact, the already existing ID is returned.
Returns
The created or reused chat ID on success. 0 on errors.
uint32_t dc_create_chat_by_msg_id ( dc_context_t context,
uint32_t  msg_id 
)

Create a normal chat or a group chat by a messages ID that comes typically from the deaddrop, DC_CHAT_ID_DEADDROP (1).

If the given message ID already belongs to a normal chat or to a group chat, the chat ID of this chat is returned and no new chat is created. If a new chat is created, the given message ID is moved to this chat, however, there may be more messages moved to the chat from the deaddrop. To get the chat messages, use dc_get_chat_msgs().

If the user is asked before creation, he should be asked whether he wants to chat with the contact belonging to the message; the group names may be really weird when taken from the subject of implicit groups and this may look confusing.

Moreover, this function also scales up the origin of the contact belonging to the message and, depending on the contacts origin, messages from the same group may be shown or not - so, all in all, it is fine to show the contact name only.

Parameters
contextThe context object as returned from dc_context_new().
msg_idThe message ID to create the chat for.
Returns
The created or reused chat ID on success. 0 on errors.
uint32_t dc_create_contact ( dc_context_t context,
const char *  name,
const char *  addr 
)

Add a single contact as a result of an explicit user action.

We assume, the contact name, if any, is entered by the user and is used "as is" therefore, normalize() is not called for the name. If the contact is blocked, it is unblocked.

To add a number of contacts, see dc_add_address_book() which is much faster for adding a bunch of addresses.

May result in a DC_EVENT_CONTACTS_CHANGED event.

Parameters
contextThe context object as created by dc_context_new().
nameName of the contact to add. If you do not know the name belonging to the address, you can give NULL here.
addrE-mail-address of the contact to add. If the email address already exists, the name is updated and the origin is increased to "manually created".
Returns
Contact ID of the created or reused contact.
uint32_t dc_create_group_chat ( dc_context_t context,
int  verified,
const char *  chat_name 
)

Create a new group chat.

After creation, the draft of the chat is set to a default text, the group has one member with the ID DC_CONTACT_ID_SELF and is in unpromoted state. This means, you can add or remove members, change the name, the group image and so on without messages being sent to all group members.

This changes as soon as the first message is sent to the group members and the group becomes promoted. After that, all changes are synced with all group members by sending status message.

To check, if a chat is still unpromoted, you dc_chat_is_unpromoted(). This may be useful if you want to show some help for just created groups.

Parameters
contextThe context as created by dc_context_new().
verifiedIf set to 1 the function creates a secure verified group. Only secure-verified members are allowed in these groups and end-to-end-encryption is always enabled.
chat_nameThe name of the group chat to create. The name may be changed later using dc_set_chat_name(). To find out the name of a group later, see dc_chat_get_name()
Returns
The chat ID of the new group chat, 0 on errors.
void dc_delete_chat ( dc_context_t context,
uint32_t  chat_id 
)

Delete a chat.

Messages are deleted from the device and the chat database entry is deleted. After that, the event DC_EVENT_MSGS_CHANGED is posted.

Things that are not done implicitly:

  • Messages are not deleted from the server.
  • The chat or the contact is not blocked, so new messages from the user/the group may appear and the user may create the chat again.
  • Groups are not left - this would be unexpected as (1) deleting a normal chat also does not prevent new mails from arriving, (2) leaving a group requires sending a message to all group members - especially for groups not used for a longer time, this is really unexpected when deletion results in contacting all members again, (3) only leaving groups is also a valid usecase.

To leave a chat explicitly, use dc_remove_contact_from_chat() with chat_id=DC_CONTACT_ID_SELF)

Parameters
contextThe context object as returned from dc_context_new().
chat_idThe ID of the chat to delete.
Returns
None.
int dc_delete_contact ( dc_context_t context,
uint32_t  contact_id 
)

Delete a contact.

The contact is deleted from the local device. It may happen that this is not possible as the contact is in use. In this case, the contact can be blocked.

May result in a DC_EVENT_CONTACTS_CHANGED event.

Parameters
contextThe context object as created by dc_context_new().
contact_idID of the contact to delete.
Returns
1=success, 0=error
void dc_delete_msgs ( dc_context_t context,
const uint32_t *  msg_ids,
int  msg_cnt 
)

Delete messages.

The messages are deleted on the current device and on the IMAP server.

Parameters
contextThe context object as created by dc_context_new()
msg_idsan array of uint32_t containing all message IDs that should be deleted
msg_cntThe number of messages IDs in the msg_ids array
Returns
None.
void dc_forward_msgs ( dc_context_t context,
const uint32_t *  msg_ids,
int  msg_cnt,
uint32_t  chat_id 
)

Forward messages to another chat.

Parameters
contextThe context object as created by dc_context_new()
msg_idsAn array of uint32_t containing all message IDs that should be forwarded
msg_cntThe number of messages IDs in the msg_ids array
chat_idThe destination chat ID.
Returns
None.
char * dc_get_blobdir ( const dc_context_t context)

Get the blob directory.

Parameters
contextThe context object as created by dc_context_new().
Returns
Blob directory associated with the context object, empty string if unset or on errors. NULL is never returned. The returned string must be free()'d.
int dc_get_blocked_cnt ( dc_context_t context)

Get the number of blocked contacts.

Parameters
contextThe context object as created by dc_context_new().
Returns
The number of blocked contacts.
dc_array_t * dc_get_blocked_contacts ( dc_context_t context)

Get blocked contacts.

Parameters
contextThe context object as created by dc_context_new().
Returns
An array containing all blocked contact IDs. Must be dc_array_unref()'d after usage.
dc_chat_t * dc_get_chat ( dc_context_t context,
uint32_t  chat_id 
)

Get chat object by a chat ID.

Parameters
contextThe context object as returned from dc_context_new().
chat_idThe ID of the chat to get the chat object for.
Returns
A chat object of the type dc_chat_t, must be freed using dc_chat_unref() when done. On errors, NULL is returned.
dc_array_t * dc_get_chat_contacts ( dc_context_t context,
uint32_t  chat_id 
)

Get contact IDs belonging to a chat.

  • for normal chats, the function always returns exactly one contact, DC_CONTACT_ID_SELF is returned only for SELF-chats.
  • for group chats all members are returned, DC_CONTACT_ID_SELF is returned explicitly as it may happen that oneself gets removed from a still existing group
  • for the deaddrop, the list is empty
Parameters
contextThe context object as returned from dc_context_new().
chat_idChat ID to get the belonging contact IDs for.
Returns
An array of contact IDs belonging to the chat; must be freed using dc_array_unref() when done.
uint32_t dc_get_chat_id_by_contact_id ( dc_context_t context,
uint32_t  contact_id 
)

Check, if there is a normal chat with a given contact.

To get the chat messages, use dc_get_chat_msgs().

Parameters
contextThe context object as returned from dc_context_new().
contact_idThe contact ID to check.
Returns
If there is a normal chat with the given contact_id, this chat_id is returned. If there is no normal chat with the contact_id, the function returns 0.
dc_array_t * dc_get_chat_media ( dc_context_t context,
uint32_t  chat_id,
int  msg_type,
int  or_msg_type 
)

Returns all message IDs of the given types in a chat.

Typically used to show a gallery. The result must be dc_array_unref()'d

The list is already sorted and starts with the oldest message. Clients should not try to re-sort the list as this would be an expensive action and would result in inconsistencies between clients.

Parameters
contextThe context object as returned from dc_context_new().
chat_idThe chat ID to get all messages with media from.
msg_typeSpecify a message type to query here, one of the DC_MSG_* constats.
or_msg_typeAnother message type to return, one of the DC_MSG_* constats. The function will return both types then. 0 if you need only one.
Returns
An array with messages from the given chat ID that have the wanted message types.
dc_array_t * dc_get_chat_msgs ( dc_context_t context,
uint32_t  chat_id,
uint32_t  flags,
uint32_t  marker1before 
)

Get all message IDs belonging to a chat.

The list is already sorted and starts with the oldest message. Clients should not try to re-sort the list as this would be an expensive action and would result in inconsistencies between clients.

Optionally, some special markers added to the ID-array may help to implement virtual lists.

Parameters
contextThe context object as returned from dc_context_new().
chat_idThe chat ID of which the messages IDs should be queried.
flagsIf set to DC_GCM_ADD_DAY_MARKER, the marker DC_MSG_ID_DAYMARKER will be added before each day (regarding the local timezone). Set this to 0 if you do not want this behaviour.
marker1beforeAn optional message ID. If set, the id DC_MSG_ID_MARKER1 will be added just before the given ID in the returned array. Set this to 0 if you do not want this behaviour.
Returns
Array of message IDs, must be dc_array_unref()'d when no longer used.
dc_chatlist_t * dc_get_chatlist ( dc_context_t context,
int  listflags,
const char *  query_str,
uint32_t  query_id 
)

Get a list of chats.

The list can be filtered by query parameters.

The list is already sorted and starts with the most recent chat in use. The sorting takes care of invalid sending dates, drafts and chats without messages. Clients should not try to re-sort the list as this would be an expensive action and would result in inconsistencies between clients.

To get information about each entry, use eg. dc_chatlist_get_summary().

By default, the function adds some special entries to the list. These special entries can be identified by the ID returned by dc_chatlist_get_chat_id():

  • DC_CHAT_ID_DEADDROP (1) - this special chat is present if there are messages from addresses that have no relationship to the configured account. The last of these messages is represented by DC_CHAT_ID_DEADDROP and you can retrieve details about it with dc_chatlist_get_msg_id(). Typically, the UI asks the user "Do you want to chat with NAME?" and offers the options "Yes" (call dc_create_chat_by_msg_id()), "Never" (call dc_block_contact()) or "Not now". The UI can also offer a "Close" button that calls dc_marknoticed_contact() then.
  • DC_CHAT_ID_ARCHIVED_LINK (6) - this special chat is present if the user has archived any chat using dc_archive_chat(). The UI should show a link as "Show archived chats", if the user clicks this item, the UI should show a list of all archived chats that can be created by this function hen using the DC_GCL_ARCHIVED_ONLY flag.
  • DC_CHAT_ID_ALLDONE_HINT (7) - this special chat is present if DC_GCL_ADD_ALLDONE_HINT is added to listflags and if there are only archived chats.
Parameters
contextThe context object as returned by dc_context_new()
listflagsA combination of flags:
  • if the flag DC_GCL_ARCHIVED_ONLY is set, only archived chats are returned. if DC_GCL_ARCHIVED_ONLY is not set, only unarchived chats are returned and the pseudo-chat DC_CHAT_ID_ARCHIVED_LINK is added if there are any archived chats
  • if the flag DC_GCL_NO_SPECIALS is set, deaddrop and archive link are not added to the list (may be used eg. for selecting chats on forwarding, the flag is not needed when DC_GCL_ARCHIVED_ONLY is already set)
  • if the flag DC_GCL_ADD_ALLDONE_HINT is set, DC_CHAT_ID_ALLDONE_HINT is added as needed.
query_strAn optional query for filtering the list. Only chats matching this query are returned. Give NULL for no filtering.
query_idAn optional contact ID for filtering the list. Only chats including this contact ID are returned. Give 0 for no filtering.
Returns
A chatlist as an dc_chatlist_t object. On errors, NULL is returned. Must be freed using dc_chatlist_unref() when no longer used.

See also: dc_get_chat_msgs() to get the messages of a single chat.

char * dc_get_config ( dc_context_t context,
const char *  key 
)

Get a configuration option.

The configuration option is set by dc_set_config() or by the library itself.

Beside the options shown at dc_set_config(), this function can be used to query some global system values:

  • sys.version = get the version string eg. as 1.2.3 or as 1.2.3special4
  • sys.msgsize_max_recommended = maximal recommended attachment size in bytes. All possible overheads are already subtracted and this value can be used eg. for direct comparison with the size of a file the user wants to attach. If an attachment is larger than this value, an error (no warning as it should be shown to the user) is logged but the attachment is sent anyway.
  • sys.config_keys = get a space-separated list of all config-keys available. The config-keys are the keys that can be passed to the parameter key of this function.
Parameters
contextThe context object as created by dc_context_new(). For querying system values, this can be NULL.
keyThe key to query.
Returns
Returns current value of "key", if "key" is unset, the default value is returned. The returned value must be free()'d, NULL is never returned.
dc_contact_t * dc_get_contact ( dc_context_t context,
uint32_t  contact_id 
)

Get a single contact object.

For a list, see eg. dc_get_contacts().

For contact DC_CONTACT_ID_SELF (1), the function returns sth. like "Me" in the selected language and the email address defined by dc_set_config().

Parameters
contextThe context object as created by dc_context_new().
contact_idID of the contact to get the object for.
Returns
The contact object, must be freed using dc_contact_unref() when no longer used. NULL on errors.
char * dc_get_contact_encrinfo ( dc_context_t context,
uint32_t  contact_id 
)

Get encryption info for a contact.

Get a multi-line encryption info, containing your fingerprint and the fingerprint of the contact, used eg. to compare the fingerprints for a simple out-of-band verification.

Parameters
contextThe context object as created by dc_context_new().
contact_idID of the contact to get the encryption info for.
Returns
Multi-line text, must be free()'d after usage.
dc_array_t * dc_get_contacts ( dc_context_t context,
uint32_t  listflags,
const char *  query 
)

Returns known and unblocked contacts.

To get information about a single contact, see dc_get_contact().

Parameters
contextThe context object as created by dc_context_new().
listflagsA combination of flags:
  • if the flag DC_GCL_ADD_SELF is set, SELF is added to the list unless filtered by other parameters
  • if the flag DC_GCL_VERIFIED_ONLY is set, only verified contacts are returned. if DC_GCL_VERIFIED_ONLY is not set, verified and unverified contacts are returned.
queryA string to filter the list. Typically used to implement an incremental search. NULL for no filtering.
Returns
An array containing all contact IDs. Must be dc_array_unref()'d after usage.
dc_msg_t * dc_get_draft ( dc_context_t context,
uint32_t  chat_id 
)

Get draft for a chat, if any.

See dc_set_draft() for more details about drafts.

Parameters
contextThe context as created by dc_context_new().
chat_idThe chat ID to get the draft for.
Returns
Message object. Can be passed directly to dc_send_msg(). Must be freed using dc_msg_unref() after usage. If there is no draft, NULL is returned.
int dc_get_fresh_msg_cnt ( dc_context_t context,
uint32_t  chat_id 
)

Get the number of fresh messages in a chat.

Typically used to implement a badge with a number in the chatlist.

Parameters
contextThe context object as returned from dc_context_new().
chat_idThe ID of the chat to count the messages for.
Returns
Number of fresh messages in the given chat. 0 for errors or if there are no fresh messages.
dc_array_t * dc_get_fresh_msgs ( dc_context_t context)

Returns the message IDs of all fresh messages of any chat.

Typically used for implementing notification summaries. The list is already sorted and starts with the most recent fresh message.

Parameters
contextThe context object as returned from dc_context_new().
Returns
Array of message IDs, must be dc_array_unref()'d when no longer used. On errors, the list is empty. NULL is never returned.
char * dc_get_info ( dc_context_t context)

Get information about the context.

The information is returned by a multi-line string and contains information about the current configuration.

Parameters
contextThe context as created by dc_context_new().
Returns
String which must be free()'d after usage. Never returns NULL.
char * dc_get_mime_headers ( dc_context_t context,
uint32_t  msg_id 
)

Get the raw mime-headers of the given message.

Raw headers are saved for incoming messages only if dc_set_config(context, "save_mime_headers", "1") was called before.

Parameters
contextThe context object as created by dc_context_new().
msg_idThe message id, must be the id of an incoming message.
Returns
Raw headers as a multi-line string, must be free()'d after usage. Returns NULL if there are no headers saved for the given message, eg. because of save_mime_headers is not set or the message is not incoming.
dc_msg_t * dc_get_msg ( dc_context_t context,
uint32_t  msg_id 
)

Get a single message object of the type dc_msg_t.

For a list of messages in a chat, see dc_get_chat_msgs() For a list or chats, see dc_get_chatlist()

Parameters
contextThe context as created by dc_context_new().
msg_idThe message ID for which the message object should be created.
Returns
A dc_msg_t message object. On errors, NULL is returned. When done, the object must be freed using dc_msg_unref().
int dc_get_msg_cnt ( dc_context_t context,
uint32_t  chat_id 
)

Get the total number of messages in a chat.

Parameters
contextThe context object as returned from dc_context_new().
chat_idThe ID of the chat to count the messages for.
Returns
Number of total messages in the given chat. 0 for errors or empty chats.
char * dc_get_msg_info ( dc_context_t context,
uint32_t  msg_id 
)

Get an informational text for a single message.

The text is multiline and may contain eg. the raw text of the message.

The max. text returned is typically longer (about 100000 characters) than the max. text returned by dc_msg_get_text() (about 30000 characters).

Parameters
contextThe context object as created by dc_context_new().
msg_idThe message id for which information should be generated
Returns
Text string, must be free()'d after usage
uint32_t dc_get_next_media ( dc_context_t context,
uint32_t  curr_msg_id,
int  dir 
)

Get next/previous message of the same type.

Typically used to implement the "next" and "previous" buttons on a media player playing eg. voice messages.

Parameters
contextThe context object as returned from dc_context_new().
curr_msg_idThis is the current (image) message displayed.
dir1=get the next (image) message, -1=get the previous one.
Returns
Returns the message ID that should be played next. The returned message is in the same chat as the given one and has the same type. Typically, this result is passed again to dc_get_next_media() later on the next swipe. If there is not next/previous message, the function returns 0.
char * dc_get_securejoin_qr ( dc_context_t context,
uint32_t  group_chat_id 
)

Get QR code text that will offer an secure-join verification.

The QR code is compatible to the OPENPGP4FPR format so that a basic fingerprint comparison also works eg. with K-9 or OpenKeychain.

The scanning Delta Chat device will pass the scanned content to dc_check_qr() then; if this function returns DC_QR_ASK_VERIFYCONTACT or DC_QR_ASK_VERIFYGROUP an out-of-band-verification can be joined using dc_join_securejoin()

Parameters
contextThe context object.
group_chat_idIf set to the ID of a chat, the "Joining a verified group" protocol is offered in the QR code. If set to 0, the "Setup Verified Contact" protocol is offered in the QR code.
Returns
Text that should go to the QR code, on problems, an empty QR code is returned. The returned string must be free()'d after usage.
void * dc_get_userdata ( dc_context_t context)

Get user data associated with a context object.

Parameters
contextThe context object as created by dc_context_new().
Returns
User data, this is the second parameter given to dc_context_new().
void dc_imex ( dc_context_t context,
int  what,
const char *  param1,
const char *  param2 
)

Import/export things.

For this purpose, the function creates a job that is executed in the IMAP-thread then; this requires to call dc_perform_imap_jobs() regularly.

What to do is defined by the what parameter which may be one of the following:

  • DC_IMEX_EXPORT_BACKUP (11) - Export a backup to the directory given as param1. The backup contains all contacts, chats, images and other data and device independent settings. The backup does not contain device dependent settings as ringtones or LED notification settings. The name of the backup is typically delta-chat.<day>.bak, if more than one backup is create on a day, the format is delta-chat.<day>-<number>.bak
  • DC_IMEX_IMPORT_BACKUP (12) - param1 is the file (not: directory) to import. The file is normally created by DC_IMEX_EXPORT_BACKUP and detected by dc_imex_has_backup(). Importing a backup is only possible as long as the context is not configured or used in another way.
  • DC_IMEX_EXPORT_SELF_KEYS (1) - Export all private keys and all public keys of the user to the directory given as param1. The default key is written to the files public-key-default.asc and private-key-default.asc, if there are more keys, they are written to files as public-key-<id>.asc and private-key-<id>.asc
  • DC_IMEX_IMPORT_SELF_KEYS (2) - Import private keys found in the directory given as param1. The last imported key is made the default keys unless its name contains the string legacy. Public keys are not imported.

While dc_imex() returns immediately, the started job may take a while, you can stop it using dc_stop_ongoing_process(). During execution of the job, some events are sent out:

  • A number of DC_EVENT_IMEX_PROGRESS events are sent and may be used to create a progress bar or stuff like that. Moreover, you'll be informed when the imex-job is done.
  • For each file written on export, the function sends DC_EVENT_IMEX_FILE_WRITTEN

Only one import-/export-progress can run at the same time. To cancel an import-/export-progress, use dc_stop_ongoing_process().

Parameters
contextThe context as created by dc_context_new().
whatOne of the DC_IMEX_* constants.
param1Meaning depends on the DC_IMEX_* constants. If this parameter is a directory, it should not end with a slash (otherwise you'll get double slashes when receiving DC_EVENT_IMEX_FILE_WRITTEN). Set to NULL if not used.
param2Meaning depends on the DC_IMEX_* constants. Set to NULL if not used.
Returns
None.
char * dc_imex_has_backup ( dc_context_t context,
const char *  dir_name 
)

Check if there is a backup file.

May only be used on fresh installations (eg. dc_is_configured() returns 0).

Example:

char dir[] = "/dir/to/search/backups/in";
void ask_user_for_credentials()
{
// - ask the user for email and password
// - save them using dc_set_config()
}
int ask_user_whether_to_import()
{
// - inform the user that we've found a backup
// - ask if he want to import it
// - return 1 to import, 0 to skip
return 1;
}
if (!dc_is_configured(context))
{
char* file = NULL;
if ((file=dc_imex_has_backup(context, dir))!=NULL && ask_user_whether_to_import())
{
dc_imex(context, DC_IMEX_IMPORT_BACKUP, file, NULL);
// connect
}
else
{
do {
ask_user_for_credentials();
}
while (!configure_succeeded())
}
free(file);
}
Parameters
contextThe context as created by dc_context_new().
dir_nameDirectory to search backups in.
Returns
String with the backup file, typically given to dc_imex(), returned strings must be free()'d. The function returns NULL if no backup was found.
char * dc_initiate_key_transfer ( dc_context_t context)

Initiate Autocrypt Setup Transfer.

Before starting the setup transfer with this function, the user should be asked:

"An 'Autocrypt Setup Message' securely shares your end-to-end setup with other Autocrypt-compliant apps.
The setup will be encrypted by a setup code which is displayed here and must be typed on the other device.

After that, this function should be called to send the Autocrypt Setup Message. The function creates the setup message and waits until it is really sent. As this may take a while, it is recommended to start the function in a separate thread; to interrupt it, you can use dc_stop_ongoing_process().

After everything succeeded, the required setup code is returned in the following format:

1234-1234-1234-1234-1234-1234-1234-1234-1234

The setup code should be shown to the user then:

"Your key has been sent to yourself. Switch to the other device and
open the setup message. You should be prompted for a setup code. Type
the following digits into the prompt:
1234 - 1234 - 1234 -
1234 - 1234 - 1234 -
1234 - 1234 - 1234
Once you're done, your other device will be ready to use Autocrypt."

On the other device you will call dc_continue_key_transfer() then for setup messages identified by dc_msg_is_setupmessage().

For more details about the Autocrypt setup process, please refer to https://autocrypt.org/en/latest/level1.html#autocrypt-setup-message

Parameters
contextThe context object.
Returns
The setup code. Must be free()'d after usage. On errors, eg. if the message could not be sent, NULL is returned.
void dc_interrupt_imap_idle ( dc_context_t context)

Interrupt waiting for imap-jobs.

If dc_perform_imap_jobs(), dc_perform_imap_fetch() and dc_perform_imap_idle() are called in a loop, calling this function causes imap-jobs to be executed and messages to be fetched.

dc_interrupt_imap_idle() does not interrupt dc_perform_imap_jobs() or dc_perform_imap_fetch(). If the imap-thread is inside one of these functions when dc_interrupt_imap_idle() is called, however, the next call of the imap-thread to dc_perform_imap_idle() is interrupted immediately.

Internally, this function is called whenever a imap-jobs should be processed (delete message, markseen etc.), for the UI view it may make sense to call the function eg. on network changes to fetch messages immediately.

Example:

void* imap_thread_func(void* context)
{
    while (true) {
        dc_perform_imap_jobs(context);
        dc_perform_imap_fetch(context);
        dc_perform_imap_idle(context);
    }
}

// start imap-thread that runs forever
pthread_t imap_thread;
pthread_create(&imap_thread, NULL, imap_thread_func, context);

... program runs ...

// network becomes available again - the interrupt causes
// dc_perform_imap_idle() in the thread to return so that jobs are executed
// and messages are fetched.
dc_interrupt_imap_idle(context);
Parameters
contextThe context as created by dc_context_new().
Returns
None.
void dc_interrupt_smtp_idle ( dc_context_t context)

Interrupt waiting for smtp-jobs.

If dc_perform_smtp_jobs() and dc_perform_smtp_idle() are called in a loop, calling this function causes jobs to be executed.

dc_interrupt_smtp_idle() does not interrupt dc_perform_smtp_jobs(). If the smtp-thread is inside this function when dc_interrupt_smtp_idle() is called, however, the next call of the smtp-thread to dc_perform_smtp_idle() is interrupted immediately.

Internally, this function is called whenever a message is to be send, for the UI view it may make sense to call the function eg. on network changes.

Example:

void* smtp_thread_func(void* context)
{
    while (true) {
        dc_perform_smtp_jobs(context);
        dc_perform_smtp_idle(context);
    }
}

// start smtp-thread that runs forever
pthread_t smtp_thread;
pthread_create(&smtp_thread, NULL, smtp_thread_func, context);

... program runs ...

// network becomes available again - the interrupt causes
// dc_perform_smtp_idle() in the thread to return so that jobs are executed
dc_interrupt_smtp_idle(context);
Parameters
contextThe context as created by dc_context_new().
Returns
None.
int dc_is_configured ( const dc_context_t context)

Check if the context is already configured.

Typically, for unconfigured accounts, the user is prompted to enter some settings and dc_configure() is called in a thread then.

Parameters
contextThe context object as created by dc_context_new().
Returns
1=context is configured and can be used; 0=context is not configured and a configuration by dc_configure() is required.
int dc_is_contact_in_chat ( dc_context_t context,
uint32_t  chat_id,
uint32_t  contact_id 
)

Check if a given contact ID is a member of a group chat.

Parameters
contextThe context as created by dc_context_new().
chat_idThe chat ID to check.
contact_idThe contact ID to check. To check if yourself is member of the chat, pass DC_CONTACT_ID_SELF (1) here.
Returns
1=contact ID is member of chat ID, 0=contact is not in chat
int dc_is_open ( const dc_context_t context)

Check if the context database is open.

Parameters
contextThe context object as created by dc_context_new().
Returns
0=context is not open, 1=context is open.
uint32_t dc_join_securejoin ( dc_context_t context,
const char *  qr 
)

Join an out-of-band-verification initiated on another device with dc_get_securejoin_qr().

This function is typically called when dc_check_qr() returns lot.state=DC_QR_ASK_VERIFYCONTACT or lot.state=DC_QR_ASK_VERIFYGROUP.

This function takes some time and sends and receives several messages. You should call it in a separate thread; if you want to abort it, you should call dc_stop_ongoing_process().

Parameters
contextThe context object
qrThe text of the scanned QR code. Typically, the same string as given to dc_check_qr().
Returns
Chat-id of the joined chat, the UI may redirect to the this chat. If the out-of-band verification failed or was aborted, 0 is returned.
uint32_t dc_lookup_contact_id_by_addr ( dc_context_t context,
const char *  addr 
)

Check if an e-mail address belongs to a known and unblocked contact.

Known and unblocked contacts will be returned by dc_get_contacts().

To validate an e-mail address independently of the contact database use dc_may_be_valid_addr().

Parameters
contextThe context object as created by dc_context_new().
addrThe e-mail-address to check.
Returns
1=address is a contact in use, 0=address is not a contact in use.
void dc_marknoticed_all_chats ( dc_context_t context)

Same as dc_marknoticed_chat() but for all chats.

Parameters
contextThe context object as returned from dc_context_new().
Returns
None.
void dc_marknoticed_chat ( dc_context_t context,
uint32_t  chat_id 
)

Mark all messages in a chat as noticed.

Noticed messages are no longer fresh and do not count as being unseen but are still waiting for being marked as "seen" using dc_markseen_msgs() (IMAP/MDNs is not done for noticed messages).

Calling this function usually results in the event DC_EVENT_MSGS_CHANGED. See also dc_marknoticed_all_chats(), dc_marknoticed_contact() and dc_markseen_msgs().

Parameters
contextThe context object as returned from dc_context_new().
chat_idThe chat ID of which all messages should be marked as being noticed.
Returns
None.
void dc_marknoticed_contact ( dc_context_t context,
uint32_t  contact_id 
)

Mark all messages sent by the given contact as noticed.

See also dc_marknoticed_chat() and dc_markseen_msgs()

Calling this function usually results in the event DC_EVENT_MSGS_CHANGED.

Parameters
contextThe context object as created by dc_context_new()
contact_idThe contact ID of which all messages should be marked as noticed.
Returns
None.
void dc_markseen_msgs ( dc_context_t context,
const uint32_t *  msg_ids,
int  msg_cnt 
)

Mark a message as seen, updates the IMAP state and sends MDNs.

If the message is not in a real chat (eg. a contact request), the message is only marked as NOTICED and no IMAP/MDNs is done. See also dc_marknoticed_chat() and dc_marknoticed_contact()

Parameters
contextThe context object.
msg_idsAn array of uint32_t containing all the messages IDs that should be marked as seen.
msg_cntThe number of message IDs in msg_ids.
Returns
None.
int dc_may_be_valid_addr ( const char *  addr)

Rough check if a string may be a valid e-mail address.

The function checks if the string contains a minimal amount of characters before and after the @ and . characters.

To check if a given address is a contact in the contact database use dc_lookup_contact_id_by_addr().

Parameters
addrThe e-mail-address to check.
Returns
1=address may be a valid e-mail address, 0=address won't be a valid e-mail address
void dc_maybe_network ( dc_context_t context)

This function can be called whenever there is a hint that the network is available again.

The library will try to send pending messages out.

Parameters
contextThe context as created by dc_context_new().
Returns
None.
int dc_open ( dc_context_t context,
const char *  dbfile,
const char *  blobdir 
)

Open context database.

If the given file does not exist, it is created and can be set up using dc_set_config() afterwards.

Parameters
contextThe context object as created by dc_context_new().
dbfileThe file to use to store the database, something like ~/file won't work on all systems, if in doubt, use absolute paths.
blobdirA directory to store the blobs in; a trailing slash is not needed. If you pass NULL or the empty string, deltachat-core creates a directory beside dbfile with the same name and the suffix -blobs.
Returns
1 on success, 0 on failure eg. if the file is not writable or if there is already a database opened for the context.
void dc_openssl_init_not_required ( void  )

Skip OpenSSL initialisation.

By default, the OpenSSL library is initialized thread-safe when calling dc_context_new() the first time. When the last context-object is deleted using dc_context_unref(), the OpenSSL library will be released as well.

If your app needs OpenSSL on its own outside these calls, you have to initialize the OpenSSL-library yourself and skip the initialisation in deltachat-core by calling dc_openssl_init_not_required() before calling dc_context_new() the first time.

Multiple calls to dc_openssl_init_not_required() are not needed, however, they do not harm.

Returns
None.
void dc_perform_imap_fetch ( dc_context_t context)

Fetch new messages, if any.

This function and dc_perform_imap_jobs() and dc_perform_imap_idle() must be called from the same thread, typically in a loop.

See dc_interrupt_imap_idle() for an example.

Parameters
contextThe context as created by dc_context_new().
Returns
None.
void dc_perform_imap_idle ( dc_context_t context)

Wait for messages or jobs.

This function and dc_perform_imap_jobs() and dc_perform_imap_fetch() must be called from the same thread, typically in a loop.

You should call this function directly after calling dc_perform_imap_fetch().

See dc_interrupt_imap_idle() for an example.

Parameters
contextThe context as created by dc_context_new().
Returns
None.
void dc_perform_imap_jobs ( dc_context_t context)

Execute pending imap-jobs.

This function and dc_perform_imap_fetch() and dc_perform_imap_idle() must be called from the same thread, typically in a loop.

See dc_interrupt_imap_idle() for an example.

Parameters
contextThe context as created by dc_context_new().
Returns
None.
void dc_perform_smtp_idle ( dc_context_t context)

Wait for smtp-jobs.

This function and dc_perform_smtp_jobs() must be called from the same thread, typically in a loop.

See dc_interrupt_smtp_idle() for an example.

Parameters
contextThe context as created by dc_context_new().
Returns
None.
void dc_perform_smtp_jobs ( dc_context_t context)

Execute pending smtp-jobs.

This function and dc_perform_smtp_idle() must be called from the same thread, typically in a loop.

See dc_interrupt_smtp_idle() for an example.

Parameters
contextThe context as created by dc_context_new().
Returns
None.
int dc_remove_contact_from_chat ( dc_context_t context,
uint32_t  chat_id,
uint32_t  contact_id 
)

Remove a member from a group.

If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.

Sends out DC_EVENT_CHAT_MODIFIED and DC_EVENT_MSGS_CHANGED if a status message was sent.

Parameters
contextThe context as created by dc_context_new().
chat_idThe chat ID to remove the contact from. Must be a group chat.
contact_idThe contact ID to remove from the chat.
Returns
1=member removed from group, 0=error
dc_array_t * dc_search_msgs ( dc_context_t context,
uint32_t  chat_id,
const char *  query 
)

Search messages containing the given query string.

Searching can be done globally (chat_id=0) or in a specified chat only (chat_id set).

Global chat results are typically displayed using dc_msg_get_summary(), chat search results may just hilite the corresponding messages and present a prev/next button.

Parameters
contextThe context object as returned from dc_context_new().
chat_idID of the chat to search messages in. Set this to 0 for a global search.
queryThe query to search for.
Returns
An array of message IDs. Must be freed using dc_array_unref() when no longer needed. If nothing can be found, the function returns NULL.
uint32_t dc_send_msg ( dc_context_t context,
uint32_t  chat_id,
dc_msg_t msg 
)

Send a message defined by a dc_msg_t object to a chat.

Sends the event DC_EVENT_MSGS_CHANGED on succcess. However, this does not imply, the message really reached the recipient - sending may be delayed eg. due to network problems. However, from your view, you're done with the message. Sooner or later it will find its way.

Example:

dc_msg_t* msg = dc_msg_new(context, DC_MSG_IMAGE);
dc_msg_set_file(msg, "/file/to/send.jpg", NULL);
dc_send_msg(context, msg);

You can even call this function if the file to be sent is still in creation. For this purpose, create a file with the additional extension .increation beside the file to sent. Once you're done with creating the file, delete the increation-file and the message will really be sent. This is useful as the user can already send the next messages while eg. the recoding of a video is not yet finished. Or the user can even forward the message with the file being still in creation to other groups.

Files being sent with the increation-method must be placed in the blob directory, see dc_get_blobdir(). If the increation-method is not used - which is probably the normal case - the file is copied to the blob directory if it is not yet there.

Parameters
contextThe context object as returned from dc_context_new().
chat_idChat ID to send the message to.
msgMessage object to send to the chat defined by the chat ID. On succcess, msg_id of the object is set up, The function does not take ownership of the object, so you have to free it using dc_msg_unref() as usual.
Returns
The ID of the message that is about being sent.
uint32_t dc_send_text_msg ( dc_context_t context,
uint32_t  chat_id,
const char *  text_to_send 
)

Send a simple text message a given chat.

Sends the event DC_EVENT_MSGS_CHANGED on succcess. However, this does not imply, the message really reached the recipient - sending may be delayed eg. due to network problems. However, from your view, you're done with the message. Sooner or later it will find its way.

See also dc_send_msg().

Parameters
contextThe context object as returned from dc_context_new().
chat_idChat ID to send the text message to.
text_to_sendText to send to the chat defined by the chat ID. Passing an empty text here causes an empty text to be sent, it's up to the caller to handle this if undesired. Passing NULL as the text causes the function to return 0.
Returns
The ID of the message that is about being sent.
int dc_set_chat_name ( dc_context_t context,
uint32_t  chat_id,
const char *  new_name 
)

Set group name.

If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.

Sends out DC_EVENT_CHAT_MODIFIED and DC_EVENT_MSGS_CHANGED if a status message was sent.

Parameters
chat_idThe chat ID to set the name for. Must be a group chat.
new_nameNew name of the group.
contextThe context as created by dc_context_new().
Returns
1=success, 0=error
int dc_set_chat_profile_image ( dc_context_t context,
uint32_t  chat_id,
const char *  new_image 
)

Set group profile image.

If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.

Sends out DC_EVENT_CHAT_MODIFIED and DC_EVENT_MSGS_CHANGED if a status message was sent.

To find out the profile image of a chat, use dc_chat_get_profile_image()

Parameters
contextThe context as created by dc_context_new().
chat_idThe chat ID to set the image for.
new_imageFull path of the image to use as the group image. If you pass NULL here, the group image is deleted (for promoted groups, all members are informed about this change anyway).
Returns
1=success, 0=error
int dc_set_config ( dc_context_t context,
const char *  key,
const char *  value 
)

Configure the context.

The configuration is handled by key=value pairs as:

  • addr = address to display (always needed)
  • mail_server = IMAP-server, guessed if left out
  • mail_user = IMAP-username, guessed if left out
  • mail_pw = IMAP-password (always needed)
  • mail_port = IMAP-port, guessed if left out
  • send_server = SMTP-server, guessed if left out
  • send_user = SMTP-user, guessed if left out
  • send_pw = SMTP-password, guessed if left out
  • send_port = SMTP-port, guessed if left out
  • server_flags = IMAP-/SMTP-flags as a combination of DC_LP flags, guessed if left out
  • imap_folder = IMAP-folder to use, defaults to INBOX
  • displayname = Own name to use when sending messages. MUAs are allowed to spread this way eg. using CC, defaults to empty
  • selfstatus = Own status to display eg. in email footers, defaults to a standard text
  • selfavatar = File containing avatar. Will be copied to blob directory. NULL to remove the avatar. It is planned for future versions to send this image together with the next messages.
  • e2ee_enabled = 0=no end-to-end-encryption, 1=prefer end-to-end-encryption (default)
  • mdns_enabled = 0=do not send or request read receipts, 1=send and request read receipts (default)
  • save_mime_headers = 1=save mime headers and make dc_get_mime_headers() work for subsequent calls, 0=do not save mime headers (default)

If you want to retrieve a value, use dc_get_config().

Parameters
contextThe context object
keyThe option to change, see above.
valueThe value to save for "key"
Returns
0=failure, 1=success
void dc_set_draft ( dc_context_t context,
uint32_t  chat_id,
dc_msg_t msg 
)

Save a draft for a chat in the database.

The UI should call this function if the user has prepared a message and exits the compose window without clicking the "send" button before. When the user later opens the same chat again, the UI can load the draft using dc_get_draft() allowing the user to continue editing and sending.

Drafts are considered when sorting messages and are also returned eg. by dc_chatlist_get_summary().

Each chat can have its own draft but only one draft per chat is possible.

If the draft is modified, an DC_EVENT_MSGS_CHANGED will be sent.

Parameters
contextThe context as created by dc_context_new().
chat_idThe chat ID to save the draft for.
msgThe message to save as a draft. Existing draft will be overwritten. NULL deletes the existing draft, if any, without sending it. Currently, also non-text-messages will delete the existing drafts.
Returns
None.
void dc_star_msgs ( dc_context_t context,
const uint32_t *  msg_ids,
int  msg_cnt,
int  star 
)

Star/unstar messages by setting the last parameter to 0 (unstar) or 1 (star).

Starred messages are collected in a virtual chat that can be shown using dc_get_chat_msgs() using the chat_id DC_CHAT_ID_STARRED.

Parameters
contextThe context object as created by dc_context_new()
msg_idsAn array of uint32_t message IDs defining the messages to star or unstar
msg_cntThe number of IDs in msg_ids
star0=unstar the messages in msg_ids, 1=star them
Returns
None.
void dc_stop_ongoing_process ( dc_context_t context)

Signal an ongoing process to stop.

After that, dc_stop_ongoing_process() returns without waiting for the ongoing process to return.

The ongoing process will return ASAP then, however, it may still take a moment. If in doubt, the caller may also decide to kill the thread after a few seconds; eg. the process may hang in a function not under the control of the core (eg. DC_EVENT_HTTP_GET). Another reason for dc_stop_ongoing_process() not to wait is that otherwise it would be GUI-blocking and should be started in another thread then; this would make things even more complicated.

Typical ongoing processes are started by dc_configure(), dc_initiate_key_transfer() or dc_imex(). As there is always at most only one onging process at the same time, there is no need to define which process to exit.

Parameters
contextThe context object.
Returns
None.

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