#include <deltachat.h>

Public Member Functions
int	dc_add_address_book (dc_context_t context, const char addr_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...

uint32_t	dc_add_device_msg (dc_context_t context, const char label, dc_msg_t *msg)
	Add a message to the device-chat. More...

void	dc_block_contact (dc_context_t *context, uint32_t contact_id, int block)
	Block or unblock a contact. More...

dc_lot_t *	dc_chatlist_get_summary2 (dc_context_t *context, uint32_t chat_id, uint32_t msg_id)
	Create a chatlist summary item when the chatlist object is already unref()'d. More...

dc_lot_t *	dc_check_qr (dc_context_t context, const char qr)
	Check a scanned QR code. More...

void	dc_configure (dc_context_t *context)
	Configure a context. More...

dc_context_t *	dc_context_new (const char os_name, const char dbfile, const char *blobdir)
	Create a new context object. More...

void	dc_context_unref (dc_context_t *context)
	Free a context object. 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...

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 name)
	Create a new group chat. More...

void	dc_delete_all_locations (dc_context_t *context)
	Delete all locations on the current device. 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...

int	dc_estimate_deletion_cnt (dc_context_t *context, int from_server, int64_t seconds)
	Estimate the number of messages that will be deleted by the dc_set_config()-options `delete_device_after` or `delete_server_after`. 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_t *	dc_get_blocked_contacts (dc_context_t *context)
	Get blocked contacts. More...

dc_chat_t *	dc_get_chat (dc_context_t *context, uint32_t chat_id)
	Get chat object by a chat ID. More...

dc_array_t *	dc_get_chat_contacts (dc_context_t *context, uint32_t chat_id)
	Get contact IDs belonging to a chat. More...

uint32_t	dc_get_chat_ephemeral_timer (dc_context_t *context, uint32_t chat_id)
	Get the chat's ephemeral message timer. 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_t *	dc_get_chat_media (dc_context_t *context, uint32_t chat_id, int msg_type, int msg_type2, int msg_type3)
	Returns all message IDs of the given types in a chat. More...

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. More...

dc_chatlist_t *	dc_get_chatlist (dc_context_t context, int flags, 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_t *	dc_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_t *	dc_get_contacts (dc_context_t context, uint32_t flags, const char query)
	Returns known and unblocked contacts. More...

dc_msg_t *	dc_get_draft (dc_context_t *context, uint32_t chat_id)
	Get draft for a chat, if any. More...

dc_event_emitter_t *	dc_get_event_emitter (dc_context_t *context)
	Create the event emitter that is used to receive events. 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_t *	dc_get_fresh_msgs (dc_context_t *context)
	Returns the message IDs of all fresh messages of any chat. More...

uint32_t	dc_get_id (dc_context_t *context)
	Get the ID of a context object. More...

char *	dc_get_info (dc_context_t *context)
	Get information about the context. More...

dc_array_t *	dc_get_locations (dc_context_t *context, uint32_t chat_id, uint32_t contact_id, int64_t timestamp_begin, int64_t timestamp_end)
	Get shared locations from the database. 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_t *	dc_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 msg_id, int dir, int msg_type, int msg_type2, int msg_type3)
	Search next/previous message based on a given message and a list of types. More...

char *	dc_get_oauth2_url (dc_context_t context, const char addr, const char *redirect_uri)
	Get url that can be used to initiate an OAuth2 authorisation. More...

char *	dc_get_securejoin_qr (dc_context_t *context, uint32_t chat_id)
	Get QR code text that will offer an Setup-Contact or Verified-Group invitation. 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)
	Check if there is a backup file. More...

char *	dc_initiate_key_transfer (dc_context_t *context)
	Initiate Autocrypt Setup Transfer. 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_io_running (const dc_context_t *context)
	Check if IO (SMTP/IMAP/Jobs) has been started. More...

int	dc_is_sending_locations_to_chat (dc_context_t *context, uint32_t chat_id)
	Check if location streaming is enabled. More...

uint32_t	dc_join_securejoin (dc_context_t context, const char qr)
	Continue a Setup-Contact or Verified-Group-Invite protocol started on another device with dc_get_securejoin_qr(). 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 should be called when there is a hint that the network is available again, eg. More...

int	dc_preconfigure_keypair (dc_context_t context, const char addr, const char public_data, const char secret_data)
	Save a keypair as the default keys for the user. More...

uint32_t	dc_prepare_msg (dc_context_t context, uint32_t chat_id, dc_msg_t msg)
	Prepare a message for sending. 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_t *	dc_search_msgs (dc_context_t context, uint32_t chat_id, const char query)
	Search messages containing the given query string. More...

