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... | |
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 a given mailbox database is open. 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 a chat object of type mrchat_t by a chat_id. More... | |
void | mrmailbox_marknoticed_chat (mrmailbox_t *mailbox, uint32_t chat_id) |
Mark all message 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... | |
carray * | 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) |
Returns all message IDs of the given types in a chat. More... | |
carray * | mrmailbox_get_chat_contacts (mrmailbox_t *mailbox, uint32_t chat_id) |
Get contact IDs belonging to a chat. More... | |
carray * | mrmailbox_get_fresh_msgs (mrmailbox_t *mailbox) |
Returns the message IDs of all fresh messages of any chat. More... | |
carray * | 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... | |
carray * | 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 to the given chat. More... | |
uint32_t | mrmailbox_send_msg (mrmailbox_t *mailbox, uint32_t chat_id, mrmsg_t *msg) |
save message in database and send it, the given message object is not unref'd by the function but some fields are set up! 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_image (mrmailbox_t *mailbox, uint32_t chat_id, const char *new_image) |
Set group 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... | |
carray * | mrmailbox_get_known_contacts (mrmailbox_t *mailbox, const char *query) |
Returns known and unblocked contacts. More... | |
carray * | 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 send 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. 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 a list of 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 a list of 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... | |
void | mrmailbox_configure_cancel (mrmailbox_t *mailbox) |
Signal the configure-process to stop. More... | |
int | mrmailbox_is_configured (mrmailbox_t *mailbox) |
Check if the mailbox is already configured. More... | |
char * | mrmailbox_imex_has_backup (mrmailbox_t *mailbox, const char *dir_name) |
Check if there is a backup file. More... | |
void | mrmailbox_imex (mrmailbox_t *mailbox, int what, const char *param1, const char *setup_code) |
Import/export things. 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... | |
char * | mrmailbox_create_setup_code (mrmailbox_t *mailbox) |
Create random setup code. More... | |
Public Attributes | |
void * | m_userdata |
the same pointer as given to mrmailbox_new(), may be used by the caller for any purpose | |
char * | m_dbfile |
the database file in file. More... | |
char * | m_blobdir |
full path of the blob directory in use. 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 |
int mrmailbox_add_address_book | ( | mrmailbox_t * | mailbox, |
const char * | adr_book | ||
) |
Add a number of contacts.
The contacts must be added as
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". |
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 message that is sent automatically by this function.
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. |
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.
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 |
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_BLOCKING_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 |
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. |
void mrmailbox_close | ( | mrmailbox_t * | mailbox | ) |
Close mailbox database.
mailbox | the mailbox object as created by mrmailbox_new() |
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(). |
void mrmailbox_configure_cancel | ( | mrmailbox_t * | mailbox | ) |
Signal the configure-process to stop.
After that, mrmailbox_configure_cancel() returns without waiting for mrmailbox_configure_and_connect() to return.
mrmailbox_configure_and_connect() will return ASAP then, however, it may still take a moment. If in doubt, the caller may also decide the kill the thread after a few seconds; eg. the configuration process may hang in a function not under the control of the core (eg. MR_EVENT_HTTP_GET). Another reason for mrmailbox_configure_cancel() 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.
mailbox | The mailbox object as created by mrmailbox_new() |
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() |
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. |
uint32_t mrmailbox_create_contact | ( | mrmailbox_t * | mailbox, |
const char * | name, | ||
const char * | addr | ||
) |
Add a single contact.
and return the ID.
mailbox | The mailbox object as created by mrmailbox_new(). |
name | Name of the contact to add. |
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 mrmailbox_create_group_chat | ( | mrmailbox_t * | mailbox, |
const char * | chat_name | ||
) |
Create a new group chat.
After creation, the groups 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 send 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.
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(). |
char * mrmailbox_create_setup_code | ( | mrmailbox_t * | mailbox | ) |
Create random setup code.
The created "Autocrypt Level 1" setup code has the following form:
Linebreaks and spaces are not added to the setup code, but the "-" are. Should be given to mrmailbox_imex() for encryption, should be wiped and free()'d after usage.
mailbox | Mailbox object as created by mrmailbox_new(). |
void mrmailbox_delete_chat | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id | ||
) |
Delete a chat:
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The ID of the chat to delete. |
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 used. In this case, the contact can be blocked.
mailbox | The mailbox object as created by mrmailbox_new(). |
contact_id | ID of the contact to delete. |
void mrmailbox_delete_msgs | ( | mrmailbox_t * | mailbox, |
const uint32_t * | msg_ids, | ||
int | msg_cnt | ||
) |
Delete a list of 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_disconnect | ( | mrmailbox_t * | mailbox | ) |
Disonnect the mailbox from the server.
mailbox | The mailbox object as created by mrmailbox_new() |
void mrmailbox_forward_msgs | ( | mrmailbox_t * | mailbox, |
const uint32_t * | msg_ids, | ||
int | msg_cnt, | ||
uint32_t | chat_id | ||
) |
Forward a list of 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. |
carray * 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(). |
mrchat_t * mrmailbox_get_chat | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id | ||
) |
Get a chat object of type mrchat_t by a chat_id.
To access the mrchat_t object, see mrchat.h The result must be unref'd using mrchat_unref().
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | The ID of the chat to get the chat object for. |
carray * 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. |
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. |
carray * 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 carray_free()'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. |
carray * 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. |
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. |
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 |
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.
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().
mailbox | The mailbox object as created by mrmailbox_new(). |
contact_id | ID of the contact to get the object for. |
char * mrmailbox_get_contact_encrinfo | ( | mrmailbox_t * | mailbox, |
uint32_t | contact_id | ||
) |
Get encryption info.
Get a multi-line encryption info, containing your fingerprint and the fingerprint of the contact, used eg. to compare the fingerprints.
mailbox | The mailbox object as created by mrmailbox_new(). |
contact_id | ID of the contact to get the encryption info 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. |
carray * 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(). |
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(). |
carray * 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. |
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 |
uint32_t mrmailbox_get_next_media | ( | mrmailbox_t * | mailbox, |
uint32_t | curr_msg_id, | ||
int | dir | ||
) |
Returns all message IDs of the given types in a chat.
Typically used to show a gallery. The result must be carray_free()'d
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. |
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. |
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_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 :-)
void mrmailbox_imex | ( | mrmailbox_t * | mailbox, |
int | what, | ||
const char * | param1, | ||
const char * | setup_code | ||
) |
Import/export things.
mrmailbox_imex() imports and exports export keys, backup etc. Function, sends MR_EVENT_IMEX_* events. To avoid double slashes, the given directory should not end with a slash. what to export is defined by a MR_IMEX_* constant.
mailbox | Mailbox object as created by mrmailbox_new(). |
what | One of the MR_IMEX_* constants. |
param1 | Meaning depends on the MR_IMEX_* constants. |
setup_code | Setup-code to encrypt/decrypt data. |
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 (mrmailbox_is_configured() returns 0).
mailbox | Mailbox object as created by mrmailbox_new(). |
dir_name | Directory to search backups in. |
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 with them.
mailbox | The mailbox object as created by mrmailbox_new() |
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_is_open | ( | const mrmailbox_t * | mailbox | ) |
Check if a given mailbox database is open.
mailbox | the mailbox object as created by mrmailbox_new(). |
void mrmailbox_marknoticed_chat | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id | ||
) |
Mark all message 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. |
void mrmailbox_marknoticed_contact | ( | mrmailbox_t * | mailbox, |
uint32_t | contact_id | ||
) |
Mark all messages send 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_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. |
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 <osName>" |
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 |
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. |
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 message that is sent automatically by this function.
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. |
carray * 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. |
uint32_t mrmailbox_send_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
mrmsg_t * | msg | ||
) |
save message in database and send it, the given message object is not unref'd by the function but some fields are set up!
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 message to. |
msg | Message object to send to the chat defined by the chat ID. The function does not take ownership of the object, so you have to free it using mrmsg_unref() as usual. |
uint32_t mrmailbox_send_text_msg | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | text_to_send | ||
) |
Send a simple text message to the 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.
mailbox | The mailbox object as returned from mrmailbox_new(). |
chat_id | Chat ID to send the message to. |
text_to_send | Text to send to the chat defined by the chat ID. |
int mrmailbox_set_chat_image | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | new_image | ||
) |
Set group image.
If the group is already promoted (any message was sent to the group), all group members are informed by a special message that is sent automatically by this function.
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_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 message that is sent automatically by this function.
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_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" |
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.
void mrmailbox_set_draft | ( | mrmailbox_t * | mailbox, |
uint32_t | chat_id, | ||
const char * | msg | ||
) |
Save a draft for a chat.
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. |
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_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(). |
char* mrmailbox_t::m_blobdir |
full path of the blob directory in use.
char* mrmailbox_t::m_dbfile |
the database file in file.