 |
Delta Chat Core C Interface
|
Loading...
Searching...
No Matches
|
Delta Chat Core C Interface
|
An object representing a single account. More...
#include <deltachat.h>
Public Member Functions | |
| void | dc_accept_chat (dc_context_t *context, uint32_t chat_id) |
| Accept a contact request chat. | |
| int | dc_add_address_book (dc_context_t *context, const char *addr_book) |
| Add a number of 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. | |
| uint32_t | dc_add_device_msg (dc_context_t *context, const char *label, dc_msg_t *msg) |
| Add a message to the device-chat. | |
| void | dc_block_chat (dc_context_t *context, uint32_t chat_id) |
| Block a chat. | |
| void | dc_block_contact (dc_context_t *context, uint32_t contact_id, int block) |
| Block or unblock a contact. | |
| 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. | |
| dc_lot_t * | dc_check_qr (dc_context_t *context, const char *qr) |
| Check a scanned QR code. | |
| void | dc_configure (dc_context_t *context) |
| Configure a context. | |
| int | dc_context_change_passphrase (dc_context_t *context, const char *passphrase) |
| Changes the passphrase on the open database. | |
| int | dc_context_is_open (dc_context_t *context) |
| Returns 1 if database is open. | |
| dc_context_t * | dc_context_new (const char *os_name, const char *dbfile, const char *blobdir) |
| Create a new context object and try to open it without passphrase. | |
| dc_context_t * | dc_context_new_closed (const char *dbfile) |
| Create a new context object. | |
| int | dc_context_open (dc_context_t *context, const char *passphrase) |
| Opens the database with the given passphrase. | |
| void | dc_context_unref (dc_context_t *context) |
| Free a context object. | |
| 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. | |
| uint32_t | dc_create_broadcast_list (dc_context_t *context) |
| Create a new broadcast list. | |
| uint32_t | dc_create_chat_by_contact_id (dc_context_t *context, uint32_t contact_id) |
| Create a normal chat with a single user. | |
| 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. | |
| uint32_t | dc_create_group_chat (dc_context_t *context, int protect, const char *name) |
| Create a new group chat. | |
| char * | dc_create_qr_svg (const char *payload) |
| Create a QR code from any input data. | |
| void | dc_delete_all_locations (dc_context_t *context) |
| Delete all locations on the current device. | |
| void | dc_delete_chat (dc_context_t *context, uint32_t chat_id) |
| Delete a chat. | |
| int | dc_delete_contact (dc_context_t *context, uint32_t contact_id) |
| Delete a contact so that it disappears from the corresponding lists. | |
| void | dc_delete_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt) |
| Delete messages. | |
| void | dc_download_full_msg (dc_context_t *context, int msg_id) |
| Asks the core to start downloading a message fully. | |
| 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. | |
| 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. | |
| char * | dc_get_blobdir (const dc_context_t *context) |
| Get the blob directory. | |
| int | dc_get_blocked_cnt (dc_context_t *context) |
| Get the number of blocked contacts. | |
| dc_array_t * | dc_get_blocked_contacts (dc_context_t *context) |
| Get blocked contacts. | |
| dc_chat_t * | dc_get_chat (dc_context_t *context, uint32_t chat_id) |
| Get a chat object by a chat ID. | |
| dc_array_t * | dc_get_chat_contacts (dc_context_t *context, uint32_t chat_id) |
| Get the contact IDs belonging to a chat. | |
| char * | dc_get_chat_encrinfo (dc_context_t *context, uint32_t chat_id) |
| Get encryption info for a chat. | |
| uint32_t | dc_get_chat_ephemeral_timer (dc_context_t *context, uint32_t chat_id) |
| Get the chat's ephemeral message timer. | |
| 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. | |
| 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 given chat or any chat. | |
| 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. | |
| 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. | |
| char * | dc_get_config (dc_context_t *context, const char *key) |
| Get a configuration option. | |
| int | dc_get_connectivity (dc_context_t *context) |
| Get the current connectivity, i.e. | |
| char * | dc_get_connectivity_html (dc_context_t *context) |
| Get an overview of the current connectivity, and possibly more statistics. | |
| dc_contact_t * | dc_get_contact (dc_context_t *context, uint32_t contact_id) |
| Get a single contact object. | |
| char * | dc_get_contact_encrinfo (dc_context_t *context, uint32_t contact_id) |
| Get encryption info for a contact. | |
| dc_array_t * | dc_get_contacts (dc_context_t *context, uint32_t flags, const char *query) |
| Returns known and unblocked contacts. | |
| dc_msg_t * | dc_get_draft (dc_context_t *context, uint32_t chat_id) |
| Get draft for a chat, if any. | |
| dc_event_emitter_t * | dc_get_event_emitter (dc_context_t *context) |
| Create the event emitter that is used to receive events. | |
| int | dc_get_fresh_msg_cnt (dc_context_t *context, uint32_t chat_id) |
| Get the number of fresh messages in a chat. | |
| dc_array_t * | dc_get_fresh_msgs (dc_context_t *context) |
| Returns the message IDs of all fresh messages of any chat. | |
| uint32_t | dc_get_id (dc_context_t *context) |
| Get the ID of a context object. | |
| char * | dc_get_info (const dc_context_t *context) |
| Get information about the context. | |
| char * | dc_get_last_error (dc_context_t *context) |
| Get last error string. | |
| 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. | |
| 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. | |
| int | dc_get_msg_cnt (dc_context_t *context, uint32_t chat_id) |
| Get the total number of messages in a chat. | |
| char * | dc_get_msg_html (dc_context_t *context, uint32_t msg_id) |
| Get uncut message, if available. | |
| char * | dc_get_msg_info (dc_context_t *context, uint32_t msg_id) |
| Get an informational text for a single message. | |
| dc_array_t * | dc_get_next_msgs (dc_context_t *context) |
Returns the message IDs of all messages of any chat with a database ID higher than last_msg_id config value. | |
| 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 authorization. | |
| int | dc_get_push_state (dc_context_t *context) |
| Get the current push notification state. | |
| 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. | |
| char * | dc_get_securejoin_qr_svg (dc_context_t *context, uint32_t chat_id) |
| Get QR code image from the QR code text generated by dc_get_securejoin_qr(). | |
| dc_chatlist_t * | dc_get_similar_chatlist (dc_context_t *context, uint32_t chat_id) |
| Returns a list of similar chats. | |
| char * | dc_get_webxdc_status_updates (dc_context_t *context, uint32_t msg_id, uint32_t serial) |
| Get webxdc status updates. | |
| void | dc_imex (dc_context_t *context, int what, const char *param1, const char *param2) |
| Import/export things. | |
| char * | dc_imex_has_backup (dc_context_t *context, const char *dir) |
| Check if there is a backup file. | |
| dc_array_t * | dc_import_vcard (dc_context_t *context, const char *vcard) |
| Import a vCard. | |
| uint32_t | dc_init_webxdc_integration (dc_context_t *context, uint32_t chat_id) |
| Init a Webxdc integration. | |
| char * | dc_initiate_key_transfer (dc_context_t *context) |
| Initiate Autocrypt Setup Transfer. | |
| int | dc_is_configured (const dc_context_t *context) |
| Check if the context is already configured. | |
| 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. | |
| int | dc_is_sending_locations_to_chat (dc_context_t *context, uint32_t chat_id) |
| Check if location streaming is enabled. | |
| 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(). | |
| 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. | |
| char * | dc_make_vcard (dc_context_t *context, uint32_t contact_id) |
| Make a vCard. | |
| void | dc_marknoticed_chat (dc_context_t *context, uint32_t chat_id) |
| Mark all messages in a chat as noticed. | |
| void | dc_markseen_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt) |
| Mark messages as presented to the user. | |
| int | dc_may_be_valid_addr (const char *addr) |
| Rough check if a string may be a valid e-mail address. | |
| void | dc_maybe_network (dc_context_t *context) |
| This function should be called when there is a hint that the network is available again, e.g. | |
| int | dc_preconfigure_keypair (dc_context_t *context, const char *secret_data) |
| Save a keypair as the default keys for the user. | |
| int | dc_receive_backup (dc_context_t *context, const char *qr) |
| Gets a backup offered by a dc_backup_provider_t object on another device. | |
| int | dc_remove_contact_from_chat (dc_context_t *context, uint32_t chat_id, uint32_t contact_id) |
| Remove a member from a group. | |
| int | dc_resend_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt) |
| Resend messages and make information available for newly added chat members. | |
| void | dc_save_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt) |
| Save a copy of messages in "Saved Messages". | |
| dc_array_t * | dc_search_msgs (dc_context_t *context, uint32_t chat_id, const char *query) |
| Search messages containing the given query string. | |
| void | dc_send_delete_request (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt) |
| Send chat members a request to delete the given messages. | |
| void | dc_send_edit_request (dc_context_t *context, uint32_t msg_id, const char *new_text) |
| Send chat members a request to edit the given message's text. | |
| void | dc_send_locations_to_chat (dc_context_t *context, uint32_t chat_id, int seconds) |
| Enable or disable location streaming for a chat. | |
| 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. | |
| 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. | |
| 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. | |
| uint32_t | dc_send_videochat_invitation (dc_context_t *context, uint32_t chat_id) |
| Send invitation to a videochat. | |
| int | dc_send_webxdc_status_update (dc_context_t *context, uint32_t msg_id, const char *json, const char *descr) |
| A webxdc instance sends a status update to its other members. | |
| int | dc_set_chat_ephemeral_timer (dc_context_t *context, uint32_t chat_id, uint32_t timer) |
| Set the chat's ephemeral message timer. | |
| int | dc_set_chat_mute_duration (dc_context_t *context, uint32_t chat_id, int64_t duration) |
| Set mute duration of a chat. | |
| int | dc_set_chat_name (dc_context_t *context, uint32_t chat_id, const char *name) |
| Set group name. | |
| int | dc_set_chat_profile_image (dc_context_t *context, uint32_t chat_id, const char *image) |
| Set group profile image. | |
| void | dc_set_chat_visibility (dc_context_t *context, uint32_t chat_id, int visibility) |
| Set chat visibility to pinned, archived or normal. | |
| int | dc_set_config (dc_context_t *context, const char *key, const char *value) |
| Configure the context. | |
| int | dc_set_config_from_qr (dc_context_t *context, const char *qr) |
| Set configuration values from a QR code. | |
| 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. | |
| int | dc_set_location (dc_context_t *context, double latitude, double longitude, double accuracy) |
| Set current location. | |
| int | dc_set_stock_translation (dc_context_t *context, uint32_t stock_id, const char *stock_msg) |
| Set stock string translation. | |
| void | dc_set_webxdc_integration (dc_context_t *context, const char *file) |
| Set Webxdc file as integration. | |
| void | dc_start_io (dc_context_t *context) |
| Start job and IMAP/SMTP tasks. | |
| void | dc_stop_io (dc_context_t *context) |
| Stop job, IMAP, SMTP and other tasks and return when they are finished. | |
| void | dc_stop_ongoing_process (dc_context_t *context) |
| Signal an ongoing process to stop. | |
| void | dc_str_unref (char *str) |
| Release a string returned by another deltachat-core function. | |
| dc_array_t * | dc_wait_next_msgs (dc_context_t *context) |
| Waits for notification of new messages and returns an array of new message IDs. | |
| 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. | |
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.
| void dc_accept_chat | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Accept a contact request chat.
Use it to accept "contact request" chats as indicated by dc_chat_is_contact_request().
If the dc_set_config()-option bot is set, all chats are accepted automatically and calling this function has no effect.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to accept. |
| 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 e-mail address is added twice. Trying to add e-mail addresses that are already in the contact list, results in updating the name unless the name was changed manually by the user. If any e-mail 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.
| context | The context object. |
| addr_book | A multi-line string in the format Name one\nAddress one\nName two\nAddress two. If an e-mail address already exists, the name is updated unless it was edited manually by dc_create_contact() before. |
| 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 has group protection enabled, 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.
| 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. |
| 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()
| 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 | The 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. |
Example:
| void dc_block_chat | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Block a chat.
Blocking 1:1 chats blocks the corresponding contact. Blocking mailing lists creates a pseudo-contact in the list of blocked contacts, so blocked mailing lists can be discovered and unblocked the same way as the contacts. Blocking group chats deletes the chat without blocking any contacts, so it may pop up again later.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to block. |
| 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.
| context | The context object. |
| contact_id | The ID of the contact to block or unblock. |
| block | 1=block contact, 0=unblock contact |
| 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, it takes the chat ID and the 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 representation as done e.g. 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.
| context | The context object. |
| chat_id | The chat ID to get a summary for. |
| msg_id | The message ID to get a summary for. |
| dc_lot_t * dc_check_qr | ( | dc_context_t * | context, |
| const char * | qr ) |
Check a scanned QR code.
The function takes the raw text scanned and checks what can be done with it.
The UI is supposed to show the result to the user. In case there are further actions possible, the UI has to ask the user before doing further steps.
The QR code state is returned in dc_lot_t::state as:
| context | The context object. |
| qr | The text of the scanned QR code. |
| void dc_configure | ( | dc_context_t * | context | ) |
Configure a context.
During configuration IO must not be started, if needed stop IO using dc_accounts_stop_io() or dc_stop_io() first. If the context is already configured, this function will try to change the configuration.
addr and mail_pw using dc_set_config().mail_user to use a different user name than addr and send_pw to use a different password for the SMTP server.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 emitted; 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.
| context | The context object. |
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:
| int dc_context_change_passphrase | ( | dc_context_t * | context, |
| const char * | passphrase ) |
Changes the passphrase on the open database.
Existing database must already be encrypted and the passphrase cannot be NULL or empty. It is impossible to encrypt unencrypted database with this method and vice versa.
| context | The context object. |
| passphrase | The new passphrase. |
| int dc_context_is_open | ( | dc_context_t * | context | ) |
Returns 1 if database is open.
| context | The context object. |
| dc_context_t * dc_context_new | ( | const char * | os_name, |
| const char * | dbfile, | ||
| const char * | blobdir ) |
Create a new context object and try to open it without passphrase.
If database is encrypted, the result is the same as using dc_context_new_closed() and the database should be opened with dc_context_open() before using.
| os_name | Deprecated, pass NULL or empty string here. |
| dbfile | The file to use to store the database, something like ~/file won't work, use absolute paths. |
| blobdir | Deprecated, pass NULL or an empty string here. |
| dc_context_t * dc_context_new_closed | ( | const char * | dbfile | ) |
Create a new context object.
After creation it is usually opened with dc_context_open() and started with dc_start_io() so it is connected and mails are fetched.
| dbfile | The file to use to store the database, something like ~/file won't work, use absolute paths. |
If you want to use multiple context objects at the same time, this can be managed using dc_accounts_t.
| int dc_context_open | ( | dc_context_t * | context, |
| const char * | passphrase ) |
Opens the database with the given passphrase.
This can only be used on closed context, such as created by dc_context_new_closed(). If the database is new, this operation sets the database passphrase. For existing databases the passphrase should be the one used to encrypt the database the first time.
| context | The context object. |
| passphrase | The passphrase to use with the database. Pass NULL or empty string to use no passphrase and no encryption. |
| void dc_context_unref | ( | dc_context_t * | context | ) |
Free a context object.
You have to call this function also for accounts returned by dc_accounts_get_account() or dc_accounts_get_selected_account().
| 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. |
| 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).
| context | The context object. |
| msg_id | The ID of the setup message to decrypt. |
| setup_code | The 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. |
| uint32_t dc_create_broadcast_list | ( | dc_context_t * | context | ) |
Create a new broadcast list.
Broadcast lists are similar to groups on the sending device, however, recipients get the messages in a read-only chat and will see who the other members are.
For historical reasons, this function does not take a name directly, instead you have to set the name using dc_set_chat_name() after creating the broadcast list.
| context | The context object. |
| 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; to get the chat messages, use dc_get_chat_msgs().
| 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. |
| 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.
| context | The context object. |
| name | The name of the contact to add. If you do not know the name belonging to the address, you can give NULL here. |
| addr | The e-mail address of the contact to add. If the e-mail address already exists, the name is updated and the origin is increased to "manually created". |
| uint32_t dc_create_group_chat | ( | dc_context_t * | context, |
| int | protect, | ||
| const char * | name ) |
Create a new group chat.
After creation, 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.
| context | The context object. |
| protect | If set to 1 the function creates group with protection initially enabled. Only 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() |
| char * dc_create_qr_svg | ( | const char * | payload | ) |
Create a QR code from any input data.
The QR code is returned as a square SVG image.
| payload | The content for the QR code. |
| 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.
| context | The context object. |
| 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:
To leave a chat explicitly, use dc_remove_contact_from_chat() with chat_id=DC_CONTACT_ID_SELF)
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to delete. |
| int dc_delete_contact | ( | dc_context_t * | context, |
| uint32_t | contact_id ) |
Delete a contact so that it disappears from the corresponding lists.
Depending on whether there are ongoing chats, deletion is done by physical deletion or hiding. The contact is deleted from the local device.
May result in a DC_EVENT_CONTACTS_CHANGED event.
| context | The context object. |
| contact_id | The ID of the contact to delete. |
| void dc_delete_msgs | ( | dc_context_t * | context, |
| const uint32_t * | msg_ids, | ||
| int | msg_cnt ) |
Delete messages.
The messages are deleted on all devices and on the IMAP server.
| 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. |
| void dc_download_full_msg | ( | dc_context_t * | context, |
| int | msg_id ) |
Asks the core to start downloading a message fully.
This function is typically called when the user hits the "Download" button that is shown by the UI in case dc_msg_get_download_state() returns DC_DOWNLOAD_AVAILABLE or DC_DOWNLOAD_FAILURE.
On success, the view type of the message may change or the message may be replaced completely by one or more messages with other message IDs. That may happen e.g. in cases where the message was encrypted and the type could not be determined without fully downloading. Downloaded content can be accessed as usual after download, e.g. using dc_msg_get_file().
To reflect these changes a DC_EVENT_MSGS_CHANGED event will be emitted.
| context | The context object. |
| msg_id | The message ID to download the content for. |
| 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 deletion of old messages.
| 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. |
show_emails option. Messages in the "saved messages" folder are not counted as they will not be deleted automatically. | 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.
All types of messages can be forwarded, however, they will be flagged as such (dc_msg_is_forwarded() is set).
Original sender, info-state and webxdc updates are not forwarded on purpose.
| 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. |
| char * dc_get_blobdir | ( | const dc_context_t * | context | ) |
Get the blob directory.
| context | The context object. |
| int dc_get_blocked_cnt | ( | dc_context_t * | context | ) |
Get the number of blocked contacts.
| context | The context object. |
| dc_array_t * dc_get_blocked_contacts | ( | dc_context_t * | context | ) |
Get blocked contacts.
| context | The context object. |
| dc_chat_t * dc_get_chat | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Get a chat object by a chat ID.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to get the chat object for. |
| dc_array_t * dc_get_chat_contacts | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Get the contact IDs belonging to a chat.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to get the belonging contact IDs for. |
| char * dc_get_chat_encrinfo | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Get encryption info for a chat.
Get a multi-line encryption info, containing encryption preferences of all members. Can be used to find out why messages sent to group are not encrypted.
| context | The context object. |
| chat_id | The ID of the chat to get the encryption info for. |
| uint32_t dc_get_chat_ephemeral_timer | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Get the chat's ephemeral message timer.
The ephemeral message timer is set by dc_set_chat_ephemeral_timer() on this or any other device participating in the chat.
| context | The context object. |
| chat_id | The chat 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().
| context | The context object as returned from dc_context_new(). |
| contact_id | The contact ID to check. |
| 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 given chat or any 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.
| context | The context object as returned from dc_context_new(). |
| chat_id | >0: get messages with media from this chat ID. 0: get messages with media from any chat of the currently used account. |
| 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. |
| 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.
| 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(). If set to DC_GCM_INFO_ONLY, only system messages will be returned, can be combined with DC_GCM_ADDDAYMARKER. |
| marker1before | Deprecated, set this to 0. |
| 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 e.g. 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():
| context | The context object as returned by dc_context_new(). |
| flags | A combination of flags:
|
| query_str | An optional query for filtering the list. Only chats matching this query are returned. Give NULL for no filtering. When is:unread is contained in the query, the chatlist is filtered such that only chats with unread messages show up. |
| query_id | An optional contact ID for filtering the list. Only chats including this contact ID are returned. Give 0 for no filtering. |
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 e.g. 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 e.g. 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.quota_exceeding = 0: quota is unknown or in normal range; >=80: quota is about to exceed, the value is the concrete percentage, a device message is added when that happens, however, that value may still be interesting for bots.| context | The context object. For querying system values, this can be NULL. |
| key | The key to query. |
| int dc_get_connectivity | ( | dc_context_t * | context | ) |
Get the current connectivity, i.e.
whether the device is connected to the IMAP server. One of:
We don't use exact values but ranges here so that we can split up states into multiple states in the future.
Meant as a rough overview that can be shown e.g. in the title of the main screen.
If the connectivity changes, a DC_EVENT_CONNECTIVITY_CHANGED will be emitted.
| context | The context object. |
| char * dc_get_connectivity_html | ( | dc_context_t * | context | ) |
Get an overview of the current connectivity, and possibly more statistics.
Meant to give the user more insight about the current status than the basic connectivity info returned by dc_get_connectivity(); show this e.g., if the user taps on said basic connectivity info.
If this page changes, a DC_EVENT_CONNECTIVITY_CHANGED will be emitted.
This comes as an HTML from the core so that we can easily improve it and the improvement instantly reaches all UIs.
| context | The context object. |
| dc_contact_t * dc_get_contact | ( | dc_context_t * | context, |
| uint32_t | contact_id ) |
Get a single contact object.
For a list, see e.g. dc_get_contacts().
For contact DC_CONTACT_ID_SELF (1), the function returns sth. like "Me" in the selected language and the e-mail address defined by dc_set_config().
| context | The context object. |
| contact_id | The ID of the contact to get the object for. |
| 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 e.g. to compare the fingerprints for a simple out-of-band verification.
| context | The context object. |
| contact_id | The ID of the contact to get the encryption info for. |
| 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().
| context | The context object. |
| flags | A combination of flags:
|
| query | A string to filter the list. Typically used to implement an incremental search. NULL for no filtering. |
| 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.
| context | The context object. |
| chat_id | The chat ID to get the draft for. |
| 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, such 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.
| context | The context object as created by dc_context_new(). |
Note: Use only one event emitter per context. The result of having multiple event emitters is unspecified. Currently events are broadcasted to all existing event emitters, but previous versions delivered events to only one event emitter and this behavior may change again in the future. Events emitted before creation of event emitter may or may not be available to event emitter.
| 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.
As muted archived chats are not unarchived automatically, a similar information is needed for the archive link as well: here, the number of archived chats containing fresh messages is returned.
If the specified chat is muted or the archive link, the UI should show the badge counter "less obtrusive", e.g. using "gray" instead of "red" color.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to count the messages for. |
| 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 or badge counters e.g. on the app icon. The list is already sorted and starts with the most recent fresh message.
Messages belonging to muted chats or to the contact requests are not returned; these messages should not be notified and also badge counters should not include these messages.
To get the number of fresh messages for a single chat, muted or not, use dc_get_fresh_msg_cnt().
| context | The context object as returned from dc_context_new(). |
| 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.
| context | The context object as created e.g. by dc_accounts_get_account() or dc_context_new(). |
| char * dc_get_info | ( | const 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.
| context | The context object. |
| char * dc_get_last_error | ( | dc_context_t * | context | ) |
Get last error string.
This is the same error string as logged via DC_EVENT_ERROR, however, using this function avoids race conditions if the failing function is called in another thread than dc_get_next_event().
| context | The context object. |
| 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.
| context | The context object. |
| chat_id | The chat ID to get location information for. 0 to get locations independently of the chat. |
| contact_id | The 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 | The 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 | The 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". |
Examples:
| 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()
| context | The context object. |
| msg_id | The message ID for which the message object should be created. |
| int dc_get_msg_cnt | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Get the total number of messages in a chat.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to count the messages for. |
| char * dc_get_msg_html | ( | dc_context_t * | context, |
| uint32_t | msg_id ) |
Get uncut message, if available.
Delta Chat tries to break the message in simple parts as plain text or images that are retrieved using dc_msg_get_viewtype(), dc_msg_get_text(), dc_msg_get_file() and so on. This works totally fine for Delta Chat to Delta Chat communication, however, when the counterpart uses another E-Mail-client, this has limits:
In these cases, dc_msg_has_html() returns 1 and you can ask dc_get_msg_html() for some HTML-code that shows the uncut text (which is close to the original) For simplicity, the function always returns HTML-code, this removes the need for the UI to deal with different formatting options of PLAIN-parts.
As the title of the full-message-view, you can use the subject (see dc_msg_get_subject()).
Note: The returned HTML-code may contain scripts, external images that may be misused as hidden read-receipts and so on. Taking care of these parts while maintaining compatibility with the then generated HTML-code is not easily doable, if at all. E.g. taking care of tags and attributes is not sufficient, we would have to deal with linked content (e.g. script, css), text (e.g. script-blocks) and values (e.g. javascript-protocol) as well; on this level, we have to deal with encodings, browser peculiarities and so on - and would still risk to oversee something and to break things.
To avoid starting this cat-and-mouse game, and to close this issue in a sustainable way, it is up to the UI to display the HTML-code in an appropriate sandbox environment - that may e.g. be an external browser or a WebView with scripting disabled.
| context | The context object. |
| msg_id | The message ID for which the uncut text should be loaded. |
| 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 e.g. 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).
| context | The context object. |
| msg_id | The message ID for which information should be generated. |
| dc_array_t * dc_get_next_msgs | ( | dc_context_t * | context | ) |
Returns the message IDs of all messages of any chat with a database ID higher than last_msg_id config value.
This function is intended for use by bots. Self-sent messages, device messages, messages from contact requests and muted chats are included, but messages from explicitly blocked contacts and chats are ignored.
This function may be called as a part of event loop triggered by DC_EVENT_INCOMING_MSG if you are only interested in the incoming messages. Otherwise use a separate message processing loop calling dc_wait_next_msgs() in a separate thread.
| context | The context object as returned from dc_context_new(). |
| 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 authorization.
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.
| 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) |
| int dc_get_push_state | ( | dc_context_t * | context | ) |
Get the current push notification state.
One of:
| context | The context object. |
| 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 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()
The returned text will also work as a normal https:-link, so that the QR code is useful also without Delta Chat being installed or can be passed to contacts through other channels.
| 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 protected groups as well as for normal groups. If set to 0, the Setup-Contact protocol is offered in the QR code. See https://securejoin.delta.chat/ for details about both protocols. |
| char * dc_get_securejoin_qr_svg | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Get QR code image from the QR code text generated by dc_get_securejoin_qr().
See dc_get_securejoin_qr() for details about the contained QR code.
| context | The context object. |
| chat_id | group-chat-id for secure-join or 0 for setup-contact, see dc_get_securejoin_qr() for details. |
| dc_chatlist_t * dc_get_similar_chatlist | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Returns a list of similar chats.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat for which to find similar chats. |
| char * dc_get_webxdc_status_updates | ( | dc_context_t * | context, |
| uint32_t | msg_id, | ||
| uint32_t | serial ) |
Get webxdc status updates.
The status updates may be sent by yourself or by other members using dc_send_webxdc_status_update(). In both cases, you will be informed by DC_EVENT_WEBXDC_STATUS_UPDATE whenever there is a new update.
In JS land, that would be mapped to something as:
| context | The context object. |
| msg_id | The ID of the message with the webxdc instance. |
| serial | The last known serial. Pass 0 if there are no known serials to receive all updates. |
update comes with the following properties:update.payload: equals the payload given to dc_send_webxdc_status_update()update.serial: the serial number of this update. Serials are larger 0 and newer serials have higher numbers.update.max_serial: the maximum serial currently known. If max_serial equals serial this update is the last update (until new network messages arrive).update.info: optional, short, informational message.update.summary: optional, short text, shown beside app icon. If there are no updates, an empty JSON-array is returned. | 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:
param1 encrypted with the passphrase given as param2. If param2 is NULL or empty string, the backup is not encrypted. 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 delta-chat-backup-<day>-<number>-<addr>.tar.param1 is the file (not: directory) to import. param2 is the passphrase. 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.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>.ascparam1. The last imported key is made the default keys unless its name contains the string legacy. Public keys are not imported. If param1 is a filename, import the private key from the file and make it the default.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:
Only one import-/export-progress can run at the same time. To cancel an import-/export-progress, use dc_stop_ongoing_process().
| 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 will 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. |
| 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 (e.g. dc_is_configured() returns 0).
Example:
| context | The context object. |
| dir | The directory to search backups in. |
| dc_array_t * dc_import_vcard | ( | dc_context_t * | context, |
| const char * | vcard ) |
Import a vCard.
| context | The context object. |
| vcard | vCard contents. |
| uint32_t dc_init_webxdc_integration | ( | dc_context_t * | context, |
| uint32_t | chat_id ) |
Init a Webxdc integration.
A Webxdc integration is a Webxdc showing a map, getting locations via setUpdateListener(), setting POIs via sendUpdate(); core takes eg. care of feeding locations to the Webxdc or sending the data out.
Currently, Webxdc integrations are .xdc files shipped together with the main app. Before dc_init_webxdc_integration() can be called, UI has to call dc_set_webxdc_integration() to define a .xdc file to be used as integration.
dc_init_webxdc_integration() returns a Webxdc message ID that UI can open and use mostly as usual.
Concrete behaviour and status updates depend on the integration, driven by UI needs.
There is no need to de-initialize the integration, however, unless documented otherwise, the integration is valid only as long as not re-initialized In other words, UI must not have a Webxdc with the same integration open twice.
Example:
| context | The context object. |
| chat_id | The chat to get the integration for. |
| 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:
After that, this function should be called to send the Autocrypt Setup Message. The function creates the setup message and adds it to outgoing message queue. The message is sent asynchronously.
The required setup code is returned in the following format:
The setup code should be shown to the user then:
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
| context | The context object. |
| 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.
A once successfully configured context cannot become unconfigured again; if a subsequent call to dc_configure() fails, the prior configuration is used.
However, of course, also a configuration may stop working, as e.g. the password was changed on the server. To check that use e.g. dc_get_connectivity().
| context | The context object. |
| 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.
| 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. |
| 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.
| 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. |
| 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.
The function returns immediately and the handshake runs in background, sending and receiving several messages. During the handshake, info messages are added to the chat, showing progress, success or errors.
Subsequent calls of dc_join_securejoin() will abort previous, unfinished handshakes.
See https://securejoin.delta.chat/ for details about both protocols.
| context | The context object. |
| qr | The text of the scanned QR code. Typically, the same string as given to dc_check_qr(). |
| 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().
| context | The context object. |
| addr | The e-mail address to check. |
| char * dc_make_vcard | ( | dc_context_t * | context, |
| uint32_t | contact_id ) |
Make a vCard.
| context | The context object. |
| contact_id | The ID of the contact to make the vCard of. |
| 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_NOTICED. See also dc_markseen_msgs().
| 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. |
| void dc_markseen_msgs | ( | dc_context_t * | context, |
| const uint32_t * | msg_ids, | ||
| int | msg_cnt ) |
Mark messages as presented to the user.
Typically, UIs call this function on scrolling through the message list, when the messages are presented at least for a little moment. The concrete action depends on the type of the chat and on the users settings (dc_msgs_presented() may be a better name therefore, but well. :)
mdns_enabled is set) and the internal state is changed to DC_STATE_IN_SEEN to reflect these actions.Moreover, timer is started for incoming ephemeral messages. This also happens for contact requests chats.
This function updates last_msg_id configuration value to the maximum of the current value and IDs passed to this function. Bots which mark messages as seen can rely on this side effect to avoid updating last_msg_id value manually.
One DC_EVENT_MSGS_NOTICED event is emitted per modified chat.
| 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. |
| 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().
| addr | The e-mail address to check. |
| void dc_maybe_network | ( | dc_context_t * | context | ) |
This function should be called when there is a hint that the network is available again, e.g.
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.
| context | The context as created by dc_context_new(). |
| int dc_preconfigure_keypair | ( | dc_context_t * | context, |
| 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.
| context | The context as created by dc_context_new(). |
| secret_data | ASCII armored secret key. |
| int dc_receive_backup | ( | dc_context_t * | context, |
| const char * | qr ) |
Gets a backup offered by a dc_backup_provider_t object on another device.
This function is called on a device that scanned the QR code offered by dc_backup_provider_get_qr(). Typically this is a different device than that which provides the backup.
This call will block while the backup is being transferred and only complete on success or failure. Use dc_stop_ongoing_process() to abort it early.
During execution of the job DC_EVENT_IMEX_PROGRESS is sent out to indicate state and progress. The process is finished when the event emits either 0 or 1000, 0 means it failed and 1000 means it succeeded. These events are for showing progress and informational only, success and failure is also shown in the return code of this function.
| context | The context. |
| qr | The qr code text, dc_check_qr() must have returned DC_QR_BACKUP on this text. |
| 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.
| 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. |
| int dc_resend_msgs | ( | dc_context_t * | context, |
| const uint32_t * | msg_ids, | ||
| int | msg_cnt ) |
Resend messages and make information available for newly added chat members.
Resending sends out the original message, however, recipients and webxdc-status may differ. Clients that already have the original message can still ignore the resent message as they have tracked the state by dedicated updates.
Some messages cannot be resent, eg. info-messages, drafts, already pending messages or messages that are not sent by SELF. In this case, the return value indicates an error and the error string from dc_get_last_error() should be shown to the user.
| context | The context object. |
| msg_ids | An array of uint32_t containing all message IDs that should be resend. All messages must belong to the same chat. |
| msg_cnt | The number of messages IDs in the msg_ids array. |
| void dc_save_msgs | ( | dc_context_t * | context, |
| const uint32_t * | msg_ids, | ||
| int | msg_cnt ) |
Save a copy of messages in "Saved Messages".
In contrast to forwarding messages, information as author, date and origin are preserved. The action completes locally, so "Saved Messages" do not show sending errors in case one is offline. Still, a sync message is emitted, so that other devices will save the same message, as long as not deleted before.
To check if a message was saved, use dc_msg_get_saved_msg_id(), UI may show an indicator and offer an "Unsave" instead of a "Save" button then.
The other way round, from inside the "Saved Messages" chat, UI may show the indicator and "Unsave" button checking dc_msg_get_original_msg_id() and offer a button to go the original message.
"Unsave" is done by deleting the saved message. Webxdc updates are not copied on purpose.
For performance reasons, esp. when saving lots of messages, UI should call this function from a background thread.
| context | The context object. |
| msg_ids | An array of uint32_t containing all message IDs that should be saved. |
| msg_cnt | The number of messages IDs in the msg_ids array. |
| 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.
For global search, result is limited to 1000 messages, this allows incremental search done fast. So, when getting exactly 1000 results, the result may be truncated; the UIs may display sth. as "1000+ messages found" in this case. Chat search (if a chat_id is set) is not limited.
| context | The context object as returned from dc_context_new(). |
| chat_id | The ID of the chat to search messages in. Set this to 0 for a global search. |
| query | The query to search for. |
| void dc_send_delete_request | ( | dc_context_t * | context, |
| const uint32_t * | msg_ids, | ||
| int | msg_cnt ) |
Send chat members a request to delete the given messages.
Only outgoing messages can be deleted this way and all messages must be in the same chat. No tombstone or sth. like that is left.
| context | The context object as returned from dc_context_new(). |
| msg_ids | An array of uint32_t containing all message IDs to delete. |
| msg_cnt | The number of messages IDs in the msg_ids array. |
| void dc_send_edit_request | ( | dc_context_t * | context, |
| uint32_t | msg_id, | ||
| const char * | new_text ) |
Send chat members a request to edit the given message's text.
Only outgoing messages sent by self can be edited. Edited messages should be flagged as such in the UI, see dc_msg_is_edited(). UI is informed about changes using the event DC_EVENT_MSGS_CHANGED. If the text is not changed, no event and no edit request message are sent.
| context | The context object as returned from dc_context_new(). |
| msg_id | The message ID of the message to edit. |
| new_text | The new text. This must not be NULL nor empty. |
| 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().
| context | The context object. |
| chat_id | The chat ID to enable location streaming for. |
| seconds | >0: enable location streaming for the given number of seconds; 0: disable location streaming. |
| 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 success. However, this does not imply, the message really reached the recipient - sending may be delayed e.g. due to network problems. However, from your view, you're done with the message. Sooner or later it will find its way.
Example:
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.
| context | The context object as returned from dc_context_new(). |
| chat_id | The chat ID to send the message to. |
| msg | The message object to send to the chat defined by the chat ID. On success, 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. |
| 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.
| context | The context object as returned from dc_context_new(). |
| chat_id | The chat ID to send the message to. |
| msg | The message object to send to the chat defined by the chat ID. On success, 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. |
| 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 success. However, this does not imply, the message really reached the recipient - sending may be delayed e.g. 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().
| context | The context object as returned from dc_context_new(). |
| chat_id | The chat ID to send the text message to. |
| text_to_send | Text 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. |
| 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:
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 success, 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, e.g. play a different sound.
| context | The context object. |
| chat_id | The chat to start a videochat for. |
| int dc_send_webxdc_status_update | ( | dc_context_t * | context, |
| uint32_t | msg_id, | ||
| const char * | json, | ||
| const char * | descr ) |
A webxdc instance sends a status update to its other members.
In JS land, that would be mapped to something as:
context and msg_id are not needed in JS as those are unique within a webxdc instance. See dc_get_webxdc_status_updates() for the receiving counterpart.
If the webxdc instance is a draft, the update is not sent immediately. Instead, the updates are collected and sent out in a batch when the instance is actually sent. This allows preparing webxdc instances, e.g. defining a poll with predefined answers.
Other members will be informed by DC_EVENT_WEBXDC_STATUS_UPDATE that there is a new update. You will also get the DC_EVENT_WEBXDC_STATUS_UPDATE yourself and the update you sent will also be included in dc_get_webxdc_status_updates().
| context | The context object. |
| msg_id | The ID of the message with the webxdc instance. |
| json | program-readable data, this is created in JS land as:
|
| descr | Deprecated, set to NULL |
| 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. For outgoing messages, the timer starts once the message is sent, for incoming messages, the timer starts once dc_markseen_msgs() is called.
The setting is synchronized to all clients participating in a chat.
| 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. |
| 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.
Muted chats should not sound or vibrate and should not show a visual notification in the system area. Moreover, muted chats should be excluded from global badge counter (dc_get_fresh_msgs() skips muted chats therefore) and the in-app, per-chat badge counter should use a less obtrusive color.
Sends out DC_EVENT_CHAT_MODIFIED.
| 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. |
| 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.
| 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. |
| 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()
| 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). |
| 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.
| 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 |
| 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 = Email address to use for configuration. If dc_configure() fails this is not the email address actually in use. Use configured_addr to find out the email address actually in use.configured_addr = Email address actually in use. Unless for testing, do not set this value using dc_set_config(). Instead, set addr and call dc_configure().mail_server = IMAP-server, guessed if left outmail_user = IMAP-username, guessed if left outmail_pw = IMAP-password (always needed)mail_port = IMAP-port, guessed if left outmail_security= IMAP-socket, one of DC_SOCKET, defaults to DC_SOCKET_AUTOsend_server = SMTP-server, guessed if left outsend_user = SMTP-user, guessed if left outsend_pw = SMTP-password, guessed if left outsend_port = SMTP-port, guessed if left outsend_security= SMTP-socket, one of DC_SOCKET, defaults to DC_SOCKET_AUTOserver_flags = IMAP-/SMTP-flags as a combination of DC_LP flags, guessed if left outproxy_enabled = Proxy enabled. Disabled by default.proxy_url = Proxy URL. May contain multiple URLs separated by newline, but only the first one is used.imap_certificate_checks = how to check IMAP certificates, one of the DC_CERTCK flags, defaults to DC_CERTCK_AUTO (0)smtp_certificate_checks = deprecated option, should be set to the same value as imap_certificate_checks but ignored by the new coredisplayname = Own name to use when sending messages. MUAs are allowed to spread this way e.g. using CC, defaults to emptyselfstatus = Own status to display, e.g. in e-mail footers, defaults to emptyselfavatar = 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=send and request read receipts, only send but not request if bot is setbcc_self = 0=do not send a copy of outgoing messages to self, 1=send a copy of outgoing messages to self (default). 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.sentbox_watch= 1=watch Sent-folder for changes, 0=do not watch the Sent-folder (default).mvbox_move = 1=detect chat messages, move them to the DeltaChat folder, and watch the DeltaChat folder for updates (default), 0=do not move chat-messagesonly_fetch_mvbox = 1=Do not fetch messages from folders other than the DeltaChat folder. Messages will still be fetched from the spam folder and sendbox_watch will also still be respected if enabled. 0=watch all folders normally (default)show_emails = DC_SHOW_EMAILS_OFF (0)= show direct replies to chats only, DC_SHOW_EMAILS_ACCEPTED_CONTACTS (1)= also show all mails of confirmed contacts, DC_SHOW_EMAILS_ALL (2)= also show mails of unconfirmed contacts (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 e-mails 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.bot = Set to "1" if this is a bot. Prevents adding the "Device messages" and "Saved messages" chats, adds Auto-Submitted header to outgoing messages, accepts contact requests automatically (calling dc_accept_chat() is not needed), does not cut large incoming text messages, handles existing messages the same way as new ones if fetch_existing_msgs=1.last_msg_id = database ID of the last message processed by the bot. This ID and IDs below it are guaranteed not to be returned by dc_get_next_msgs() and dc_wait_next_msgs(). The value is updated automatically when dc_markseen_msgs() is called, but the bot can also set it manually if it processed the message but does not want to mark it as seen. For most bots calling dc_markseen_msgs() is the recommended way to update this value even for self-sent messages.fetch_existing_msgs = 0=do not fetch existing messages on configure (default), 1=fetch most recent existing messages on configure. In both cases, existing recipients are added to the contact database.disable_idle = 1=disable IMAP IDLE even if the server supports it, 0=use IMAP IDLE if the server supports it. This is a developer option used for testing polling used as an IDLE fallback.download_limit = Messages up to this number of bytes are downloaded automatically. For larger messages, only the header is downloaded and a placeholder is shown. These messages can be downloaded fully using dc_download_full_msg() later. The limit is compared against raw message sizes, including headers. The actually used limit may be corrected to not mess up with non-delivery-reports or read-receipts. 0=no limit (default). Changes affect future messages only.protect_autocrypt = Enable Header Protection for Autocrypt header. This is an experimental option not compatible to other MUAs and older Delta Chat versions. 1 = enable. 0 = disable (default).gossip_period = How often to gossip Autocrypt keys in chats with multiple recipients, in seconds. 2 days by default. This is not supposed to be changed by UIs and only used for testing.verified_one_on_one_chats = Feature flag for verified 1:1 chats; the UI should set it to 1 if it supports verified 1:1 chats. Regardless of this setting, dc_chat_is_protected() returns true while the key is verified, and when the key changes, an info message is posted into the chat. 0=Nothing else happens when the key changes. 1=After the key changed, dc_chat_can_send() returns false and dc_chat_is_protection_broken() returns true until dc_accept_chat() is called.is_chatmail = 1 if the the server is a chatmail server, 0 otherwise.is_muted = Whether a context is muted by the user. Muted contexts should not sound, vibrate or show notifications. In contrast to dc_set_chat_mute_duration(), fresh message and badge counters are not changed by this setting, but should be tuned down where appropriate.private_tag = Optional tag as "Work", "Family". Meant to help profile owner to differ between profiles with similar names.ui.* = All keys prefixed by ui. can be used by the user-interfaces for system-specific purposes. The prefix should be followed by the system and maybe subsystem, e.g. ui.desktop.foo, ui.desktop.linux.bar, ui.android.foo, ui.dc40.bar, ui.bot.simplebot.baz. These keys go to backups and allow easy per-account settings when using dc_accounts_t, however, are not handled by the core otherwise.webxdc_realtime_enabled = Whether the realtime APIs should be enabled. 0 = WebXDC realtime API is disabled and behaves as noop. 1 = WebXDC realtime API is enabled (default).If you want to retrieve a value, use dc_get_config().
| context | The context object. |
| key | The option to change, see above. |
| value | The value to save for "key" |
| 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, DC_QR_LOGIN or DC_QR_WEBRTC_INSTANCE.
Internally, the function will call dc_set_config() with the appropriate keys, e.g. addr and mail_pw for DC_QR_ACCOUNT and DC_QR_LOGIN or webrtc_instance for DC_QR_WEBRTC_INSTANCE.
| context | The context object. |
| qr | The scanned QR code. |
| 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 e.g. 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.
| 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. |
| 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.
| context | The context object. |
| latitude | A 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. |
| 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.
| context | The context object. |
| stock_id | The integer ID of the stock message, one of the DC_STR constants. |
| stock_msg | The message to be used. |
| void dc_set_webxdc_integration | ( | dc_context_t * | context, |
| const char * | file ) |
Set Webxdc file as integration.
see dc_init_webxdc_integration() for more details about Webxdc integrations.
| context | The context object. |
| file | The .xdc file to use as Webxdc integration. |
| void dc_start_io | ( | dc_context_t * | context | ) |
Start job and IMAP/SMTP tasks.
If IO is already running, nothing happens.
If the context was created by the dc_accounts_t account manager, use dc_accounts_start_io() instead of this function.
| context | The context object as created by dc_context_new(). |
| void dc_stop_io | ( | dc_context_t * | context | ) |
Stop job, IMAP, SMTP and other tasks and return when they are finished.
Even if IO is not running, there may be pending tasks, so this function should always be called before releasing context to ensure clean termination of event loop.
If the context was created by the dc_accounts_t account manager, use dc_accounts_stop_io() instead of this function.
| context | The context object as created by dc_context_new(). |
| 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() 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.
| context | The context object. |
| void dc_str_unref | ( | char * | str | ) |
Release a string returned by another deltachat-core function.
| str | The string to release. If NULL is given, nothing is done. |
| dc_array_t * dc_wait_next_msgs | ( | dc_context_t * | context | ) |
Waits for notification of new messages and returns an array of new message IDs.
See the documentation for dc_get_next_msgs() for the details of return value.
This function waits for internal notification of a new message in the database and returns afterwards. Notification is also sent when I/O is started to allow processing new messages and when I/O is stopped using dc_stop_io() or dc_accounts_stop_io() to allow for manual interruption of the message processing loop. The function may return an empty array if there are no messages after notification, which may happen on start or if the message is quickly deleted after adding it to the database.
| context | The context object as returned from dc_context_new(). |
| 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 with dc_add_device_msg().
| context | The context object. |
| label | The label of the message to check. |
1.13.2