Delta Chat Core C-API
|
An object representing a single mailbox. More...
#include <mrmailbox.h>
Public Types | |
typedef uintptr_t(* | mrmailboxcb_t) (mrmailbox_t *, int event, uintptr_t data1, uintptr_t data2) |
Callback function that should be given to mrmailbox_new(). More... | |
Public Member Functions | |
mrmailbox_t * | mrmailbox_new (mrmailboxcb_t cb, void *userdata, const char *os_name) |
Create a new mailbox object. More... | |
void | mrmailbox_unref (mrmailbox_t *mailbox) |
Free a mailbox object. More... | |
void * | mrmailbox_get_userdata (mrmailbox_t *mailbox) |
Get user data associated with a mailbox object. More... | |
int | mrmailbox_open (mrmailbox_t *mailbox, const char *dbfile, const char *blobdir) |
Open mailbox database. More... | |
void | mrmailbox_close (mrmailbox_t *mailbox) |
Close mailbox database. More... | |
int | mrmailbox_is_open (const mrmailbox_t *mailbox) |
Check if the mailbox database is open. More... | |
char * | mrmailbox_get_blobdir (mrmailbox_t *mailbox) |
Get the blob directory. More... | |
int | mrmailbox_set_config (mrmailbox_t *ths, const char *key, const char *value) |
Configure the mailbox. More... | |
char * | mrmailbox_get_config (mrmailbox_t *ths, const char *key, const char *def) |
Get a configuration option. More... | |
int | mrmailbox_set_config_int (mrmailbox_t *ths, const char *key, int32_t value) |
Configure the mailbox. More... | |
int32_t | mrmailbox_get_config_int (mrmailbox_t *ths, const char *key, int32_t def) |
Get a configuration option. More... | |
char * | mrmailbox_get_info (mrmailbox_t *mailbox) |
Get information about the mailbox. More... | |
char * | mrmailbox_get_version_str (void) |
Find out the version of the Delta Chat core library. More... | |
void | mrmailbox_connect (mrmailbox_t *mailbox) |
Connect to the mailbox using the configured settings. More... | |
void | mrmailbox_disconnect (mrmailbox_t *mailbox) |
Disonnect the mailbox from the server. More... | |
void | mrmailbox_heartbeat (mrmailbox_t *ths) |
Stay alive. More... | |
mrchatlist_t * | mrmailbox_get_chatlist (mrmailbox_t *mailbox, int listflags, const char *query) |
Get a list of chats. More... | |
mrchat_t * | mrmailbox_get_chat (mrmailbox_t *mailbox, uint32_t chat_id) |
Get chat object by a chat ID. More... | |
void | mrmailbox_marknoticed_chat (mrmailbox_t *mailbox, uint32_t chat_id) |
Mark all messages in a chat as noticed. More... | |
uint32_t | mrmailbox_get_chat_id_by_contact_id (mrmailbox_t *mailbox, uint32_t contact_id) |
Check, if there is a normal chat with a given contact. More... | |
uint32_t | mrmailbox_create_chat_by_contact_id (mrmailbox_t *mailbox, uint32_t contact_id) |
Create a normal chat with a single user. More... | |
mrarray_t * | mrmailbox_get_chat_media (mrmailbox_t *mailbox, uint32_t chat_id, int msg_type, int or_msg_type) |
Returns all message IDs of the given types in a chat. More... | |
uint32_t | mrmailbox_get_next_media (mrmailbox_t *mailbox, uint32_t curr_msg_id, int dir) |
Get next/previous message of the same type. More... | |
mrarray_t * | mrmailbox_get_chat_contacts (mrmailbox_t *mailbox, uint32_t chat_id) |
Get contact IDs belonging to a chat. More... | |
mrarray_t * | mrmailbox_get_fresh_msgs (mrmailbox_t *mailbox) |
Returns the message IDs of all fresh messages of any chat. More... | |
mrarray_t * | mrmailbox_get_chat_msgs (mrmailbox_t *mailbox, uint32_t chat_id, uint32_t flags, uint32_t marker1before) |
Get all message IDs belonging to a chat. More... | |
mrarray_t * | mrmailbox_search_msgs (mrmailbox_t *mailbox, uint32_t chat_id, const char *query) |
Search messages containing the given query string. More... | |
void | mrmailbox_set_draft (mrmailbox_t *mailbox, uint32_t chat_id, const char *msg) |
Save a draft for a chat. More... | |
int | mrmailbox_get_total_msg_count (mrmailbox_t *mailbox, uint32_t chat_id) |
Get the total number of messages in a chat. More... | |
int | mrmailbox_get_fresh_msg_count (mrmailbox_t *mailbox, uint32_t chat_id) |
Get the number of fresh messages in a chat. More... | |
void | mrmailbox_archive_chat (mrmailbox_t *mailbox, uint32_t chat_id, int archive) |
Archive or unarchive a chat. More... | |
void | mrmailbox_delete_chat (mrmailbox_t *mailbox, uint32_t chat_id) |
Delete a chat. More... | |
uint32_t | mrmailbox_send_text_msg (mrmailbox_t *mailbox, uint32_t chat_id, const char *text_to_send) |
Send a simple text message a given chat. More... | |
uint32_t | mrmailbox_send_image_msg (mrmailbox_t *mailbox, uint32_t chat_id, const char *file, const char *filemime, int width, int height) |
Send an image to a chat. More... | |
uint32_t | mrmailbox_send_video_msg (mrmailbox_t *mailbox, uint32_t chat_id, const char *file, const char *filemime, int width, int height, int duration) |
Send a video to a chat. More... | |
uint32_t | mrmailbox_send_voice_msg (mrmailbox_t *mailbox, uint32_t chat_id, const char *file, const char *filemime, int duration) |
Send a voice message to a chat. More... | |
uint32_t | mrmailbox_send_audio_msg (mrmailbox_t *mailbox, uint32_t chat_id, const char *file, const char *filemime, int duration, const char *author, const char *trackname) |
Send an audio file to a chat. More... | |
uint32_t | mrmailbox_send_file_msg (mrmailbox_t *mailbox, uint32_t chat_id, const char *file, const char *filemime) |
Send a document to a chat. More... | |
uint32_t | mrmailbox_send_vcard_msg (mrmailbox_t *mailbox, uint32_t chat_id, uint32_t contact_id) |
Send foreign contact data to a chat. More... | |
uint32_t | mrmailbox_create_group_chat (mrmailbox_t *mailbox, const char *chat_name) |
Create a new group chat. More... | |
int | mrmailbox_set_chat_name (mrmailbox_t *mailbox, uint32_t chat_id, const char *new_name) |
Set group name. More... | |
int | mrmailbox_set_chat_profile_image (mrmailbox_t *mailbox, uint32_t chat_id, const char *new_image) |
Set group profile image. More... | |
int | mrmailbox_is_contact_in_chat (mrmailbox_t *mailbox, uint32_t chat_id, uint32_t contact_id) |
Check if a given contact ID is a member of a group chat. More... | |
int | mrmailbox_add_contact_to_chat (mrmailbox_t *mailbox, uint32_t chat_id, uint32_t contact_id) |
Add a member to a group. More... | |
int | mrmailbox_remove_contact_from_chat (mrmailbox_t *mailbox, uint32_t chat_id, uint32_t contact_id) |
Remove a member from a group. More... | |
uint32_t | mrmailbox_create_contact (mrmailbox_t *mailbox, const char *name, const char *addr) |
Add a single contact. More... | |
int | mrmailbox_add_address_book (mrmailbox_t *mailbox, const char *adr_book) |
Add a number of contacts. More... | |
mrarray_t * | mrmailbox_get_known_contacts (mrmailbox_t *mailbox, const char *query) |
Returns known and unblocked contacts. More... | |
mrarray_t * | mrmailbox_get_blocked_contacts (mrmailbox_t *mailbox) |
Get blocked contacts. More... | |
int | mrmailbox_get_blocked_count (mrmailbox_t *mailbox) |
Get the number of blocked contacts. More... | |
mrcontact_t * | mrmailbox_get_contact (mrmailbox_t *mailbox, uint32_t contact_id) |
Get a single contact object. More... | |
void | mrmailbox_marknoticed_contact (mrmailbox_t *mailbox, uint32_t contact_id) |
Mark all messages sent by the given contact as noticed. More... | |
void | mrmailbox_block_contact (mrmailbox_t *mailbox, uint32_t contact_id, int new_blocking) |
Block or unblock a contact. More... | |
char * | mrmailbox_get_contact_encrinfo (mrmailbox_t *mailbox, uint32_t contact_id) |
Get encryption info for a contact. More... | |
int | mrmailbox_delete_contact (mrmailbox_t *mailbox, uint32_t contact_id) |
Delete a contact. More... | |
mrmsg_t * | mrmailbox_get_msg (mrmailbox_t *mailbox, uint32_t msg_id) |
Get a single message object of the type mrmsg_t. More... | |
char * | mrmailbox_get_msg_info (mrmailbox_t *mailbox, uint32_t msg_id) |
Get an informational text for a single message. More... | |
void | mrmailbox_forward_msgs (mrmailbox_t *mailbox, const uint32_t *msg_ids, int msg_cnt, uint32_t chat_id) |
Forward messages to another chat. More... | |
void | mrmailbox_star_msgs (mrmailbox_t *mailbox, 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 | mrmailbox_delete_msgs (mrmailbox_t *mailbox, const uint32_t *msg_ids, int msg_cnt) |
Delete messages. More... | |
void | mrmailbox_markseen_msgs (mrmailbox_t *mailbox, const uint32_t *msg_ids, int msg_cnt) |
Mark a message as seen, updates the IMAP state and sends MDNs. More... | |
int | mrmailbox_configure_and_connect (mrmailbox_t *mailbox) |
Configure and connect a mailbox. More... | |
int | mrmailbox_is_configured (mrmailbox_t *mailbox) |
Check if the mailbox is already configured. More... | |
void | mrmailbox_stop_ongoing_process (mrmailbox_t *mailbox) |
Signal an ongoing process to stop. More... | |
char * | mrmailbox_initiate_key_transfer (mrmailbox_t *mailbox) |
Initiate Autocrypt Key Transfer. More... | |
int | mrmailbox_continue_key_transfer (mrmailbox_t *mailbox, uint32_t msg_id, const char *setup_code) |
Continue the Autocrypt Key Transfer on another device. More... | |
int | mrmailbox_imex (mrmailbox_t *mailbox, int what, const char *param1, const char *param2) |
Import/export things. More... | |
char * | mrmailbox_imex_has_backup (mrmailbox_t *mailbox, const char *dir_name) |
Check if there is a backup file. More... | |
int | mrmailbox_check_password (mrmailbox_t *mailbox, const char *test_pw) |
Check if the user is authorized by the given password in some way. More... | |
An object representing a single mailbox.
Each mailbox is linked to an IMAP/POP3 account and uses a separate SQLite database for offline functionality and for mailbox-related settings.
typedef uintptr_t(* mrmailboxcb_t) (mrmailbox_t *, int event, uintptr_t data1, uintptr_t data2) |
Callback function that should be given to mrmailbox_new().
mailbox | the mailbox object as returned by mrmailbox_new(). |
event | one of the MR_EVENT_* constants as defined in mrevent.h |
data1 | depends on the event parameter |
data2 | depends on the event parameter |
mrmailbox_t * mrmailbox_new | ( | mrmailboxcb_t | cb, |
void * | userdata, | ||
const char * | os_name | ||
) |
Create a new mailbox object.
After creation it is usually opened, connected and mails are fetched. After usage, the object should be deleted using mrmailbox_unref().
cb | a callback function that is called for events (update, state changes etc.) and to get some information form the client (eg. translation for a given string). See mrevent.h 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 mrmailbox_get_userdata(). |
os_name | is only for decorative use and is shown eg. in the X-Mailer: header in the form "Delta Chat <version> for <os_name>". You can give the name of the operating system and/or the used environment here. It is okay to give NULL, in this case X-Mailer: header is set to "Delta Chat <version>". |
void mrmailbox_unref | ( | mrmailbox_t * | mailbox | ) |
Free a mailbox object.
If app runs can only be terminated by a forced kill, this may be superfluous.
mailbox | the mailbox object as created by mrmailbox_new(). |
void * mrmailbox_get_userdata | ( | mrmailbox_t * | mailbox | ) |
Get user data associated with a mailbox object.
mailbox | the mailbox object as created by mrmailbox_new(). |
int mrmailbox_open | ( | mrmailbox_t * | mailbox, |
const char * | dbfile, | ||
const char * | blobdir | ||
) |
Open mailbox database.
If the given file does not exist, it is created and can be set up using mrmailbox_set_config() afterwards.
mailbox | the mailbox object as created by mrmailbox_new |
dbfile | the file to use to store the database, sth. like "~/file" won't work on all systems, if in doubt, use absolute paths. You can find the file path later in mrmailbox_t::m_dbfile |
blobdir | a directory to store the blobs in, the trailing slash is added by us, so if you want to avoid double slashes, do not add one. If you give NULL as blobdir, dbfile-blobs is used in the same directory as dbfile will be created in. You can find the path to the blob direcrory later in mrmailbox_t::m_blobdir |
void mrmailbox_close | ( | mrmailbox_t * | mailbox | ) |
Close mailbox database.
mailbox | the mailbox object as created by mrmailbox_new() |
int mrmailbox_is_open | ( | const mrmailbox_t * | mailbox | ) |
Check if the mailbox database is open.
mailbox | the mailbox object as created by mrmailbox_new(). |
char * mrmailbox_get_blobdir | ( | mrmailbox_t * | mailbox | ) |
Get the blob directory.
mailbox | the mailbox object as created by mrmailbox_new(). |
int mrmailbox_set_config | ( | mrmailbox_t * | ths, |
const char * | key, | ||
const char * | value | ||
) |
Configure the mailbox.
The configuration is handled by key=value pairs. Typical configuration options are:
ths | the mailbox object |
key | the option to change, typically one of the strings listed above |
value | the value to save for "key" |
char * mrmailbox_get_config | ( | mrmailbox_t * | ths, |
const char * | key, | ||
const char * | def | ||
) |
Get a configuration option.
The configuration option is typically set by mrmailbox_set_config() or by the library itself.
ths | the mailbox object as created by mrmmailbox_new() |
key | the key to query |
def | default value to return if "key" is unset |
int mrmailbox_set_config_int | ( | mrmailbox_t * | ths, |
const char * | key, | ||
int32_t | value | ||
) |
Configure the mailbox.
Similar to mrmailbox_set_config() but sets an integer instead of a string. If there is already a key with a string set, this is overwritten by the given integer value.
int32_t mrmailbox_get_config_int | ( | mrmailbox_t * | ths, |
const char * | key, | ||
int32_t | def | ||
) |
Get a configuration option.
Similar as mrmailbox_get_config() but gets the value as an integer instead of a string.
char * mrmailbox_get_info | ( | mrmailbox_t * | mailbox | ) |
Get information about the mailbox.
The information is returned by a multi-line string and contains information about the current configuration and the last log entries.
mailbox | Mailbox object as returned by mrmailbox_new(). |
char * mrmailbox_get_version_str | ( | void | ) |
Find out the version of the Delta Chat core library.
major.minor.revision
. The return value must be free()'d. void mrmailbox_connect | ( | mrmailbox_t * | mailbox | ) |
Connect to the mailbox using the configured settings.
We connect using IMAP-IDLE or, if this is not possible, a using pull algorithm.
mailbox | The mailbox object as created by mrmailbox_new() |
void mrmailbox_disconnect | ( | mrmailbox_t * | mailbox | ) |
Disonnect the mailbox from the server.
mailbox | The mailbox object as created by mrmailbox_new() |
void mrmailbox_heartbeat | ( | mrmailbox_t * | ths | ) |
Stay alive.
The library tries itself to stay alive. For this purpose there is an additional "heartbeat" thread that checks if the IDLE-thread is up and working. This check is done about every minute. However, depending on the operating system, this thread may be delayed or stopped, if this is the case you can force additional checks manually by just calling mrmailbox_heartbeat() about every minute. If in doubt, call this function too often, not too less :-)
mrchatlist_t * mrmailbox_get_chatlist | ( | mrmailbox_t * | mailbox, |
int | listflags, | ||
const char * | query | ||
) |
Get a list of chats.
mailbox | The mailbox object as returned by mrmailbox_new() |
listflags | A combination of flags:
|
query | An optional query for filtering the list. Only chats matching this query are returned. Give NULL for no filtering. |
mrchat_t * mrmailbox_get_chat | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id | ||
) |
Get chat object by a chat ID.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The ID of the chat to get the chat object for. |
void mrmailbox_marknoticed_chat | ( | mrmailbox_t * | mailbox, |
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. IMAP/MDNs is not done for noticed messages. See also mrmailbox_marknoticed_contact() and mrmailbox_markseen_msgs()
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The chat ID of which all messages should be marked as being noticed. |
uint32_t mrmailbox_get_chat_id_by_contact_id | ( | mrmailbox_t * | mailbox, |
uint32_t | contact_id | ||
) |
Check, if there is a normal chat with a given contact.
mailbox | The mailbox object as returned from mrmailbox_new(). |
contact_id | The contact ID to check. |
uint32_t mrmailbox_create_chat_by_contact_id | ( | mrmailbox_t * | mailbox, |
uint32_t | contact_id | ||
) |
Create a normal chat with a single user.
To create group chats, see mrmailbox_create_group_chat()
mailbox | The mailbox object as returned from mrmailbox_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. |
mrarray_t * mrmailbox_get_chat_media | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
int | msg_type, | ||
int | or_msg_type | ||
) |
Returns all message IDs of the given types in a chat.
Typically used to show a gallery. The result must be mrarray_unref()'d
mailbox | The mailbox object as returned from mrmailbox_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 MR_MSG_* constats. |
or_msg_type | Another message type to return, one of the MR_MSG_* constats. The function will return both types then. 0 if you need only one. |
uint32_t mrmailbox_get_next_media | ( | mrmailbox_t * | mailbox, |
uint32_t | curr_msg_id, | ||
int | dir | ||
) |
Get next/previous message of the same type.
Typically used to implement the "next" and "previous" buttons on a media player playing eg. voice messages.
mailbox | The mailbox object as returned from mrmailbox_new(). |
curr_msg_id | This is the current (image) message displayed. |
dir | 1=get the next (image) message, -1=get the previous one. |
mrarray_t * mrmailbox_get_chat_contacts | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id | ||
) |
Get contact IDs belonging to a chat.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | Chat ID to get the belonging contact IDs for. |
mrarray_t * mrmailbox_get_fresh_msgs | ( | mrmailbox_t * | mailbox | ) |
Returns the message IDs of all fresh messages of any chat.
Typically used for implementing notification summaries. The result must be free()'d.
mailbox | The mailbox object as returned from mrmailbox_new(). |
mrarray_t * mrmailbox_get_chat_msgs | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
uint32_t | flags, | ||
uint32_t | marker1before | ||
) |
Get all message IDs belonging to a chat.
Optionally, some special markers added to the ID-array may help to implement virtual lists.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The chat ID of which the messages IDs should be queried. |
flags | If set to MR_GCM_ADD_DAY_MARKER, the marker MR_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 MR_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. |
mrarray_t * mrmailbox_search_msgs | ( | mrmailbox_t * | mailbox, |
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 mrmsg_get_summary(), chat search results may just hilite the corresponding messages and present a prev/next button.
mailbox | The mailbox object as returned from mrmailbox_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 mrmailbox_set_draft | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | msg | ||
) |
Save a draft for a chat.
To get the draft for a given chat ID, use mrchat_t::m_draft_text
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The chat ID to save the draft for. |
msg | The message text to save as a draft. |
int mrmailbox_get_total_msg_count | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id | ||
) |
Get the total number of messages in a chat.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The ID of the chat to count the messages for. |
int mrmailbox_get_fresh_msg_count | ( | mrmailbox_t * | mailbox, |
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.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The ID of the chat to count the messages for. |
void mrmailbox_archive_chat | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
int | archive | ||
) |
Archive or unarchive a chat.
Archived chats are not included in the default chatlist returned by mrmailbox_get_chatlist(). Instead, if there are any archived chats, the pseudo-chat with the chat_id MR_CHAT_ID_ARCHIVED_LINK will be added the the end of the chatlist.
To get a list of archived chats, use mrmailbox_get_chatlist() with the flag MR_GCL_ARCHIVED_ONLY.
To find out the archived state of a given chat, use mrchat_t::m_archived
Calling this function usually results in the event MR_EVENT_MSGS_CHANGED
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The ID of the chat to archive or unarchive. |
archive | 1=archive chat, 0=unarchive chat, all other values are reserved for future use |
void mrmailbox_delete_chat | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id | ||
) |
Delete a chat.
Messages are deleted from the device and the chat database entry is deleted. After that, the event MR_EVENT_MSGS_CHANGED is posted.
Things that are not done implicitly:
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The ID of the chat to delete. |
uint32_t mrmailbox_send_text_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | text_to_send | ||
) |
Send a simple text message a given chat.
Sends the event MR_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 mrmailbox_send_image_msg().
mailbox | The mailbox object as returned from mrmailbox_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. |
uint32_t mrmailbox_send_image_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | file, | ||
const char * | filemime, | ||
int | width, | ||
int | height | ||
) |
Send an image to a chat.
Sends the event MR_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 mrmailbox_send_text_msg().
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | Chat ID to send the image to. |
file | Full path of the image file to send. The core may make a copy of the file. |
filemime | Mime type of the file to send. NULL if you don't know or don't care. |
width | Width in pixel of the file. 0 if you don't know or don't care. |
height | Width in pixel of the file. 0 if you don't know or don't care. |
uint32_t mrmailbox_send_video_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | file, | ||
const char * | filemime, | ||
int | width, | ||
int | height, | ||
int | duration | ||
) |
Send a video to a chat.
Sends the event MR_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 mrmailbox_send_image_msg().
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | Chat ID to send the video to. |
file | Full path of the video file to send. The core may make a copy of the file. |
filemime | Mime type of the file to send. NULL if you don't know or don't care. |
width | Width in video of the file, if known. 0 if you don't know or don't care. |
height | Width in video of the file, if known. 0 if you don't know or don't care. |
duration | Length of the video in milliseconds. 0 if you don't know or don't care. |
uint32_t mrmailbox_send_voice_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | file, | ||
const char * | filemime, | ||
int | duration | ||
) |
Send a voice message to a chat.
Voice messages are messages just recorded though the device microphone. For sending music or other audio data, use mrmailbox_send_audio_msg().
Sends the event MR_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.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | Chat ID to send the voice message to. |
file | Full path of the file to send. The core may make a copy of the file. |
filemime | Mime type of the file to send. NULL if you don't know or don't care. |
duration | Length of the voice message in milliseconds. 0 if you don't know or don't care. |
uint32_t mrmailbox_send_audio_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | file, | ||
const char * | filemime, | ||
int | duration, | ||
const char * | author, | ||
const char * | trackname | ||
) |
Send an audio file to a chat.
Audio messages are eg. music tracks. For voice messages just recorded though the device microphone, use mrmailbox_send_voice_msg().
Sends the event MR_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.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | Chat ID to send the audio to. |
file | Full path of the file to send. The core may make a copy of the file. |
filemime | Mime type of the file to send. NULL if you don't know or don't care. |
duration | Length of the audio in milliseconds. 0 if you don't know or don't care. |
author | Author or artist of the file. NULL if you don't know or don't care. |
trackname | Trackname or title of the file. NULL if you don't know or don't care. |
uint32_t mrmailbox_send_file_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | file, | ||
const char * | filemime | ||
) |
Send a document to a chat.
Use this function to send any document or file to a chat.
Sends the event MR_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.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | Chat ID to send the document to. |
file | Full path of the file to send. The core may make a copy of the file. |
filemime | Mime type of the file to send. NULL if you don't know or don't care. |
uint32_t mrmailbox_send_vcard_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
uint32_t | contact_id | ||
) |
Send foreign contact data to a chat.
Sends the name and the email address of another contact to a chat. The contact this may or may not be a member of the chat.
Typically used to share a contact to another member or to a group of members.
Internally, the function just creates an appropriate text message and sends it using mrmailbox_send_text_msg().
NB: The "vcard" in the function name is just an abbreviation of "visiting card" and is not related to the VCARD data format.
mailbox | The mailbox object. |
chat_id | The chat to send the message to. |
contact_id | The contact whichs data should be shared to the chat. |
uint32_t mrmailbox_create_group_chat | ( | mrmailbox_t * | mailbox, |
const char * | chat_name | ||
) |
Create a new group chat.
After creation, the group has one member with the ID MR_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 mrchat_is_unpromoted()
mailbox | Mailbox object as created by mrmailbox_new(). |
chat_name | The name of the group chat to create. The name may be changed later using mrmailbox_set_chat_name(). To find out the name of a group later, see mrchat_t::m_name |
int mrmailbox_set_chat_name | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | new_name | ||
) |
Set group name.
If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.
Sends out MR_EVENT_CHAT_MODIFIED and MR_EVENT_MSGS_CHANGED if a status message was sent.
chat_id | The chat ID to set the name for. Must be a group chat. |
new_name | New name of the group. |
mailbox | Mailbox object as created by mrmailbox_new(). |
int mrmailbox_set_chat_profile_image | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | new_image | ||
) |
Set group profile image.
If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.
Sends out MR_EVENT_CHAT_MODIFIED and MR_EVENT_MSGS_CHANGED if a status message was sent.
To find out the profile image of a chat, use mrchat_get_profile_image()
mailbox | Mailbox object as created by mrmailbox_new(). |
chat_id | The chat ID to set the image for. |
new_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). |
int mrmailbox_is_contact_in_chat | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
uint32_t | contact_id | ||
) |
Check if a given contact ID is a member of a group chat.
mailbox | Mailbox object as created by mrmailbox_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 MR_CONTACT_ID_SELF (1) here. |
int mrmailbox_add_contact_to_chat | ( | mrmailbox_t * | mailbox, |
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.
Sends out MR_EVENT_CHAT_MODIFIED and MR_EVENT_MSGS_CHANGED if a status message was sent.
mailbox | Mailbox object as created by mrmailbox_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. |
int mrmailbox_remove_contact_from_chat | ( | mrmailbox_t * | mailbox, |
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 MR_EVENT_CHAT_MODIFIED and MR_EVENT_MSGS_CHANGED if a status message was sent.
mailbox | Mailbox object as created by mrmailbox_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. |
uint32_t mrmailbox_create_contact | ( | mrmailbox_t * | mailbox, |
const char * | name, | ||
const char * | addr | ||
) |
Add a single contact.
We assume, the contact name, if any, is entered by the user and is used "as is" therefore, mr_normalize_name() is not called for the name.
To add a number of contacts, see mrmailbox_add_address_book() which is much faster for adding a bunch of addresses.
May result in a MR_EVENT_CONTACTS_CHANGED event.
mailbox | The mailbox object as created by mrmailbox_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". |
int mrmailbox_add_address_book | ( | mrmailbox_t * | mailbox, |
const char * | adr_book | ||
) |
Add a number of contacts.
Typically used to add the whole address book from the OS. As names here are typically not well formatted, we call mr_normalize_name() for each name given.
To add a single contact entered by the user, you should prefer mrmailbox_create_contact(), however, for adding a bunch of addresses, this function is much faster.
The function takes are of not overwriting names manually added or edited by mrmailbox_create_contact().
mailbox | the mailbox object as created by mrmailbox_new(). |
adr_book | A multi-line string in the format in the format Name one\nAddress one\nName two\Address two . If an email address already exists, the name is updated and the origin is increased to "manually created". |
mrarray_t * mrmailbox_get_known_contacts | ( | mrmailbox_t * | mailbox, |
const char * | query | ||
) |
Returns known and unblocked contacts.
To get information about a single contact, see mrmailbox_get_contact().
mailbox | The mailbox object as created by mrmailbox_new(). |
query | A string to filter the list. Typically used to implement an incremental search. NULL for no filtering. |
mrarray_t * mrmailbox_get_blocked_contacts | ( | mrmailbox_t * | mailbox | ) |
Get blocked contacts.
mailbox | The mailbox object as created by mrmailbox_new(). |
int mrmailbox_get_blocked_count | ( | mrmailbox_t * | mailbox | ) |
Get the number of blocked contacts.
mailbox | The mailbox object as created by mrmailbox_new(). |
mrcontact_t * mrmailbox_get_contact | ( | mrmailbox_t * | mailbox, |
uint32_t | contact_id | ||
) |
Get a single contact object.
For a list, see eg. mrmailbox_get_known_contacts().
For contact MR_CONTACT_ID_SELF (1), the function returns the name MR_STR_SELF (typically "Me" in the selected language) and the email address defined by mrmailbox_set_config().
mailbox | The mailbox object as created by mrmailbox_new(). |
contact_id | ID of the contact to get the object for. |
void mrmailbox_marknoticed_contact | ( | mrmailbox_t * | mailbox, |
uint32_t | contact_id | ||
) |
Mark all messages sent by the given contact as noticed.
See also mrmailbox_marknoticed_chat() and mrmailbox_markseen_msgs()
mailbox | The mailbox object as created by mrmmailbox_new() |
contact_id | The contact ID of which all messages should be marked as noticed. |
void mrmailbox_block_contact | ( | mrmailbox_t * | mailbox, |
uint32_t | contact_id, | ||
int | new_blocking | ||
) |
Block or unblock a contact.
May result in a MR_EVENT_CONTACTS_CHANGED event.
mailbox | The mailbox object as created by mrmailbox_new(). |
contact_id | The ID of the contact to block or unblock. |
new_blocking | 1=block contact, 0=unblock contact |
char * mrmailbox_get_contact_encrinfo | ( | mrmailbox_t * | mailbox, |
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.
mailbox | The mailbox object as created by mrmailbox_new(). |
contact_id | ID of the contact to get the encryption info for. |
int mrmailbox_delete_contact | ( | mrmailbox_t * | mailbox, |
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 MR_EVENT_CONTACTS_CHANGED event.
mailbox | The mailbox object as created by mrmailbox_new(). |
contact_id | ID of the contact to delete. |
mrmsg_t * mrmailbox_get_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | msg_id | ||
) |
Get a single message object of the type mrmsg_t.
For a list of messages in a chat, see mrmailbox_get_chat_msgs() For a list or chats, see mrmailbox_get_chatlist()
mailbox | Mailbox object as created by mrmailbox_new() |
msg_id | The message ID for which the message object should be created. |
char * mrmailbox_get_msg_info | ( | mrmailbox_t * | mailbox, |
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.
mailbox | the mailbox object as created by mrmailbox_new(). |
msg_id | the message id for which information should be generated |
void mrmailbox_forward_msgs | ( | mrmailbox_t * | mailbox, |
const uint32_t * | msg_ids, | ||
int | msg_cnt, | ||
uint32_t | chat_id | ||
) |
Forward messages to another chat.
mailbox | the mailbox object as created by mrmailbox_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. |
void mrmailbox_star_msgs | ( | mrmailbox_t * | mailbox, |
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 mrmailbox_get_chat_msgs() using the chat_id MR_CHAT_ID_STARRED.
mailbox | The mailbox object as created by mrmailbox_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 mrmailbox_delete_msgs | ( | mrmailbox_t * | mailbox, |
const uint32_t * | msg_ids, | ||
int | msg_cnt | ||
) |
Delete messages.
The messages are deleted on the current device and on the IMAP server.
mailbox | the mailbox object as created by mrmailbox_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 mrmailbox_markseen_msgs | ( | mrmailbox_t * | mailbox, |
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 mrmailbox_marknoticed_chat() and mrmailbox_marknoticed_contact()
mailbox | The mailbox 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 mrmailbox_configure_and_connect | ( | mrmailbox_t * | mailbox | ) |
Configure and connect a mailbox.
addr
and mail_pw
using mrmailbox_set_config().mailbox | the mailbox object as created by mrmailbox_new(). |
There is no need to call this every program start, the result is saved in the database. Instead, you can use mrmailbox_connect() which reuses the configuration and is much faster:
int mrmailbox_is_configured | ( | mrmailbox_t * | mailbox | ) |
Check if the mailbox is already configured.
Typically, for unconfigured mailboxes, the user is prompeted for to enter some settings and mrmailbox_configure_and_connect() is called in a thread then.
mailbox | The mailbox object as created by mrmailbox_new(). |
void mrmailbox_stop_ongoing_process | ( | mrmailbox_t * | mailbox | ) |
Signal an ongoing process to stop.
After that, mrmailbox_stop_ongoing_process() returns without waiting for the ongoing process to return.
The ongoing process will return ASAP then, however, it may still take a moment. If in doubt, the caller may also decide to kill the thread after a few seconds; eg. the process may hang in a function not under the control of the core (eg. MR_EVENT_HTTP_GET). Another reason for mrmailbox_stop_ongoing_process() not to wait is that otherwise it would be GUI-blocking and should be started in another thread then; this would make things even more complicated.
Typical ongoing processes are started by mrmailbox_configure_and_connect(), mrmailbox_initiate_key_transfer() or mrmailbox_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.
mailbox | The mailbox object. |
char * mrmailbox_initiate_key_transfer | ( | mrmailbox_t * | mailbox | ) |
Initiate Autocrypt Key Transfer.
mailbox | The mailbox object. |
Before starting the key 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 mrmailbox_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 mrmailbox_continue_key_transfer() then for setup messages identified by mrmsg_is_setupmessage().
For more details about the Autocrypt setup process, please refer to https://autocrypt.org/en/latest/level1.html#autocrypt-setup-message
int mrmailbox_continue_key_transfer | ( | mrmailbox_t * | mailbox, |
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 mrmailbox_initiate_key_transfer() and you've detected a setup message with mrmsg_is_setupmessage(), you should prompt the user for the setup code and call this function then.
You can use mrmsg_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).
mailbox | The mailbox 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 mrmailbox_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. |
int mrmailbox_imex | ( | mrmailbox_t * | mailbox, |
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
. The backup contains all contacts, chats, images and other data and device independent settings. The backup does not contain device dependent settings as ringtones or LED notification settings. The name of the backup is typically delta-chat.<day>.bak
, if more than one backup is create on a day, the format is delta-chat.<day>-<number>.bak
param1
is the file (not: directory) to import. The file is normally created by MR_IMEX_EXPORT_BACKUP and detected by mrmailbox_imex_has_backup(). Importing a backup is only possible as long as the mailbox 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>.asc
param1
. The last imported key is made the default keys unless its name contains the string legacy
. Public keys are not imported.The function may take a long time until it finishes, so it might be a good idea to start it in a separate thread. During its execution, the function sends out some events:
Only one import-/export-progress can run at the same time. To cancel an import-/export-progress, use mrmailbox_stop_ongoing_process().
mailbox | Mailbox object as created by mrmailbox_new(). |
what | One of the MR_IMEX_* constants. |
param1 | Meaning depends on the MR_IMEX_* constants. If this parameter is a directory, it should not end with a slash (otherwise you'll get double slashes when receiving MR_EVENT_IMEX_FILE_WRITTEN). Set to NULL if not used. |
param2 | Meaning depends on the MR_IMEX_* constants. Set to NULL if not used. |
char * mrmailbox_imex_has_backup | ( | mrmailbox_t * | mailbox, |
const char * | dir_name | ||
) |
Check if there is a backup file.
May only be used on fresh installations (eg. mrmailbox_is_configured() returns 0).
mailbox | Mailbox object as created by mrmailbox_new(). |
dir_name | Directory to search backups in. |
Example:
int mrmailbox_check_password | ( | mrmailbox_t * | mailbox, |
const char * | test_pw | ||
) |
Check if the user is authorized by the given password in some way.
This is to promt for the password eg. before exporting keys/backup.
mailbox | Mailbox object as created by mrmailbox_new(). |
test_pw | Password to check. |