void	dc_send_locations_to_chat (dc_context_t *context, uint32_t chat_id, int seconds)
	Enable or disable location streaming for a chat. 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_msg_sync (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, synchronously. 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...

uint32_t	dc_send_videochat_invitation (dc_context_t *context, uint32_t chat_id)
	Send invitation to a videochat. More...

int	dc_set_chat_ephemeral_timer (dc_context_t *context, uint32_t chat_id, uint32_t timer)
	Set the chat's ephemeral message timer. More...

int	dc_set_chat_mute_duration (dc_context_t *context, uint32_t chat_id, int64_t duration)
	Set mute duration of a chat. More...

int	dc_set_chat_name (dc_context_t context, uint32_t chat_id, const char name)
	Set group name. More...

int	dc_set_chat_profile_image (dc_context_t context, uint32_t chat_id, const char image)
	Set group profile image. More...

void	dc_set_chat_visibility (dc_context_t *context, uint32_t chat_id, int visibility)
	Set chat visibility to pinned, archived or normal. More...

int	dc_set_config (dc_context_t context, const char key, const char *value)
	Configure the context. More...

int	dc_set_config_from_qr (dc_context_t context, const char qr)
	Set configuration values from a QR code. 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...

int	dc_set_location (dc_context_t *context, double latitude, double longitude, double accuracy)
	Set current location. More...

int	dc_set_stock_translation (dc_context_t context, uint32_t stock_id, const char stock_msg)
	Set stock string translation. 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_start_io (dc_context_t *context)
	Start job and IMAP/SMTP tasks. More...

void	dc_stop_io (dc_context_t *context)
	Stop job and IMAP/SMTP tasks and return when they are finished. More...

void	dc_stop_ongoing_process (dc_context_t *context)
	Signal an ongoing process to stop. More...

void	dc_str_unref (char *str)
	Release a string returned by another deltachat-core function. More...

void	dc_update_device_chats (dc_context_t *context)
	Init device-messages and saved-messages chat. More...

int	dc_was_device_msg_ever_added (dc_context_t context, const char label)
	Check if a device-message with a given label was ever added. 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 Function Documentation

◆ dc_add_address_book()

int dc_add_address_book	(	dc_context_t *	context,
		const char *	addr_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

context	the context object.
addr_book	A 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.

◆ dc_add_contact_to_chat()

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

context	The context object.
chat_id	The chat ID to add the contact to. Must be a group chat.
contact_id	The contact ID to add to the chat.

Returns: 1=member added to group, 0=error

◆ dc_add_device_msg()

uint32_t dc_add_device_msg	(	dc_context_t *	context,
		const char *	label,
		dc_msg_t *	msg
	)

Add a message to the device-chat.

Device-messages usually contain update information and some hints that are added during the program runs, multi-device etc. The device-message may be defined by a label; if a message with the same label was added or skipped before, the message is not added again, even if the message was deleted in between. If needed, the device-chat is created before.

Sends the event DC_EVENT_MSGS_CHANGED on success. To check, if a given chat is a device-chat, see dc_chat_is_device_talk()

Parameters

context	The context object.
label	A unique name for the message to add. The label is typically not displayed to the user and must be created from the characters `A-Z`, `a-z`, `0-9`, `_` or `-`. If you pass NULL here, the message is added unconditionally.
msg	Message to be added to the device-chat. The message appears to the user as an incoming message. If you pass NULL here, only the given label will be added and block adding messages with that label in the future.

Returns: The ID of the just added message, if the message was already added or no message to add is given, 0 is returned.

Example:

dc_msg_t* welcome_msg = dc_msg_new(DC_MSG_TEXT);
dc_msg_set_text(welcome_msg, "great that you give this app a try!");
 
dc_msg_t* changelog_msg = dc_msg_new(DC_MSG_TEXT);
dc_msg_set_text(changelog_msg, "we have added 3 new emojis :)");
 
if (dc_add_device_msg(context, "welcome", welcome_msg)) {
    // do not add the changelog on a new installations -
    // not now and not when this code is executed again
    dc_add_device_msg(context, "update-123", NULL);
} else {
    // welcome message was not added now, this is an oder installation,
    // add a changelog
    dc_add_device_msg(context, "update-123", changelog_msg);
}
 
dc_msg_unref(changelog_msg);
dc_msg_unref(welome_msg);

◆ dc_block_contact()

void dc_block_contact	(	dc_context_t *	context,
		uint32_t	contact_id,
		int	block
	)

Block or unblock a contact.

May result in a DC_EVENT_CONTACTS_CHANGED event.

Parameters

context	The context object.
contact_id	The ID of the contact to block or unblock.
block	1=block contact, 0=unblock contact

Returns: None.

◆ dc_chatlist_get_summary2()

dc_lot_t * dc_chatlist_get_summary2	(	dc_context_t *	context,
		uint32_t	chat_id,
		uint32_t	msg_id
	)

Create a chatlist summary item when the chatlist object is already unref()'d.

This function is similar to dc_chatlist_get_summary(), however, takes the chat-id and message-id as returned by dc_chatlist_get_chat_id() and dc_chatlist_get_msg_id() as arguments. The chatlist object itself is not needed directly.

This maybe useful if you convert the complete object into a different represenation as done eg. in the node-bindings. If you have access to the chatlist object in some way, using this function is not recommended, use dc_chatlist_get_summary() in this case instead.

Parameters

context	The context object.
chat_id	Chat to get a summary for.
msg_id	Messasge to get a summary for.

Returns: The summary as an dc_lot_t object, see dc_chatlist_get_summary() for details. Must be freed using dc_lot_unref(). NULL is never returned.

◆ dc_check_qr()

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_ACCOUNT allows creation of an account, dc_lot_t::text1=domain
DC_QR_WEBRTC_INSTANCE - a shared webrtc-instance that will be set if dc_set_config_from_qr() is called with the qr-code, dc_lot_t::text1=domain could be used to ask the user
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

context	The context object.
qr	The 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.

◆ dc_configure()

void dc_configure ( dc_context_t * context )

Configure a context.

While configuration IO must not be started, if needed stop IO using dc_stop_io() first. 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.

If DC_EVENT_CONFIGURE_PROGRESS reports failure, the core continues to use the last working configuration and parameters as addr, mail_pw etc. are set to that.

Parameters

context The context object.

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_new()

dc_context_t * dc_context_new	(	const char *	os_name,
		const char *	dbfile,
		const char *	blobdir
	)

Create a new context object.

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

Parameters

os_name	is only for decorative use and is shown eg. in the `X-Mailer:` header in the form "Delta Chat Core <version>/<os_name>". You can give the name of the app, the operating system, the used environment and/or the version here. It is okay to give NULL, in this case `X-Mailer:` header is set to "Delta Chat Core <version>".
dbfile	The file to use to store the database, something like `~/file` won't work, use absolute paths.
blobdir	A 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: 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.

If you want to use multiple context objects at the same time, this can be managed using dc_accounts_t.

◆ dc_context_unref()

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().

You have to call this function also for accounts returned by dc_accounts_get_account() or dc_accounts_get_selected_account(), however, in this case, the context is not shut down but just a reference counter is decreased

Parameters

context The context object as created by dc_context_new(), dc_accounts_get_account() or dc_accounts_get_selected_account(). If NULL is given, nothing is done.

Returns: None.

◆ dc_continue_key_transfer()

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

context	The context object.
msg_id	ID of the setup message to decrypt.
setup_code	Setup 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.

◆ dc_create_chat_by_contact_id()

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

context	The context object as returned from dc_context_new().
contact_id	The 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.

◆ dc_create_chat_by_msg_id()

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

context	The context object as returned from dc_context_new().
msg_id	The message ID to create the chat for.

Returns: The created or reused chat ID on success. 0 on errors.

◆ dc_create_contact()

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

context	The context object.
name	Name of the contact to add. If you do not know the name belonging to the address, you can give NULL here.
addr	E-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.

◆ dc_create_group_chat()

uint32_t dc_create_group_chat	(	dc_context_t *	context,
		int	verified,
		const char *	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

context	The context object.
verified	If 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.
name	The 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.

◆ dc_delete_all_locations()

void dc_delete_all_locations ( dc_context_t * context )

Delete all locations on the current device.

Locations already sent cannot be deleted.

Typically results in the event DC_EVENT_LOCATION_CHANGED with contact_id set to 0.

Parameters

context The context object.

Returns: None.

◆ dc_delete_chat()

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

context	The context object as returned from dc_context_new().
chat_id	The ID of the chat to delete.

Returns: None.

◆ dc_delete_contact()

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

context	The context object.
contact_id	ID of the contact to delete.

Returns: 1=success, 0=error

◆ dc_delete_msgs()

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

context	The context object
msg_ids	an array of uint32_t containing all message IDs that should be deleted
msg_cnt	The number of messages IDs in the msg_ids array

Returns: None.

◆ dc_estimate_deletion_cnt()

int dc_estimate_deletion_cnt	(	dc_context_t *	context,
		int	from_server,
		int64_t	seconds
	)

Estimate the number of messages that will be deleted by the dc_set_config()-options delete_device_after or delete_server_after.

This is typically used to show the estimated impact to the user before actually enabling ephemeral messages.

Parameters

context	The context object as returned from dc_context_new().
from_server	1=Estimate deletion count for server, 0=Estimate deletion count for device
seconds	Count messages older than the given number of seconds.

Returns: Number of messages that are older than the given number of seconds. This includes emails downloaded due to the show_emails option. Messages in the "saved messages" folder are not counted as they will not be deleted automatically.

◆ dc_forward_msgs()

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

context	The context object.
msg_ids	An array of uint32_t containing all message IDs that should be forwarded
msg_cnt	The number of messages IDs in the msg_ids array
chat_id	The destination chat ID.

Returns: None.

◆ dc_get_blobdir()

char * dc_get_blobdir ( const dc_context_t * context )

Get the blob directory.

Parameters

context The context object.

Returns: Blob directory associated with the context object, empty string if unset or on errors. NULL is never returned. The returned string must be released using dc_str_unref().

◆ dc_get_blocked_cnt()

int dc_get_blocked_cnt ( dc_context_t * context )

Get the number of blocked contacts.

Parameters

context The context object.

Returns: The number of blocked contacts.

◆ dc_get_blocked_contacts()

dc_array_t * dc_get_blocked_contacts ( dc_context_t * context )

Get blocked contacts.

Parameters

context The context object.

Returns: An array containing all blocked contact IDs. Must be dc_array_unref()'d after usage.

◆ dc_get_chat()

dc_chat_t * dc_get_chat	(	dc_context_t *	context,
		uint32_t	chat_id
	)

Get chat object by a chat ID.

Parameters

context	The context object as returned from dc_context_new().
chat_id	The 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_get_chat_contacts()

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

context	The context object as returned from dc_context_new().
chat_id	Chat 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.

◆ dc_get_chat_ephemeral_timer()

uint32_t dc_get_chat_ephemeral_timer	(	dc_context_t *	context,
		uint32_t	chat_id
	)

Get the chat's ephemeral message timer.

Parameters

context	The context object.
chat_id	The chat ID.

Returns: ephemeral timer value in seconds, 0 if the timer is disabled or if there is an error

◆ dc_get_chat_id_by_contact_id()

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

context	The context object as returned from dc_context_new().
contact_id	The 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_get_chat_media()

dc_array_t * dc_get_chat_media	(	dc_context_t *	context,
		uint32_t	chat_id,
		int	msg_type,
		int	msg_type2,
		int	msg_type3
	)

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

context	The context object as returned from dc_context_new().
chat_id	The chat ID to get all messages with media from.
msg_type	Specify a message type to query here, one of the DC_MSG constants.
msg_type2	Alternative message type to search for. 0 to skip.
msg_type3	Alternative message type to search for. 0 to skip.

Returns: An array with messages from the given chat ID that have the wanted message types.

◆ dc_get_chat_msgs()

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

context	The context object as returned from dc_context_new().
chat_id	The chat ID of which the messages IDs should be queried.
flags	If set to DC_GCM_ADDDAYMARKER, 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. To get the concrete time of the marker, use dc_array_get_timestamp().
marker1before	An 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_get_chatlist()

dc_chatlist_t * dc_get_chatlist	(	dc_context_t *	context,
		int	flags,
		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_set_chat_visibility(). 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

context	The context object as returned by dc_context_new()
flags	A 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 the flag DC_GCL_FOR_FORWARDING sorts "Saved messages" to the top of the chatlist and hides the "Device chat" and the deaddrop. typically used on forwarding, may be combined with DC_GCL_NO_SPECIALS to also hide the archive link. 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_str	An optional query for filtering the list. Only chats matching this query are returned. Give NULL for no filtering.
query_id	An 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.

◆ dc_get_config()

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

context	The context object. For querying system values, this can be NULL.
key	The key to query.

Returns: Returns current value of "key", if "key" is unset, the default value is returned. The returned value must be released using dc_str_unref(), NULL is never returned. If there is an error an empty string will be returned.

◆ dc_get_contact()

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

context	The context object.
contact_id	ID 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.

◆ dc_get_contact_encrinfo()

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

context	The context object.
contact_id	ID of the contact to get the encryption info for.

Returns: Multi-line text, must be released using dc_str_unref() after usage.

◆ dc_get_contacts()

dc_array_t * dc_get_contacts	(	dc_context_t *	context,
		uint32_t	flags,
		const char *	query
	)

Returns known and unblocked contacts.

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

Parameters

context	The context object.
flags	A 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.
query	A 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_get_draft()

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

context	The context object.
chat_id	The 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.

◆ dc_get_event_emitter()

dc_event_emitter_t * dc_get_event_emitter ( dc_context_t * context )

Create the event emitter that is used to receive events.

The library will emit various DC_EVENT events as "new message", "message read" etc. To get these events, you have to create an event emitter using this function and call dc_get_next_event() on the emitter.

Parameters

context The context object as created by dc_context_new().

Returns: Returns the event emitter, NULL on errors. Must be freed using dc_event_emitter_unref() after usage.

Note: Use only one event emitter per context. Having more than one event emitter running at the same time on the same context will result in events randomly delivered to the one or to the other.

◆ dc_get_fresh_msg_cnt()

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

context	The context object as returned from dc_context_new().
chat_id	The 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_get_fresh_msgs()

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

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

◆ dc_get_id()

uint32_t dc_get_id ( dc_context_t * context )

Get the ID of a context object.

Each context has an ID assigned. If the context was created through the dc_accounts_t account manager, the ID is unique, no other context handled by the account manager will have the same ID. If the context was created by dc_context_new(), a random ID is assigned.

Parameters

context The context object as created eg. by dc_accounts_get_account() or dc_context_new().

Returns: The context-id.

◆ dc_get_info()

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.

If the context is not open or configured only a subset of the information will be available. There is no guarantee about which information will be included when however.

Parameters

context The context object.

Returns: String which must be released using dc_str_unref() after usage. Never returns NULL.

◆ dc_get_locations()

dc_array_t * dc_get_locations	(	dc_context_t *	context,
		uint32_t	chat_id,
		uint32_t	contact_id,
		int64_t	timestamp_begin,
		int64_t	timestamp_end
	)

Get shared locations from the database.

The locations can be filtered by the chat-id, the contact-id and by a timespan.

The number of returned locations can be retrieved using dc_array_get_cnt(). To get information for each location, use dc_array_get_latitude(), dc_array_get_longitude(), dc_array_get_accuracy(), dc_array_get_timestamp(), dc_array_get_contact_id() and dc_array_get_msg_id(). The latter returns 0 if there is no message bound to the location.

Note that only if dc_array_is_independent() returns 0, the location is the current or a past position of the user. If dc_array_is_independent() returns 1, the location is any location on earth that is marked by the user.

Parameters

context	The context object.
chat_id	Chat-id to get location information for. 0 to get locations independently of the chat.
contact_id	Contact-id to get location information for. If also a chat-id is given, this should be a member of the given chat. 0 to get locations independently of the contact.
timestamp_begin	Start of timespan to return. Must be given in number of seconds since 00:00 hours, Jan 1, 1970 UTC. 0 for "start from the beginning".
timestamp_end	End of timespan to return. Must be given in number of seconds since 00:00 hours, Jan 1, 1970 UTC. 0 for "all up to now".

Returns: Array of locations, NULL is never returned. The array is sorted decending; the first entry in the array is the location with the newest timestamp. Note that this is only realated to the recent postion of the user if dc_array_is_independent() returns 0. The returned array must be freed using dc_array_unref().

Examples:

// get locations from the last hour for a global map
dc_array_t* loc = dc_get_locations(context, 0, 0, time(NULL)-60*60, 0);
for (int i=0; i<dc_array_get_cnt(); i++) {
    double lat = dc_array_get_latitude(loc, i);
    ...
}
dc_array_unref(loc);
 
// get locations from a contact for a global map
dc_array_t* loc = dc_get_locations(context, 0, contact_id, 0, 0);
...
 
// get all locations known for a given chat
dc_array_t* loc = dc_get_locations(context, chat_id, 0, 0, 0);
...
 
// get locations from a single contact for a given chat
dc_array_t* loc = dc_get_locations(context, chat_id, contact_id, 0, 0);
...

◆ dc_get_mime_headers()

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

context	The context object.
msg_id	The message id, must be the id of an incoming message.

Returns: Raw headers as a multi-line string, must be released using dc_str_unref() 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_get_msg()

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

context	The context object.
msg_id	The 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().

◆ dc_get_msg_cnt()

int dc_get_msg_cnt	(	dc_context_t *	context,
		uint32_t	chat_id
	)

Get the total number of messages in a chat.

Parameters

context	The context object as returned from dc_context_new().
chat_id	The ID of the chat to count the messages for.

Returns: Number of total messages in the given chat. 0 for errors or empty chats.

◆ dc_get_msg_info()

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

context	The context object object.
msg_id	The message id for which information should be generated

Returns: Text string, must be released using dc_str_unref() after usage

◆ dc_get_next_media()

uint32_t dc_get_next_media	(	dc_context_t *	context,
		uint32_t	msg_id,
		int	dir,
		int	msg_type,
		int	msg_type2,
		int	msg_type3
	)

Search next/previous message based on a given message and a list of types.

The Typically used to implement the "next" and "previous" buttons in a gallery or in a media player.

Parameters

context	The context object as returned from dc_context_new().
msg_id	This is the current message from which the next or previous message should be searched.
dir	1=get the next message, -1=get the previous one.
msg_type	Message type to search for. If 0, the message type from curr_msg_id is used.
msg_type2	Alternative message type to search for. 0 to skip.
msg_type3	Alternative message type to search for. 0 to skip.

Returns: Returns the message ID that should be played next. The returned message is in the same chat as the given one and has one of the given types. 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.

◆ dc_get_oauth2_url()

char * dc_get_oauth2_url	(	dc_context_t *	context,
		const char *	addr,
		const char *	redirect_uri
	)

Get url that can be used to initiate an OAuth2 authorisation.

If an OAuth2 authorization is possible for a given e-mail-address, this function returns the URL that should be opened in a browser.

If the user authorizes access, the given redirect_uri is called by the provider. It's up to the UI to handle this call.

The provider will attach some parameters to the url, most important the parameter code that should be set as the mail_pw. With server_flags set to DC_LP_AUTH_OAUTH2, dc_configure() can be called as usual afterwards.

Parameters

context	The context object.
addr	E-mail address the user has entered. In case the user selects a different e-mail-address during authorization, this is corrected in dc_configure()
redirect_uri	URL that will get `code` that is used as `mail_pw` then. Not all URLs are allowed here, however, the following should work: `chat.delta:/PATH`, `http://localhost:PORT/PATH`, `https://localhost:PORT/PATH`, `urn:ietf:wg:oauth:2.0:oob` (the latter just displays the code the user can copy+paste then)

Returns: URL that can be opened in the browser to start OAuth2. Returned strings must be released using dc_str_unref(). If OAuth2 is not possible for the given e-mail-address, NULL is returned.

◆ dc_get_securejoin_qr()

char * dc_get_securejoin_qr	(	dc_context_t *	context,
		uint32_t	chat_id
	)

Get QR code text that will offer an Setup-Contact or Verified-Group invitation.

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

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

Parameters

context	The context object.
chat_id	If set to a group-chat-id, the Verified-Group-Invite protocol is offered in the QR code; works for verified groups as well as for normal groups. If set to 0, the Setup-Contact protocol is offered in the QR code. See https://countermitm.readthedocs.io/en/latest/new.html for details about both protocols.

Returns: Text that should go to the QR code, On errors, an empty QR code is returned, NULL is never returned. The returned string must be released using dc_str_unref() after usage.

◆ dc_imex()

void dc_imex	(	dc_context_t *	context,
		int	what,
		const char *	param1,
		const char *	param2
	)

Import/export things.

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>.tar, if more than one backup is create on a day, the format is delta-chat-<day>-<number>.tar
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

context	The context.
what	One of the DC_IMEX_* constants.
param1	Meaning 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.
param2	Meaning depends on the DC_IMEX_* constants. Set to NULL if not used.

Returns: None.

◆ dc_imex_has_backup()

char * dc_imex_has_backup	(	dc_context_t *	context,
		const char *	dir
	)

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())
    }
    dc_str_unref(file);
}

Parameters

context	The context object.
dir	Directory to search backups in.

Returns: String with the backup file, typically given to dc_imex(), returned strings must be released using dc_str_unref(). The function returns NULL if no backup was found.

◆ dc_initiate_key_transfer()

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

context The context object.

Returns: The setup code. Must be released using dc_str_unref() after usage. On errors, eg. if the message could not be sent, NULL is returned.

◆ dc_is_configured()

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

context The context object.

Returns: 1=context is configured and can be used; 0=context is not configured and a configuration by dc_configure() is required.

◆ dc_is_contact_in_chat()

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

context	The context object.
chat_id	The chat ID to check.
contact_id	The 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

◆ dc_is_io_running()

int dc_is_io_running ( const dc_context_t * context )

Check if IO (SMTP/IMAP/Jobs) has been started.

Parameters

context The context object.

Returns: 1=IO is running; 0=IO is not running.

◆ dc_is_sending_locations_to_chat()

int dc_is_sending_locations_to_chat	(	dc_context_t *	context,
		uint32_t	chat_id
	)

Check if location streaming is enabled.

Location stream can be enabled or disabled using dc_send_locations_to_chat(). If you have already a dc_chat_t object, dc_chat_is_sending_locations() may be more handy.

Parameters

context	The context object.
chat_id	>0: Check if location streaming is enabled for the given chat. 0: Check of location streaming is enabled for any chat.

Returns: 1: location streaming is enabled for the given chat(s); 0: location streaming is disabled for the given chat(s).

◆ dc_join_securejoin()

uint32_t dc_join_securejoin	(	dc_context_t *	context,
		const char *	qr
	)

Continue a Setup-Contact or Verified-Group-Invite protocol started 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.

Depending on the given QR code, this function may takes some time and sends and receives several messages. Therefore, you should call it always in a separate thread; if you want to abort it, you should call dc_stop_ongoing_process().

If the given QR code starts the Setup-Contact protocol, the function typically returns immediately and the handshake runs in background. Subsequent calls of dc_join_securejoin() will abort unfinished tasks. The returned chat is the one-to-one opportunistic chat. When the protocol has finished, an info-message is added to that chat.
If the given QR code starts the Verified-Group-Invite protocol, the function waits until the protocol has finished. This is because the verified group is not opportunistic and can be created only when the contacts have verified each other.

See https://countermitm.readthedocs.io/en/latest/new.html for details about both protocols.

Parameters

context	The context object
qr	The 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. A returned chat-id does not guarantee that the chat or the belonging contact is verified. If needed, this be checked with dc_chat_is_verified() and dc_contact_is_verified(), however, in practise, the UI will just listen to DC_EVENT_CONTACTS_CHANGED unconditionally.

◆ dc_lookup_contact_id_by_addr()

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.

To get a list of all known and unblocked contacts, use dc_get_contacts().

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

Parameters

context	The context object.
addr	The e-mail-address to check.

Returns: Contact ID of the contact belonging to the e-mail-address or 0 if there is no contact that is or was introduced by an accepted contact.

◆ dc_marknoticed_all_chats()

void dc_marknoticed_all_chats ( dc_context_t * context )

Same as dc_marknoticed_chat() but for all chats.

Parameters

context The context object as returned from dc_context_new().

Returns: None.

◆ dc_marknoticed_chat()

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

context	The context object as returned from dc_context_new().
chat_id	The chat ID of which all messages should be marked as being noticed.

Returns: None.

◆ dc_marknoticed_contact()

void dc_marknoticed_contact	(	dc_context_t *	context,
		uint32_t	contact_id
	)

Mark all messages sent by the given contact as noticed.

Calling this function usually results in the event DC_EVENT_MSGS_CHANGED.

Parameters

context	The context object.
contact_id	The contact ID of which all messages should be marked as noticed.

Returns: None.

◆ dc_markseen_msgs()

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

context	The context object.
msg_ids	An array of uint32_t containing all the messages IDs that should be marked as seen.
msg_cnt	The number of message IDs in msg_ids.

Returns: None.

◆ dc_may_be_valid_addr()

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

addr	The 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

◆ dc_maybe_network()

void dc_maybe_network ( dc_context_t * context )

This function should be called when there is a hint that the network is available again, eg.

as a response to system event reporting network availability. The library will try to send pending messages out immediately.

Moreover, to have a reliable state when the app comes to foreground with network available, it may be reasonable to call the function also at that moment.

It is okay to call the function unconditionally when there is network available, however, calling the function without having network may interfere with the backoff algorithm and will led to let the jobs fail faster, with fewer retries and may avoid messages being sent out.

Finally, if the context was created by the dc_accounts_t account manager, use dc_accounts_maybe_network() instead of this function.

Parameters

context The context as created by dc_context_new().

Returns: None.

◆ dc_preconfigure_keypair()

int dc_preconfigure_keypair	(	dc_context_t *	context,
		const char *	addr,
		const char *	public_data,
		const char *	secret_data
	)

Save a keypair as the default keys for the user.

This API is only for testing purposes and should not be used as part of a normal application, use the import-export APIs instead.

This saves a public/private keypair as the default keypair in the context. It allows avoiding having to generate a secret key for unittests which need one.

Parameters

context	The context as created by dc_context_new().
addr	The email address of the user. This must match the configured_addr setting of the context as well as the UID of the key.
public_data	The public key as base64.
secret_data	The secret key as base64.

Returns: 1 on success, 0 on failure.

◆ dc_prepare_msg()

uint32_t dc_prepare_msg	(	dc_context_t *	context,
		uint32_t	chat_id,
		dc_msg_t *	msg
	)

Prepare a message for sending.

Call this function if the file to be sent is still in creation. Once you're done with creating the file, call dc_send_msg() as usual and the message will really be sent.

This is useful as the user can already send the next messages while e.g. 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 - dc_send_msg() copies the file to the blob directory if it is not yet there. To distinguish the two cases, msg->state must be set properly. The easiest way to ensure this is to re-use the same object for both calls.

Example:

char* blobdir = dc_get_blobdir(context);
char* file_to_send = mprintf("%s/%s", blobdir, "send.mp4")
 
dc_msg_t* msg = dc_msg_new(context, DC_MSG_VIDEO);
dc_msg_set_file(msg, file_to_send, NULL);
dc_prepare_msg(context, chat_id, msg);
 
// ... create the file ...
 
dc_send_msg(context, chat_id, msg);
 
dc_msg_unref(msg);
free(file_to_send);
dc_str_unref(file_to_send);

Parameters

context	The context object as returned from dc_context_new().
chat_id	Chat ID to send the message to.
msg	Message object to send to the chat defined by the chat ID. On succcess, msg_id and state of the object are 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 being prepared.

◆ dc_remove_contact_from_chat()

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

context	The context object.
chat_id	The chat ID to remove the contact from. Must be a group chat.
contact_id	The contact ID to remove from the chat.

Returns: 1=member removed from group, 0=error

◆ dc_search_msgs()

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

context	The context object as returned from dc_context_new().
chat_id	ID of the chat to search messages in. Set this to 0 for a global search.
query	The 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.

◆ dc_send_locations_to_chat()

void dc_send_locations_to_chat	(	dc_context_t *	context,
		uint32_t	chat_id,
		int	seconds
	)

Enable or disable location streaming for a chat.

Locations are sent to all members of the chat for the given number of seconds; after that, location streaming is automatically disabled for the chat. The current location streaming state of a chat can be checked using dc_is_sending_locations_to_chat().

The locations that should be sent to the chat can be set using dc_set_location().

Parameters

context	The context object.
chat_id	Chat id to enable location streaming for.
seconds	>0: enable location streaming for the given number of seconds; 0: disable location streaming.

Returns: None.

◆ dc_send_msg()

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, chat_id, msg);
 
