 |
Delta Chat Core C Interface
|
|
Delta Chat Core C Interface
|
#include <deltachat.h>
Public Types | |
| typedef uintptr_t(* | dc_callback_t) (dc_context_t *context, int event, uintptr_t data1, uintptr_t data2) |
| Callback function that should be given to dc_context_new(). More... | |
Public Member Functions | |
| int | dc_add_address_book (dc_context_t *context, const char *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_check_qr (dc_context_t *context, const char *qr) |
| Check a scanned QR code. More... | |
| void | dc_close (dc_context_t *context) |
| Close context database opened by dc_open(). More... | |
| void | dc_configure (dc_context_t *context) |
| Configure a context. More... | |
| dc_context_t * | dc_context_new (dc_callback_t cb, void *userdata, const char *os_name) |
| Create a new context object. More... | |
| void | dc_context_unref (dc_context_t *context) |
| Free a context object. More... | |
| 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... | |
| void | dc_empty_server (dc_context_t *context, uint32_t flags) |
| Empty IMAP server folder: delete all messages. More... | |
| void | dc_forward_msgs (dc_context_t *context, const uint32_t *msg_ids, int msg_cnt, uint32_t chat_id) |
| Forward messages to another chat. More... | |
| char * | dc_get_blobdir (const dc_context_t *context) |
| Get the blob directory. More... | |
| int | dc_get_blocked_cnt (dc_context_t *context) |
| Get the number of blocked contacts. More... | |
| dc_array_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_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... | |
| 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... | |
| 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_get_userdata (dc_context_t *context) |
| Get user data associated with a context object. 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... | |
| void | dc_interrupt_imap_idle (dc_context_t *context) |
| Interrupt waiting for imap-jobs. More... | |
| void | dc_interrupt_mvbox_idle (dc_context_t *context) |
| Interrupt waiting for MVBOX-fetch. More... | |
| void | dc_interrupt_sentbox_idle (dc_context_t *context) |
| Interrupt waiting for messages or jobs in the SENTBOX-thread. More... | |
| void | dc_interrupt_smtp_idle (dc_context_t *context) |
| Interrupt waiting for smtp-jobs. More... | |
| int | dc_is_configured (const dc_context_t *context) |
| Check if the context is already configured. More... | |
| int | dc_is_contact_in_chat (dc_context_t *context, uint32_t chat_id, uint32_t contact_id) |
| Check if a given contact ID is a member of a group chat. More... | |
| int | dc_is_open (const dc_context_t *context) |
| Check if the context database is open. More... | |
| 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 can be called whenever there is a hint that the network is available again. More... | |
| int | dc_open (dc_context_t *context, const char *dbfile, const char *blobdir) |
| Open context database. More... | |
| void | dc_perform_imap_fetch (dc_context_t *context) |
| Fetch new messages, if any. More... | |
| void | dc_perform_imap_idle (dc_context_t *context) |
| Wait for messages or jobs. More... | |
| void | dc_perform_imap_jobs (dc_context_t *context) |
| Execute pending imap-jobs. More... | |
| void | dc_perform_mvbox_fetch (dc_context_t *context) |
| Fetch new messages from the MVBOX, if any. More... | |
| void | dc_perform_mvbox_idle (dc_context_t *context) |
| Wait for messages or jobs in the MVBOX-thread. More... | |
| void | dc_perform_mvbox_jobs (dc_context_t *context) |
| Execute pending mvbox-jobs. More... | |
| void | dc_perform_sentbox_fetch (dc_context_t *context) |
| Fetch new messages from the Sent folder, if any. More... | |
| void | dc_perform_sentbox_idle (dc_context_t *context) |
| Wait for messages or jobs in the SENTBOX-thread. More... | |
| void | dc_perform_sentbox_jobs (dc_context_t *context) |
| Execute pending sentbox-jobs. More... | |
| void | dc_perform_smtp_idle (dc_context_t *context) |
| Wait for smtp-jobs. More... | |
| void | dc_perform_smtp_jobs (dc_context_t *context) |
| Execute pending smtp-jobs. More... | |
| int | dc_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_text_msg (dc_context_t *context, uint32_t chat_id, const char *text_to_send) |
| Send a simple text message a given chat. More... | |
| int | dc_set_chat_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 containing an account. 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_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... | |
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.
| typedef uintptr_t(* dc_callback_t(dc_context_t *context, int event, uintptr_t data1, uintptr_t data2) |
Callback function that should be given to dc_context_new().
| context | The context object as returned by dc_context_new(). |
| event | one of the DC_EVENT constants |
| data1 | depends on the event parameter |
| data2 | depends on the event parameter |
| 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.
| context | the context object as created by dc_context_new(). |
| 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. |
| 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.
| context | The context as created by dc_context_new(). |
| 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 as created by dc_context_new(). |
| 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. |
Example:
| 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 as created by dc_context_new(). |
| contact_id | The ID of the contact to block or unblock. |
| block | 1=block contact, 0=unblock contact |
| 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:
| context | The context object. |
| qr | The text of the scanned QR code. |
| void dc_close | ( | dc_context_t * | context | ) |
Close context database opened by dc_open().
Before this, connections to SMTP and IMAP are closed; these connections are started automatically as needed eg. by sending for fetching messages. This function is also implicitly called by dc_context_unref(). Multiple calls to this functions are okay, the function takes care not to free objects twice.
| context | The context object as created by dc_context_new(). |
| void dc_configure | ( | dc_context_t * | context | ) |
Configure a context.
For this purpose, the function creates a job that is executed in the IMAP-thread then; this requires to call dc_perform_imap_jobs() regularly. If the context is already configured, this function will try to change the configuration.
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 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.
| context | The context object as created by dc_context_new(). |
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:
| dc_context_t * dc_context_new | ( | dc_callback_t | cb, |
| void * | userdata, | ||
| const char * | os_name | ||
| ) |
Create a new context object.
After creation it is usually opened, connected and mails are fetched.
| cb | a callback function that is called for events (update, state changes etc.) and to get some information from the client (eg. translation for a given string). See DC_EVENT for a list of possible events that may be passed to the callback.
|
| userdata | can be used by the client for any purpuse. He finds it later in dc_get_userdata(). |
| 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>". |
| 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().
| context | The context object as created by dc_context_new(). 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 | 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. |
| 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().
| 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_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.
| context | The context object as returned from dc_context_new(). |
| msg_id | The message ID to create the chat for. |
| 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 as created by dc_context_new(). |
| 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". |
| 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.
| context | The context as created by dc_context_new(). |
| 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() |
| 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.
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.
| context | The context object as created by dc_context_new(). |
| contact_id | 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 the current device and on the IMAP server.
| context | The context object as created by dc_context_new() |
| 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_empty_server | ( | dc_context_t * | context, |
| uint32_t | flags | ||
| ) |
Empty IMAP server folder: delete all messages.
| context | The context object as created by dc_context_new() |
| flags | What to delete, a combination of the DC_EMPTY flags |
| 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.
| context | The context object as created by dc_context_new() |
| 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 as created by dc_context_new(). |
| int dc_get_blocked_cnt | ( | dc_context_t * | context | ) |
Get the number of blocked contacts.
| context | The context object as created by dc_context_new(). |
| dc_array_t * dc_get_blocked_contacts | ( | dc_context_t * | context | ) |
Get blocked contacts.
| context | The context object as created by dc_context_new(). |
| dc_chat_t * dc_get_chat | ( | dc_context_t * | context, |
| uint32_t | chat_id | ||
| ) |
Get 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 contact IDs belonging to a chat.
| context | The context object as returned from dc_context_new(). |
| chat_id | Chat ID to get the belonging contact IDs for. |
| 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 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 | 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. |
| 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. |
| 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. |
| 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():
| 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. |
| 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 eg. as 1.2.3 or as 1.2.3special4sys.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.| context | The context object as created by dc_context_new(). For querying system values, this can be NULL. |
| key | The key to query. |
| 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().
| context | The context object as created by dc_context_new(). |
| contact_id | 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 eg. to compare the fingerprints for a simple out-of-band verification.
| context | The context object as created by dc_context_new(). |
| contact_id | 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 as created by dc_context_new(). |
| 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 as created by dc_context_new(). |
| chat_id | The chat ID to get the draft for. |
| 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.
| 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. The list is already sorted and starts with the most recent fresh message.
| context | The context object as returned from dc_context_new(). |
| 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.
| context | The context as created by dc_context_new(). |
| 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 | 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". |
Examples:
| 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.
| context | The context object as created by dc_context_new(). |
| msg_id | The message id, must be the id of an incoming message. |
| 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 as created by dc_context_new(). |
| 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_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).
| context | The context object as created by dc_context_new(). |
| msg_id | The message id for which information should be generated |
| 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.
| 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. |
| 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.
| context | The context object as created by dc_context_new(). |
| 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) |
| 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()
| 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. |
| void * dc_get_userdata | ( | dc_context_t * | context | ) |
Get user data associated with a context object.
| context | The context object as created by dc_context_new(). |
| void dc_imex | ( | dc_context_t * | context, |
| int | what, | ||
| const char * | param1, | ||
| const char * | param2 | ||
| ) |
Import/export things.
For this purpose, the function creates a job that is executed in the IMAP-thread then; this requires to call dc_perform_imap_jobs() regularly.
What to do is defined by the what parameter which may be one of the following:
param1. The backup contains all contacts, chats, images and other data and device independent settings. The backup does not contain device dependent settings as ringtones or LED notification settings. The name of the backup is typically delta-chat.<day>.bak, if more than one backup is create on a day, the format is delta-chat.<day>-<number>.bakparam1 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.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.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 as created by dc_context_new(). |
| 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. |
| 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:
| context | The context as created by dc_context_new(). |
| dir | Directory to search backups in. |
| 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 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:
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. |
| void dc_interrupt_imap_idle | ( | dc_context_t * | context | ) |
Interrupt waiting for imap-jobs.
If dc_perform_imap_jobs(), dc_perform_imap_fetch() and dc_perform_imap_idle() are called in a loop, calling this function causes imap-jobs to be executed and messages to be fetched.
dc_interrupt_imap_idle() does not interrupt dc_perform_imap_jobs() or dc_perform_imap_fetch(). If the imap-thread is inside one of these functions when dc_interrupt_imap_idle() is called, however, the next call of the imap-thread to dc_perform_imap_idle() is interrupted immediately.
Internally, this function is called whenever a imap-jobs should be processed (delete message, markseen etc.).
When you need to call this function just because to get jobs done after network changes, use dc_maybe_network() instead.
| context | The context as created by dc_context_new(). |
| void dc_interrupt_mvbox_idle | ( | dc_context_t * | context | ) |
Interrupt waiting for MVBOX-fetch.
dc_interrupt_mvbox_idle() does not interrupt dc_perform_mvbox_fetch(). If the MVBOX-thread is inside this function when dc_interrupt_mvbox_idle() is called, however, the next call of the MVBOX-thread to dc_perform_mvbox_idle() is interrupted immediately.
Internally, this function is called whenever a imap-jobs should be processed.
When you need to call this function just because to get jobs done after network changes, use dc_maybe_network() instead.
| context | The context as created by dc_context_new(). |
| void dc_interrupt_sentbox_idle | ( | dc_context_t * | context | ) |
Interrupt waiting for messages or jobs in the SENTBOX-thread.
| context | The context as created by dc_context_new(). |
| void dc_interrupt_smtp_idle | ( | dc_context_t * | context | ) |
Interrupt waiting for smtp-jobs.
If dc_perform_smtp_jobs() and dc_perform_smtp_idle() are called in a loop, calling this function causes jobs to be executed.
dc_interrupt_smtp_idle() does not interrupt dc_perform_smtp_jobs(). If the smtp-thread is inside this function when dc_interrupt_smtp_idle() is called, however, the next call of the smtp-thread to dc_perform_smtp_idle() is interrupted immediately.
Internally, this function is called whenever a message is to be sent.
When you need to call this function just because to get jobs done after network changes, use dc_maybe_network() instead.
| context | The context as created by dc_context_new(). |
| 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.
| context | The context object as created by dc_context_new(). |
| 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 as created by dc_context_new(). |
| 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_open | ( | const dc_context_t * | context | ) |
Check if the context database is open.
| context | The context object as created by dc_context_new(). |
| 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.
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().
See https://countermitm.readthedocs.io/en/latest/new.html 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.
Known and unblocked contacts will be returned by dc_get_contacts().
To validate an e-mail address independently of the contact database use dc_may_be_valid_addr().
| context | The context object as created by dc_context_new(). |
| addr | The e-mail-address to check. |
| void dc_marknoticed_all_chats | ( | dc_context_t * | context | ) |
Same as dc_marknoticed_chat() but for all chats.
| context | The context object as returned from dc_context_new(). |
| 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().
| 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_marknoticed_contact | ( | dc_context_t * | context, |
| uint32_t | contact_id | ||
| ) |
Mark all messages sent by the given contact as noticed.
See also dc_marknoticed_chat() and dc_markseen_msgs()
Calling this function usually results in the event DC_EVENT_MSGS_CHANGED.
| context | The context object as created by dc_context_new() |
| contact_id | The contact ID of which all messages should be marked as noticed. |
| 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()
| 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 can be called whenever there is a hint that the network is available again.
The library will try to send pending messages out.
| context | The context as created by dc_context_new(). |
| int dc_open | ( | dc_context_t * | context, |
| const char * | dbfile, | ||
| const char * | blobdir | ||
| ) |
Open context database.
If the given file does not exist, it is created and can be set up using dc_set_config() afterwards.
| context | The context object as created by dc_context_new(). |
| dbfile | The file to use to store the database, something like ~/file won't work on all systems, if in doubt, 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. |
| void dc_perform_imap_fetch | ( | dc_context_t * | context | ) |
Fetch new messages, if any.
This function and dc_perform_imap_jobs() and dc_perform_imap_idle() must be called from the same thread, typically in a loop.
See dc_perform_imap_jobs() for an example.
| context | The context as created by dc_context_new(). |
| void dc_perform_imap_idle | ( | dc_context_t * | context | ) |
Wait for messages or jobs.
This function and dc_perform_imap_jobs() and dc_perform_imap_fetch() must be called from the same thread, typically in a loop.
You should call this function directly after calling dc_perform_imap_fetch().
See dc_perform_imap_jobs() for an example.
| context | The context as created by dc_context_new(). |
| void dc_perform_imap_jobs | ( | dc_context_t * | context | ) |
Execute pending imap-jobs.
This function and dc_perform_imap_fetch() and dc_perform_imap_idle() must be called from the same thread, typically in a loop.
Example:
void* imap_thread_func(void* context)
{
while (true) {
dc_perform_imap_jobs(context);
dc_perform_imap_fetch(context);
dc_perform_imap_idle(context);
}
}
// start imap-thread that runs forever
pthread_t imap_thread;
pthread_create(&imap_thread, NULL, imap_thread_func, context);
... program runs ...
// network becomes available again -
// the interrupt causes dc_perform_imap_idle() in the thread above
// to return so that jobs are executed and messages are fetched.
dc_maybe_network(context);
| context | The context as created by dc_context_new(). |
| void dc_perform_mvbox_fetch | ( | dc_context_t * | context | ) |
Fetch new messages from the MVBOX, if any.
The MVBOX is a folder on the account where chat messages are moved to. The moving is done to not disturb shared accounts that are used by both, Delta Chat and a classical MUA.
| context | The context as created by dc_context_new(). |
| void dc_perform_mvbox_idle | ( | dc_context_t * | context | ) |
Wait for messages or jobs in the MVBOX-thread.
This function and dc_perform_mvbox_fetch(). must be called from the same thread, typically in a loop.
You should call this function directly after calling dc_perform_mvbox_fetch().
See dc_perform_mvbox_fetch() for an example.
| context | The context as created by dc_context_new(). |
| void dc_perform_mvbox_jobs | ( | dc_context_t * | context | ) |
Execute pending mvbox-jobs.
This function and dc_perform_mvbox_fetch() and dc_perform_mvbox_idle() must be called from the same thread, typically in a loop.
Example:
void* mvbox_thread_func(void* context)
{
while (true) {
dc_perform_mvbox_jobs(context);
dc_perform_mvbox_fetch(context);
dc_perform_mvbox_idle(context);
}
}
// start mvbox-thread that runs forever
pthread_t mvbox_thread;
pthread_create(&mvbox_thread, NULL, mvbox_thread_func, context);
... program runs ...
// network becomes available again -
// the interrupt causes dc_perform_mvbox_idle() in the thread above
// to return so that jobs are executed and messages are fetched.
dc_maybe_network(context);
| context | The context as created by dc_context_new(). |
| void dc_perform_sentbox_fetch | ( | dc_context_t * | context | ) |
Fetch new messages from the Sent folder, if any.
This function and dc_perform_sentbox_idle() must be called from the same thread, typically in a loop.
| context | The context as created by dc_context_new(). |
| void dc_perform_sentbox_idle | ( | dc_context_t * | context | ) |
Wait for messages or jobs in the SENTBOX-thread.
This function and dc_perform_sentbox_fetch() must be called from the same thread, typically in a loop.
| context | The context as created by dc_context_new(). |
| void dc_perform_sentbox_jobs | ( | dc_context_t * | context | ) |
Execute pending sentbox-jobs.
This function and dc_perform_sentbox_fetch() and dc_perform_sentbox_idle() must be called from the same thread, typically in a loop.
Example:
void* sentbox_thread_func(void* context)
{
while (true) {
dc_perform_sentbox_jobs(context);
dc_perform_sentbox_fetch(context);
dc_perform_sentbox_idle(context);
}
}
// start sentbox-thread that runs forever
pthread_t sentbox_thread;
pthread_create(&sentbox_thread, NULL, sentbox_thread_func, context);
... program runs ...
// network becomes available again -
// the interrupt causes dc_perform_sentbox_idle() in the thread above
// to return so that jobs are executed and messages are fetched.
dc_maybe_network(context);
| context | The context as created by dc_context_new(). |
| void dc_perform_smtp_idle | ( | dc_context_t * | context | ) |
Wait for smtp-jobs.
This function and dc_perform_smtp_jobs() must be called from the same thread, typically in a loop.
See dc_interrupt_smtp_idle() for an example.
| context | The context as created by dc_context_new(). |
| void dc_perform_smtp_jobs | ( | dc_context_t * | context | ) |
Execute pending smtp-jobs.
This function and dc_perform_smtp_idle() must be called from the same thread, typically in a loop.
Example:
void* smtp_thread_func(void* context)
{
while (true) {
dc_perform_smtp_jobs(context);
dc_perform_smtp_idle(context);
}
}
// start smtp-thread that runs forever
pthread_t smtp_thread;
pthread_create(&smtp_thread, NULL, smtp_thread_func, context);
... program runs ...
// network becomes available again -
// the interrupt causes dc_perform_smtp_idle() in the thread above
// to return so that jobs are executed
dc_maybe_network(context);
| context | The context as created by dc_context_new(). |
| 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.
| 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. |
| 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:
| 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. |
| 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 as created by dc_context_new(). |
| 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. |
| 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.
| 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. |
| 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 | 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 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:
| 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. |
| uint32_t dc_send_text_msg | ( | dc_context_t * | context, |
| uint32_t | chat_id, | ||
| const char * | text_to_send | ||
| ) |
Send a simple text message a given chat.
Sends the event DC_EVENT_MSGS_CHANGED on succcess. However, this does not imply, the message really reached the recipient - sending may be delayed eg. due to network problems. However, from your view, you're done with the message. Sooner or later it will find its way.
See also dc_send_msg().
| context | The context object as returned from dc_context_new(). |
| chat_id | 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. |
| int dc_set_chat_mute_duration | ( | dc_context_t * | context, |
| uint32_t | chat_id, | ||
| int64_t | duration | ||
| ) |
Set mute duration of a chat.
This value can be checked by the ui upon receiving a new message to decide whether it should trigger an notification.
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 as created by dc_context_new(). |
| 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 as created by dc_context_new(). |
| 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 as created by dc_context_new(). |
| chat_id | The chat ID to set the image for. |
| image | Full path of the image to use as the group image. If you pass NULL here, the group image is deleted (for promoted groups, all members are informed about this change anyway). |
| 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 = address to display (always needed)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 outsend_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 outserver_flags = IMAP-/SMTP-flags as a combination of DC_LP flags, guessed if left outimap_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 emptyselfstatus = Own status to display eg. in email footers, defaults to a standard textselfavatar = File containing avatar. Will be copied to blob directory. NULL to remove the avatar. It is planned for future versions to send this image together with the next messages.e2ee_enabled = 0=no end-to-end-encryption, 1=prefer end-to-end-encryption (default)mdns_enabled = 0=do not send or request read receipts, 1=send and request read receipts (default)inbox_watch = 1=watch INBOX-folder for changes (default), 0=do not watch the INBOX-foldersentbox_watch= 1=watch Sent-folder for changes (default), 0=do not watch the Sent-foldermvbox_watch = 1=watch DeltaChat-folder for changes (default), 0=do not watch the DeltaChat-foldermvbox_move = 1=heuristically detect chat-messages and move them to the DeltaChat-folder, 0=do not move chat-messagesshow_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 keypairsave_mime_headers = 1=save mime headers and make dc_get_mime_headers() work for subsequent calls, 0=do not save mime headers (default)If you want to retrieve a value, use dc_get_config().
| 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 containing an account.
Before this function is called, dc_check_qr() should confirm the type of the QR code is DC_QR_ACCOUNT.
Internally, the function will call dc_set_config() at least with the keys addr and mail_pw.
| context | The context object |
| qr | 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 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.
| context | The context as created by dc_context_new(). |
| 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. |
| 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 | 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 (DC_STR_*) |
| stock_msg | the message to be used |
| 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.
| context | The context object as created by dc_context_new() |
| 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 |
| 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.
| context | The context object. |
| void dc_str_unref | ( | char * | str | ) |
Release a string returned by another deltachat-core function.
| str | The string to release. |
| 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).
| context | The context as created by 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 dc_add_device_msg().
| context | The context as created by dc_context_new(). |
| label | Label of the message to check. |
1.8.17