Delta Chat Core C-API
Public Types | Public Member Functions | List of all members
mrmailbox_t Class Reference

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_tmrmailbox_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_tmrmailbox_get_chatlist (mrmailbox_t *mailbox, int listflags, const char *query)
 Get a list of chats. More...
 
mrchat_tmrmailbox_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_tmrmailbox_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_tmrmailbox_get_chat_contacts (mrmailbox_t *mailbox, uint32_t chat_id)
 Get contact IDs belonging to a chat. More...
 
mrarray_tmrmailbox_get_fresh_msgs (mrmailbox_t *mailbox)
 Returns the message IDs of all fresh messages of any chat. More...
 
mrarray_tmrmailbox_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_tmrmailbox_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_tmrmailbox_get_known_contacts (mrmailbox_t *mailbox, const char *query)
 Returns known and unblocked contacts. More...
 
mrarray_tmrmailbox_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_tmrmailbox_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_tmrmailbox_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...
 

Detailed Description

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.

Member Typedef Documentation

typedef uintptr_t(* mrmailboxcb_t) (mrmailbox_t *, int event, uintptr_t data1, uintptr_t data2)

Callback function that should be given to mrmailbox_new().

Parameters
mailboxthe mailbox object as returned by mrmailbox_new().
eventone of the MR_EVENT_* constants as defined in mrevent.h
data1depends on the event parameter
data2depends on the event parameter
Returns
return 0 unless stated otherwise in the event parameter documentation

Member Function Documentation

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

Parameters
cba 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.
  • The callback MAY be called from any thread, not only the main/GUI thread!
  • The callback MUST NOT call any mrmailbox_* and related functions unless stated otherwise!
  • The callback SHOULD return fast, for GUI updates etc. you should post yourself an asynchronous message to your GUI thread, if needed.
  • If not mentioned otherweise, the callback should return 0.
userdatacan be used by the client for any purpuse. He finds it later in mrmailbox_get_userdata().
os_nameis 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>".
Returns
a mailbox object with some public members the object must be passed to the other mailbox functions and the object must be freed using mrmailbox_unref() after usage.
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.

Parameters
mailboxthe mailbox object as created by mrmailbox_new().
Returns
none
void * mrmailbox_get_userdata ( mrmailbox_t mailbox)

Get user data associated with a mailbox object.

Parameters
mailboxthe mailbox object as created by mrmailbox_new().
Returns
User data, this is the second parameter given to 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.

Parameters
mailboxthe mailbox object as created by mrmailbox_new
dbfilethe 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
blobdira 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
Returns
1 on success, 0 on failure
void mrmailbox_close ( mrmailbox_t mailbox)

Close mailbox database.

Parameters
mailboxthe mailbox object as created by mrmailbox_new()
Returns
none
int mrmailbox_is_open ( const mrmailbox_t mailbox)

Check if the mailbox database is open.

Parameters
mailboxthe mailbox object as created by mrmailbox_new().
Returns
0=mailbox is not open, 1=mailbox is open.
char * mrmailbox_get_blobdir ( mrmailbox_t mailbox)

Get the blob directory.

Parameters
mailboxthe mailbox object as created by mrmailbox_new().
Returns
Blob directory associated with the mailbox object, empty string if unset or on errors. NULL is never returned. The returned string must be free()'d.
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:

  • addr = address to display (needed)
  • mail_server = IMAP-server, guessed if left out
  • mail_user = IMAP-username, guessed if left out
  • mail_pw = IMAP-password (needed)
  • mail_port = IMAP-port, guessed if left out
  • send_server = SMTP-server, guessed if left out
  • send_user = SMTP-user, guessed if left out
  • send_pw = SMTP-password, guessed if left out
  • send_port = SMTP-port, guessed if left out
  • server_flags = IMAP-/SMTP-flags, guessed if left out
  • displayname = Own name to use when sending messages. MUAs are allowed to spread this way eg. using CC, defaults to empty
  • selfstatus = Own status to display eg. in email footers, defaults to a standard text
  • e2ee_enabled = 0=no e2ee, 1=prefer encryption (default)