dc_msg_unref(msg);

If you send images with the DC_MSG_IMAGE type, they will be recoded to a reasonable size before sending, if possible (cmp the dc_set_config()-option media_quality). If that fails, is not possible, or the image is already small enough, the image is sent as original. If you want images to be always sent as the original file, use the DC_MSG_FILE type.

Videos and other file types are currently not recoded by the library, with dc_prepare_msg(), however, you can do that from the UI.

Parameters

context	The context object as returned from dc_context_new().
chat_id	Chat ID to send the message to. If dc_prepare_msg() was called before, this parameter can be 0.
msg	Message 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 to be sent. 0 in case of errors.

◆ dc_send_msg_sync()

uint32_t dc_send_msg_sync	(	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, synchronously.

This bypasses the IO scheduler and creates its own SMTP connection. Which means this is useful when the scheduler is not running.

Parameters

context	The context object as returned from dc_context_new().
chat_id	Chat ID to send the message to. If dc_prepare_msg() was called before, this parameter can be 0.
msg	Message 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 to be sent. 0 in case of errors.

◆ dc_send_text_msg()

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.

◆ dc_send_videochat_invitation()

uint32_t dc_send_videochat_invitation	(	dc_context_t *	context,
		uint32_t	chat_id
	)

Send invitation to a videochat.

This function reads the webrtc_instance config value, may check that the server is working in some way and creates a unique room for this chat, if needed doing a TOKEN roundtrip for that.

After that, the function sends out a message that contains information to join the room:

To allow non-delta-clients to join the chat, the message contains a text-area with some descriptive text and a url that can be opened in a supported browser to join the videochat
delta-clients can get all information needed from the message object, using eg. dc_msg_get_videochat_url() and check dc_msg_get_viewtype() for DC_MSG_VIDEOCHAT_INVITATION

dc_send_videochat_invitation() is blocking and may take a while, so the UIs will typically call the function from within a thread. Moreover, UIs will typically enter the room directly without an additional click on the message, for this purpose, the function returns the message-id directly.

As for other messages sent, this function sends the event DC_EVENT_MSGS_CHANGED on succcess, the message has a delivery state, and so on. The recipient will get noticed by the call as usual by DC_EVENT_INCOMING_MSG or DC_EVENT_MSGS_CHANGED, However, UIs might some things differently, eg. play a different sound.

Parameters

context	The context object
chat_id	The chat to start a videochat for.

Returns: The id if the message sent out or 0 for errors.

◆ dc_set_chat_ephemeral_timer()

int dc_set_chat_ephemeral_timer	(	dc_context_t *	context,
		uint32_t	chat_id,
		uint32_t	timer
	)

Set the chat's ephemeral message timer.

This timer is applied to all messages in a chat and starts when the message is read. The setting is synchronized to all clients participating in a chat.

Parameters

context	The context object.
chat_id	The chat ID to set the ephemeral message timer for.
timer	The timer value in seconds or 0 to disable the timer.

Returns: 1=success, 0=error

◆ dc_set_chat_mute_duration()

int dc_set_chat_mute_duration	(	dc_context_t *	context,
		uint32_t	chat_id,
		int64_t	duration
	)

Set mute duration of a chat.

The ui can then call dc_chat_is_muted() when receiving a new message to decide whether it should trigger an notification.

Sends out DC_EVENT_CHAT_MODIFIED.

Parameters

chat_id	The chat ID to set the mute duration.
duration	The duration (0 for no mute, -1 for forever mute, everything else is is the relative mute duration from now in seconds)
context	The context object.

Returns: 1=success, 0=error

◆ dc_set_chat_name()

int dc_set_chat_name	(	dc_context_t *	context,
		uint32_t	chat_id,
		const char *	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_id	The chat ID to set the name for. Must be a group chat.
name	New name of the group.
context	The context object.

Returns: 1=success, 0=error

◆ dc_set_chat_profile_image()

int dc_set_chat_profile_image	(	dc_context_t *	context,
		uint32_t	chat_id,
		const char *	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

context	The context object.
chat_id	The chat ID to set the image for.
image	Full path of the image to use as the group image. The image will immediately be copied to the `blobdir`; the original image will not be needed anymore. 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

◆ dc_set_chat_visibility()

void dc_set_chat_visibility	(	dc_context_t *	context,
		uint32_t	chat_id,
		int	visibility
	)

Set chat visibility to pinned, archived or normal.

Calling this function usually results in the event DC_EVENT_MSGS_CHANGED See DC_CHAT_VISIBILITY for detailed information about the visibilities.

Parameters

context	The context object as returned from dc_context_new().
chat_id	The ID of the chat to change the visibility for.
visibility	one of DC_CHAT_VISIBILITY

Returns: None.

◆ dc_set_config()

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
mail_security= IMAP-socket, one of DC_SOCKET, defaults to DC_SOCKET_AUTO
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
send_security= SMTP-socket, one of DC_SOCKET, defaults to DC_SOCKET_AUTO
server_flags = IMAP-/SMTP-flags as a combination of DC_LP flags, guessed if left out
imap_certificate_checks = how to check IMAP certificates, one of the DC_CERTCK flags, defaults to DC_CERTCK_AUTO (0)
smtp_certificate_checks = how to check SMTP certificates, one of the DC_CERTCK flags, defaults to DC_CERTCK_AUTO (0)
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 immediately be copied to the blobdir; the original image will not be needed anymore. NULL to remove the avatar. As for displayname and selfstatus, also the avatar is sent to the recipients. To save traffic, however, the avatar is attached only as needed and also recoded to a reasonable size.
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)
bcc_self = 0=do not send a copy of outgoing messages to self (default), 1=send a copy of outgoing messages to self. Sending messages to self is needed for a proper multi-account setup, however, on the other hand, may lead to unwanted notifications in non-delta clients.
inbox_watch = 1=watch INBOX-folder for changes (default), 0=do not watch the INBOX-folder, changes require restarting IO by calling dc_stop_io() and then dc_start_io().
sentbox_watch= 1=watch Sent-folder for changes (default), 0=do not watch the Sent-folder, changes require restarting IO by calling dc_stop_io() and then dc_start_io().
mvbox_watch = 1=watch DeltaChat-folder for changes (default), 0=do not watch the DeltaChat-folder, changes require restarting IO by calling dc_stop_io() and then dc_start_io().
mvbox_move = 1=heuristically detect chat-messages and move them to the DeltaChat-folder, 0=do not move chat-messages
show_emails = DC_SHOW_EMAILS_OFF (0)= show direct replies to chats only (default), DC_SHOW_EMAILS_ACCEPTED_CONTACTS (1)= also show all mails of confirmed contacts, DC_SHOW_EMAILS_ALL (2)= also show mails of unconfirmed contacts in the deaddrop.
key_gen_type = DC_KEY_GEN_DEFAULT (0)= generate recommended key type (default), DC_KEY_GEN_RSA2048 (1)= generate RSA 2048 keypair DC_KEY_GEN_ED25519 (2)= generate Ed25519 keypair
save_mime_headers = 1=save mime headers and make dc_get_mime_headers() work for subsequent calls, 0=do not save mime headers (default)
delete_device_after = 0=do not delete messages from device automatically (default), >=1=seconds, after which messages are deleted automatically from the device. Messages in the "saved messages" chat (see dc_chat_is_self_talk()) are skipped. Messages are deleted whether they were seen or not, the UI should clearly point that out. See also dc_estimate_deletion_cnt().
delete_server_after = 0=do not delete messages from server automatically (default), 1=delete messages directly after receiving from server, mvbox is skipped. >1=seconds, after which messages are deleted automatically from the server, mvbox is used as defined. "Saved messages" are deleted from the server as well as emails matching the show_emails settings above, the UI should clearly point that out. See also dc_estimate_deletion_cnt().
media_quality = DC_MEDIA_QUALITY_BALANCED (0) = good outgoing images/videos/voice quality at reasonable sizes (default) DC_MEDIA_QUALITY_WORSE (1) allow worse images/videos/voice quality to gain smaller sizes, suitable for providers or areas known to have a bad connection. The library uses the media_quality setting to use different defaults for recoding images sent with type DC_MSG_IMAGE. If needed, recoding other file types is up to the UI.
webrtc_instance = webrtc instance to use for videochats in the form [basicwebrtc:|jitsi:]https://example.com/subdir#roomname=$ROOM if the url is prefixed by basicwebrtc, the server is assumed to be of the type https://github.com/cracker0dks/basicwebrtc which some UIs have native support for. The type jitsi: may be handled by external apps. If no type is prefixed, the videochat is handled completely in a browser.

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

Parameters

context	The context object.
key	The option to change, see above.
value	The value to save for "key"

Returns: 0=failure, 1=success

◆ dc_set_config_from_qr()

int dc_set_config_from_qr	(	dc_context_t *	context,
		const char *	qr
	)

Set configuration values from a QR code.

Before this function is called, dc_check_qr() should confirm the type of the QR code is DC_QR_ACCOUNT or DC_QR_WEBRTC_INSTANCE.

Internally, the function will call dc_set_config() with the appropriate keys, eg. addr and mail_pw for DC_QR_ACCOUNT or webrtc_instance for DC_QR_WEBRTC_INSTANCE.

Parameters

context	The context object
qr	scanned QR code

Returns: int (==0 on error, 1 on success)

◆ dc_set_draft()

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

context	The context object.
chat_id	The chat ID to save the draft for.
msg	The 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.

◆ dc_set_location()

int dc_set_location	(	dc_context_t *	context,
		double	latitude,
		double	longitude,
		double	accuracy
	)

Set current location.

The location is sent to all chats where location streaming is enabled using dc_send_locations_to_chat().

Typically results in the event DC_EVENT_LOCATION_CHANGED with contact_id set to DC_CONTACT_ID_SELF.

The UI should call this function on all location changes. The locations set by this function are not sent immediately, instead a message with the last locations is sent out every some minutes or when the user sends out a normal message, the last locations are attached.

Parameters

context	The context object.
latitude	North-south position of the location. Set to 0.0 if the latitude is not known.
longitude	East-west position of the location. Set to 0.0 if the longitude is not known.
accuracy	Estimated accuracy of the location, radial, in meters. Set to 0.0 if the accuracy is not known.

Returns: 1: location streaming is still enabled for at least one chat, this dc_set_location() should be called as soon as the location changes; 0: location streaming is no longer needed, dc_is_sending_locations_to_chat() is false for all chats.

◆ dc_set_stock_translation()

int dc_set_stock_translation	(	dc_context_t *	context,
		uint32_t	stock_id,
		const char *	stock_msg
	)

Set stock string translation.

The function will emit warnings if it returns an error state.

Parameters

context	The context object
stock_id	the integer id of the stock message (DC_STR_*)
stock_msg	the message to be used

Returns: int (==0 on error, 1 on success)

◆ dc_star_msgs()

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

context	The context object.
msg_ids	An array of uint32_t message IDs defining the messages to star or unstar
msg_cnt	The number of IDs in msg_ids
star	0=unstar the messages in msg_ids, 1=star them

Returns: None.

◆ dc_start_io()

void dc_start_io ( dc_context_t * context )

Start job and IMAP/SMTP tasks.

If IO is already running, nothing happens. To check the current IO state, use dc_is_io_running().

If the context was created by the dc_accounts_t account manager, use dc_accounts_start_io() instead of this function.

Parameters

context The context object as created by dc_context_new().

Returns: None

◆ dc_stop_io()

void dc_stop_io ( dc_context_t * context )

Stop job and IMAP/SMTP tasks and return when they are finished.

If IO is not running, nothing happens. To check the current IO state, use dc_is_io_running().

If the context was created by the dc_accounts_t account manager, use dc_accounts_stop_io() instead of this function.

Parameters

context The context object as created by dc_context_new().

Returns: None

◆ dc_stop_ongoing_process()

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.

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

context The context object.

Returns: None.

◆ dc_str_unref()

void dc_str_unref ( char * str )

Release a string returned by another deltachat-core function.

Strings returned by any deltachat-core-function MUST NOT be released by the standard free() function; always use dc_str_unref() for this purpose.
dc_str_unref() MUST NOT be called for strings not returned by deltachat-core.
dc_str_unref() MUST NOT be called for other objectes returned by deltachat-core.

Parameters

str	The string to release.

Returns: None.

◆ dc_update_device_chats()

void dc_update_device_chats ( dc_context_t * context )

Init device-messages and saved-messages chat.

This function adds the device-chat and saved-messages chat and adds one or more welcome or update-messages. The ui can add messages on its own using dc_add_device_msg() - for ordering, either before or after or even without calling this function.

Chat and message creation is done only once. So if the user has manually deleted things, they won't be re-created (however, not seen device messages are added and may re-create the device-chat).

Parameters

context The context object.

Returns: None.

◆ dc_was_device_msg_ever_added()

int dc_was_device_msg_ever_added	(	dc_context_t *	context,
		const char *	label
	)

Check if a device-message with a given label was ever added.

Device-messages can be added dc_add_device_msg().

Parameters

context	The context object.
label	Label of the message to check.

Returns: 1=A message with this label was added at some point, 0=A message with this label was never added.

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

deltachat.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ dc_add_address_book()

◆ dc_add_contact_to_chat()

◆ dc_add_device_msg()

◆ dc_block_contact()

◆ dc_chatlist_get_summary2()

◆ dc_check_qr()

◆ dc_configure()

◆ dc_context_new()

◆ dc_context_unref()

◆ dc_continue_key_transfer()

◆ dc_create_chat_by_contact_id()

◆ dc_create_chat_by_msg_id()

◆ dc_create_contact()

◆ dc_create_group_chat()

◆ dc_delete_all_locations()

◆ dc_delete_chat()

◆ dc_delete_contact()

◆ dc_delete_msgs()

◆ dc_estimate_deletion_cnt()

◆ dc_forward_msgs()

◆ dc_get_blobdir()

◆ dc_get_blocked_cnt()

◆ dc_get_blocked_contacts()

◆ dc_get_chat()

◆ dc_get_chat_contacts()

◆ dc_get_chat_ephemeral_timer()

◆ dc_get_chat_id_by_contact_id()

◆ dc_get_chat_media()

◆ dc_get_chat_msgs()

◆ dc_get_chatlist()

◆ dc_get_config()

◆ dc_get_contact()

◆ dc_get_contact_encrinfo()

◆ dc_get_contacts()

◆ dc_get_draft()

◆ dc_get_event_emitter()

◆ dc_get_fresh_msg_cnt()

◆ dc_get_fresh_msgs()

◆ dc_get_id()

◆ dc_get_info()

◆ dc_get_locations()

◆ dc_get_mime_headers()

◆ dc_get_msg()

◆ dc_get_msg_cnt()

◆ dc_get_msg_info()

◆ dc_get_next_media()

◆ dc_get_oauth2_url()

◆ dc_get_securejoin_qr()

◆ dc_imex()

◆ dc_imex_has_backup()

◆ dc_initiate_key_transfer()

◆ dc_is_configured()

◆ dc_is_contact_in_chat()

◆ dc_is_io_running()

◆ dc_is_sending_locations_to_chat()

◆ dc_join_securejoin()

◆ dc_lookup_contact_id_by_addr()

◆ dc_marknoticed_all_chats()

◆ dc_marknoticed_chat()

◆ dc_marknoticed_contact()

◆ dc_markseen_msgs()

◆ dc_may_be_valid_addr()

◆ dc_maybe_network()

◆ dc_preconfigure_keypair()

◆ dc_prepare_msg()

◆ dc_remove_contact_from_chat()

◆ dc_search_msgs()

◆ dc_send_locations_to_chat()

◆ dc_send_msg()

◆ dc_send_msg_sync()

◆ dc_send_text_msg()

◆ dc_send_videochat_invitation()

◆ dc_set_chat_ephemeral_timer()

◆ dc_set_chat_mute_duration()

◆ dc_set_chat_name()

◆ dc_set_chat_profile_image()

◆ dc_set_chat_visibility()