Parameters
thsthe mailbox object
keythe option to change, typically one of the strings listed above
valuethe value to save for "key"
Returns
0=failure, 1=success
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.

Parameters
thsthe mailbox object as created by mrmmailbox_new()
keythe key to query
defdefault value to return if "key" is unset
Returns
Returns current value of "key", if "key" is unset, "def" is returned (which may be NULL) If the returned values is not NULL, the return value must be free()'d,
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.

Parameters
mailboxMailbox object as returned by mrmailbox_new().
Returns
String which must be free()'d after usage. Never returns NULL.
char * mrmailbox_get_version_str ( void  )

Find out the version of the Delta Chat core library.

Returns
String with version number as 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.

Parameters
mailboxThe mailbox object as created by mrmailbox_new()
Returns
None
void mrmailbox_disconnect ( mrmailbox_t mailbox)

Disonnect the mailbox from the server.

Parameters
mailboxThe mailbox object as created by mrmailbox_new()
Returns
None
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.

Parameters
mailboxThe mailbox object as returned by mrmailbox_new()
listflagsA combination of flags:
  • if the flag MR_GCL_ARCHIVED_ONLY is set, only archived chats are returned. if MR_GCL_ARCHIVED_ONLY is not set, only unarchived chats are returned and the pseudo-chat MR_CHAT_ID_ARCHIVED_LINK is added if there are any archived chats
  • if the flag MR_GCL_NO_SPECIALS is set, deaddrop and archive link are not added to the list (may be used eg. for selecting chats on forwarding, the flag is F not needed when MR_GCL_ARCHIVED_ONLY is already set)
queryAn optional query for filtering the list. Only chats matching this query are returned. Give NULL for no filtering.
Returns
A chatlist as an mrchatlist_t object. Must be freed using mrchatlist_unref() when no longer used
mrchat_t * mrmailbox_get_chat ( mrmailbox_t mailbox,
uint32_t  chat_id 
)

Get chat object by a chat ID.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe ID of the chat to get the chat object for.
Returns
A chat object of the type mrchat_t, must be freed using mrchat_unref() when done.
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()

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe chat ID of which all messages should be marked as being noticed.
Returns
None.
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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
contact_idThe contact ID to check.
Returns
If there is a normal chat with the given contact_id, this chat_id is returned. If there is no normal chat with the contact_id, the function returns 0.
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()

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
contact_idThe contact ID to create the chat for. If there is already a chat with this contact, the already existing ID is returned.
Returns
The created or reused chat ID on success. 0 on errors.
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

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe chat ID to get all messages with media from.
msg_typeSpecify a message type to query here, one of the MR_MSG_* constats.
or_msg_typeAnother message type to return, one of the MR_MSG_* constats. The function will return both types then. 0 if you need only one.
Returns
An array with messages from the given chat ID that have the wanted message types.
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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
curr_msg_idThis is the current (image) message displayed.
dir1=get the next (image) message, -1=get the previous one.
Returns
Returns the message ID that should be played next. The returned message is in the same chat as the given one and has the same type. Typically, this result is passed again to mrmailbox_get_next_media() later on the next swipe. If there is not next/previous message, the function returns 0.
mrarray_t * mrmailbox_get_chat_contacts ( mrmailbox_t mailbox,
uint32_t  chat_id 
)

Get contact IDs belonging to a chat.

  • for normal chats, the function always returns exactly one contact, MR_CONTACT_ID_SELF is not returned.
  • for group chats all members are returned, MR_CONTACT_ID_SELF is returned explicitly as it may happen that oneself gets removed from a still existing group
  • for the deaddrop, all contacts are returned, MR_CONTACT_ID_SELF is not added
Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idChat ID to get the belonging contact IDs for.
Returns
an array of contact IDs belonging to the chat; must be freed using mrarray_unref() when done.
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.

Parameters
mailboxThe 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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe chat ID of which the messages IDs should be queried.
flagsIf 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.
marker1beforeAn 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.
Returns
Array of message IDs, must be mrarray_unref()'d when no longer used.
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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idID of the chat to search messages in. Set this to 0 for a global search.
queryThe query to search for.
Returns
An array of message IDs. Must be freed using mrarray_unref() when no longer needed. If nothing can be found, the function returns NULL.
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

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe chat ID to save the draft for.
msgThe message text to save as a draft.
Returns
None.
int mrmailbox_get_total_msg_count ( mrmailbox_t mailbox,
uint32_t  chat_id 
)

Get the total number of messages in a chat.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe ID of the chat to count the messages for.
Returns
Number of total messages in the given chat. 0 for errors or empty chats.
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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe ID of the chat to count the messages for.
Returns
Number of fresh messages in the given chat. 0 for errors or if there are no fresh messages.
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

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe ID of the chat to archive or unarchive.
archive1=archive chat, 0=unarchive chat, all other values are reserved for future use
Returns
None
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:

  • Messages are not deleted from the server.
  • The chat or the contact is not blocked, so new messages from the user/the group may appear and the user may create the chat again.
  • Groups are not left - this would be unexpected as deleting a normal chat also does not prevent new mails from arriving (another argument is, that leaving a group requires sending a message to all group members - esp. for groups not used for a longer time, this is really unexpected when deletion results in contacting all members again. To leave a chat explicitly, use mrmailbox_remove_contact_from_chat() with chat_id=MR_CONTACT_ID_SELF)
Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idThe ID of the chat to delete.
Returns
None
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().

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idChat ID to send the text message to.
text_to_sendText to send to the chat defined by the chat ID.
Returns
The ID of the message that is about being sent.
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().

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idChat ID to send the image to.
fileFull path of the image file to send. The core may make a copy of the file.
filemimeMime type of the file to send. NULL if you don't know or don't care.
widthWidth in pixel of the file. 0 if you don't know or don't care.
heightWidth in pixel of the file. 0 if you don't know or don't care.
Returns
The ID of the message that is about being sent.
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().

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idChat ID to send the video to.
fileFull path of the video file to send. The core may make a copy of the file.
filemimeMime type of the file to send. NULL if you don't know or don't care.
widthWidth in video of the file, if known. 0 if you don't know or don't care.
heightWidth in video of the file, if known. 0 if you don't know or don't care.
durationLength of the video in milliseconds. 0 if you don't know or don't care.
Returns
The ID of the message that is about being sent.
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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idChat ID to send the voice message to.
fileFull path of the file to send. The core may make a copy of the file.
filemimeMime type of the file to send. NULL if you don't know or don't care.
durationLength of the voice message in milliseconds. 0 if you don't know or don't care.
Returns
The ID of the message that is about being sent.
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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idChat ID to send the audio to.
fileFull path of the file to send. The core may make a copy of the file.
filemimeMime type of the file to send. NULL if you don't know or don't care.
durationLength of the audio in milliseconds. 0 if you don't know or don't care.
authorAuthor or artist of the file. NULL if you don't know or don't care.
tracknameTrackname or title of the file. NULL if you don't know or don't care.
Returns
The ID of the message that is about being sent.
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.

Parameters
mailboxThe mailbox object as returned from mrmailbox_new().
chat_idChat ID to send the document to.
fileFull path of the file to send. The core may make a copy of the file.
filemimeMime type of the file to send. NULL if you don't know or don't care.
Returns
The ID of the message that is about being sent.
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.

Parameters
mailboxThe mailbox object.
chat_idThe chat to send the message to.
contact_idThe contact whichs data should be shared to the chat.
Returns
Returns the ID of the message sent.
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()

Parameters
mailboxMailbox object as created by mrmailbox_new().
chat_nameThe 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
Returns
The chat ID of the new group chat, 0 on errors.
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.

Parameters
chat_idThe chat ID to set the name for. Must be a group chat.
new_nameNew name of the group.
mailboxMailbox object as created by mrmailbox_new().
Returns
1=success, 0=error
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()

Parameters
mailboxMailbox object as created by mrmailbox_new().
chat_idThe chat ID to set the image for.
new_imageFull 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).
Returns
1=success, 0=error
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.

Parameters
mailboxMailbox object as created by mrmailbox_new().
chat_idThe chat ID to check.
contact_idThe contact ID to check. To check if yourself is member of the chat, pass MR_CONTACT_ID_SELF (1) here.
Returns
1=contact ID is member of chat ID, 0=contact is not in chat
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.

Parameters
mailboxMailbox object as created by mrmailbox_new().
chat_idThe chat ID to add the contact to. Must be a group chat.
contact_idThe contact ID to add to the chat.
Returns
1=member added to group, 0=error
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.

Parameters
mailboxMailbox object as created by mrmailbox_new().
chat_idThe chat ID to remove the contact from. Must be a group chat.
contact_idThe contact ID to remove from the chat.
Returns
1=member removed from group, 0=error
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.

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
nameName of the contact to add. If you do not know the name belonging to the address, you can give NULL here.
addrE-mail-address of the contact to add. If the email address already exists, the name is updated and the origin is increased to "manually created".
Returns
Contact ID of the created or reused contact.
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().

Parameters
mailboxthe mailbox object as created by mrmailbox_new().
adr_bookA 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".
Returns
The number of modified or added contacts.
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().

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
queryA string to filter the list. Typically used to implement an incremental search. NULL for no filtering.
Returns
An array containing all contact IDs. Must be mrarray_unref()'d after usage.
mrarray_t * mrmailbox_get_blocked_contacts ( mrmailbox_t mailbox)

Get blocked contacts.

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
Returns
An array containing all blocked contact IDs. Must be mrarray_unref()'d after usage.
int mrmailbox_get_blocked_count ( mrmailbox_t mailbox)

Get the number of blocked contacts.

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

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
contact_idID of the contact to get the object for.
Returns
The contact object, must be freed using mrcontact_unref() when no longer used. NULL on errors.
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()

Parameters
mailboxThe mailbox object as created by mrmmailbox_new()
contact_idThe contact ID of which all messages should be marked as noticed.
Returns
none
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.

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
contact_idThe ID of the contact to block or unblock.
new_blocking1=block contact, 0=unblock contact
Returns
None.
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.

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
contact_idID of the contact to get the encryption info for.
Returns
multi-line text, must be free()'d after usage.
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.

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
contact_idID of the contact to delete.
Returns
1=success, 0=error
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()

Parameters
mailboxMailbox object as created by mrmailbox_new()
msg_idThe message ID for which the message object should be created.
Returns
A mrmsg_t message object. When done, the object must be freed using mrmsg_unref()
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.

Parameters
mailboxthe mailbox object as created by mrmailbox_new().
msg_idthe message id for which information should be generated
Returns
text string, must be free()'d after usage
void mrmailbox_forward_msgs ( mrmailbox_t mailbox,
const uint32_t *  msg_ids,
int  msg_cnt,
uint32_t  chat_id 
)

Forward messages to another chat.

Parameters
mailboxthe mailbox object as created by mrmailbox_new()
msg_idsan array of uint32_t containing all message IDs that should be forwarded
msg_cntthe number of messages IDs in the msg_ids array
chat_idThe destination chat ID.
Returns
none
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.

Parameters
mailboxThe mailbox object as created by mrmailbox_new()
msg_idsAn array of uint32_t message IDs defining the messages to star or unstar
msg_cntThe number of IDs in msg_ids
star0=unstar the messages in msg_ids, 1=star them
Returns
none
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.

Parameters
mailboxthe mailbox object as created by mrmailbox_new()
msg_idsan array of uint32_t containing all message IDs that should be deleted
msg_cntthe number of messages IDs in the msg_ids array
Returns
none
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()

Parameters
mailboxThe mailbox object.
msg_idsan array of uint32_t containing all the messages IDs that should be marked as seen.
msg_cntThe number of message IDs in msg_ids.
Returns
none
int mrmailbox_configure_and_connect ( mrmailbox_t mailbox)

Configure and connect a mailbox.

Parameters
mailboxthe mailbox object as created by mrmailbox_new().
Returns
1=configured and connected, 0=not configured, not explicitly connected, however, an existing connection may still be present

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:

if( mrmailbox_is_configured(mailbox) ) {
mrmailbox_connect(mailbox); // fast, reuse the configuration
}
else {
mrmailbox_configure_and_connect(mailbox); // may take a while, typically started in a thread
}
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.

Parameters
mailboxThe mailbox object as created by mrmailbox_new().
Returns
1=mailbox is configured and mrmailbox_connect() can be called directly as needed, 0=mailbox is not configured and a configuration by mrmailbox_configure_and_connect() is required.
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.

Parameters
mailboxThe mailbox object.
Returns
None
char * mrmailbox_initiate_key_transfer ( mrmailbox_t mailbox)

Initiate Autocrypt Key Transfer.

Parameters
mailboxThe mailbox object.
Returns
The setup code. Must be free()'d after usage. On errors, eg. if the message could not be sent, NULL is returned.

Before starting the key transfer with this function, the user should be asked:

"The 'Autocrypt Key Transfer' requires that the mail client on the other device is Autocrypt-compliant.
You can then send your key to yourself. Your key will be encrypted by a setup code which is displayed here and must be typed on the other device."

After that, this function should be called to send the Autocrypt setup message. The function creates the setup message and waits until it is really sent. As this may take a while, it is recommended to start the function in a separate thread; to interrupt it, you can use mrmailbox_stop_ongoing_process().

After everything succeeded, the required setup code is returned in the following format:

1234-1234-1234-1234-1234-1234-1234-1234-1234

The setup code should be shown to the user then:

"Your key has been sent to yourself. Switch to the other device and
open the setup message. You should be prompted for a setup code. Type
the following digits into the prompt:
1234 - 1234 - 1234 -
1234 - 1234 - 1234 -
1234 - 1234 - 1234
Once you're done, your other device will be ready to use Autocrypt."

On the other device you will call 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).

Parameters
mailboxThe mailbox object.
msg_idID of the setup message to decrypt.
setup_codeSetup 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.
Returns
1=key successfully decrypted and imported; both devices will use the same key now; 0=key transfer failed eg. due to a bad setup code.
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:

  • MR_IMEX_EXPORT_BACKUP (11) - Export a backup to the directory given as param1. The backup contains all contacts, chats, images and other data and device independent settings. The backup does not contain device dependent settings as ringtones or LED notification settings. The name of the backup is typically delta-chat.<day>.bak, if more than one backup is create on a day, the format is delta-chat.<day>-<number>.bak
  • MR_IMEX_IMPORT_BACKUP (12) - 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.
  • MR_IMEX_EXPORT_SELF_KEYS (1) - Export all private keys and all public keys of the user to the directory given as param1. The default key is written to the files public-key-default.asc and private-key-default.asc, if there are more keys, they are written to files as public-key-<id>.asc and private-key-<id>.asc
  • MR_IMEX_IMPORT_SELF_KEYS (2) - Import private keys found in the directory given as param1. The last imported key is made the default keys unless its name contains the string legacy. Public keys are not imported.

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

Parameters
mailboxMailbox object as created by mrmailbox_new().
whatOne of the MR_IMEX_* constants.
param1Meaning 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.
param2Meaning depends on the MR_IMEX_* constants. Set to NULL if not used.
Returns
1=success, 0=error or progress canceled.
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).

Parameters
mailboxMailbox object as created by mrmailbox_new().
dir_nameDirectory to search backups in.
Returns
String with the backup file, typically given to mrmailbox_imex(), returned strings must be free()'d. The function returns NULL if no backup was found.

Example:

char dir[] = "/dir/to/search/backups/in";
void ask_user_for_credentials()
{
// - ask the user for email and password
// - save them using mrmailbox_set_config()
}
int ask_user_whether_to_import()
{
// - inform the user that we've found a backup
// - ask if he want to import it
// - return 1 to import, 0 to skip
return 1;
}
if( !mrmailbox_is_configured(mailbox) )
{
char* file = NULL;
if( (file=mrmailbox_imex_has_backup(mailbox, dir))!=NULL && ask_user_whether_to_import() )
{
mrmailbox_imex(mailbox, MR_IMEX_IMPORT_BACKUP, file, NULL);
}
else
{
do {
ask_user_for_credentials();
}
}
free(file);
}
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.

Parameters
mailboxMailbox object as created by mrmailbox_new().
test_pwPassword to check.
Returns
1=user is authorized, 0=user is not authorized.

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