Delta Chat Core C-API
mrmailbox.h
1 /*******************************************************************************
2  *
3  * Delta Chat Core
4  * Copyright (C) 2017 Björn Petersen
5  * Contact: r10s@b44t.com, http://b44t.com
6  *
7  * This program is free software: you can redistribute it and/or modify it under
8  * the terms of the GNU General Public License as published by the Free Software
9  * Foundation, either version 3 of the License, or (at your option) any later
10  * version.
11  *
12  * This program is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
15  * details.
16  *
17  * You should have received a copy of the GNU General Public License along with
18  * this program. If not, see http://www.gnu.org/licenses/ .
19  *
20  ******************************************************************************/
21 
22 
23 #ifndef __MRMAILBOX_H__
24 #define __MRMAILBOX_H__
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 
30 #define MR_VERSION_MAJOR 0
31 #define MR_VERSION_MINOR 14
32 #define MR_VERSION_REVISION 0
33 
34 
150 #ifndef PY_CFFI
151 #include <pthread.h>
152 #include <libetpan/libetpan.h> /* defines uint16_t */
153 #endif
154 
155 #include "mrarray.h"
156 #include "mrchatlist.h"
157 #include "mrchat.h"
158 #include "mrmsg.h"
159 #include "mrcontact.h"
160 #include "mrlot.h"
161 #include "mrevent.h"
162 
163 
173 typedef struct _mrmailbox mrmailbox_t;
174 
175 
191 typedef uintptr_t (*mrmailboxcb_t) (mrmailbox_t*, int event, uintptr_t data1, uintptr_t data2);
192 
193 
194 
195 
196 /* create/open/connect */
197 mrmailbox_t* mrmailbox_new (mrmailboxcb_t, void* userdata, const char* os_name);
198 void mrmailbox_unref (mrmailbox_t*);
199 void* mrmailbox_get_userdata (mrmailbox_t*);
200 
201 int mrmailbox_open (mrmailbox_t*, const char* dbfile, const char* blobdir);
202 void mrmailbox_close (mrmailbox_t*);
203 int mrmailbox_is_open (const mrmailbox_t*);
204 char* mrmailbox_get_blobdir (mrmailbox_t*);
205 
206 int mrmailbox_set_config (mrmailbox_t*, const char* key, const char* value);
207 char* mrmailbox_get_config (mrmailbox_t*, const char* key, const char* def);
208 int mrmailbox_set_config_int (mrmailbox_t*, const char* key, int32_t value);
209 int32_t mrmailbox_get_config_int (mrmailbox_t*, const char* key, int32_t def);
210 char* mrmailbox_get_version_str (void);
211 
212 int mrmailbox_configure_and_connect(mrmailbox_t*);
213 void mrmailbox_stop_ongoing_process(mrmailbox_t*);
214 int mrmailbox_is_configured (mrmailbox_t*);
215 
216 void mrmailbox_connect (mrmailbox_t*);
217 void mrmailbox_disconnect (mrmailbox_t*);
218 
219 char* mrmailbox_get_info (mrmailbox_t*);
220 
221 
222 /* Handle chatlists */
223 #define MR_GCL_ARCHIVED_ONLY 0x01
224 #define MR_GCL_NO_SPECIALS 0x02
225 mrchatlist_t* mrmailbox_get_chatlist (mrmailbox_t*, int flags, const char* query);
226 
227 
228 /* Handle chats */
229 uint32_t mrmailbox_create_chat_by_contact_id (mrmailbox_t*, uint32_t contact_id);
230 uint32_t mrmailbox_get_chat_id_by_contact_id (mrmailbox_t*, uint32_t contact_id);
231 
232 uint32_t mrmailbox_send_text_msg (mrmailbox_t*, uint32_t chat_id, const char* text_to_send);
233 uint32_t mrmailbox_send_image_msg (mrmailbox_t*, uint32_t chat_id, const char* file, const char* filemime, int width, int height);
234 uint32_t mrmailbox_send_video_msg (mrmailbox_t*, uint32_t chat_id, const char* file, const char* filemime, int width, int height, int duration);
235 uint32_t mrmailbox_send_voice_msg (mrmailbox_t*, uint32_t chat_id, const char* file, const char* filemime, int duration);
236 uint32_t mrmailbox_send_audio_msg (mrmailbox_t*, uint32_t chat_id, const char* file, const char* filemime, int duration, const char* author, const char* trackname);
237 uint32_t mrmailbox_send_file_msg (mrmailbox_t*, uint32_t chat_id, const char* file, const char* filemime);
238 uint32_t mrmailbox_send_vcard_msg (mrmailbox_t*, uint32_t chat_id, uint32_t contact_id);
239 void mrmailbox_set_draft (mrmailbox_t*, uint32_t chat_id, const char*);
240 
241 #define MR_GCM_ADDDAYMARKER 0x01
242 mrarray_t* mrmailbox_get_chat_msgs (mrmailbox_t*, uint32_t chat_id, uint32_t flags, uint32_t marker1before);
243 int mrmailbox_get_total_msg_count (mrmailbox_t*, uint32_t chat_id);
244 int mrmailbox_get_fresh_msg_count (mrmailbox_t*, uint32_t chat_id);
245 mrarray_t* mrmailbox_get_fresh_msgs (mrmailbox_t*);
246 void mrmailbox_marknoticed_chat (mrmailbox_t*, uint32_t chat_id);
247 mrarray_t* mrmailbox_get_chat_media (mrmailbox_t*, uint32_t chat_id, int msg_type, int or_msg_type);
248 uint32_t mrmailbox_get_next_media (mrmailbox_t*, uint32_t curr_msg_id, int dir);
249 
250 void mrmailbox_archive_chat (mrmailbox_t*, uint32_t chat_id, int archive);
251 void mrmailbox_delete_chat (mrmailbox_t*, uint32_t chat_id);
252 
253 mrarray_t* mrmailbox_get_chat_contacts (mrmailbox_t*, uint32_t chat_id);
254 mrarray_t* mrmailbox_search_msgs (mrmailbox_t*, uint32_t chat_id, const char* query);
255 
256 mrchat_t* mrmailbox_get_chat (mrmailbox_t*, uint32_t chat_id);
257 
258 
259 /* Handle group chats */
260 uint32_t mrmailbox_create_group_chat (mrmailbox_t*, const char* name);
261 int mrmailbox_is_contact_in_chat (mrmailbox_t*, uint32_t chat_id, uint32_t contact_id);
262 int mrmailbox_add_contact_to_chat (mrmailbox_t*, uint32_t chat_id, uint32_t contact_id);
263 int mrmailbox_remove_contact_from_chat (mrmailbox_t*, uint32_t chat_id, uint32_t contact_id);
264 int mrmailbox_set_chat_name (mrmailbox_t*, uint32_t chat_id, const char* name);
265 int mrmailbox_set_chat_profile_image (mrmailbox_t*, uint32_t chat_id, const char* image);
266 
267 
268 /* Handle messages */
269 char* mrmailbox_get_msg_info (mrmailbox_t*, uint32_t msg_id);
270 void mrmailbox_delete_msgs (mrmailbox_t*, const uint32_t* msg_ids, int msg_cnt);
271 void mrmailbox_forward_msgs (mrmailbox_t*, const uint32_t* msg_ids, int msg_cnt, uint32_t chat_id);
272 void mrmailbox_marknoticed_contact (mrmailbox_t*, uint32_t contact_id);
273 void mrmailbox_markseen_msgs (mrmailbox_t*, const uint32_t* msg_ids, int msg_cnt);
274 void mrmailbox_star_msgs (mrmailbox_t*, const uint32_t* msg_ids, int msg_cnt, int star);
275 mrmsg_t* mrmailbox_get_msg (mrmailbox_t*, uint32_t msg_id);
276 
277 
278 /* Handle contacts */
279 uint32_t mrmailbox_create_contact (mrmailbox_t*, const char* name, const char* addr);
280 int mrmailbox_add_address_book (mrmailbox_t*, const char*);
281 mrarray_t* mrmailbox_get_known_contacts (mrmailbox_t*, const char* query);
282 int mrmailbox_get_blocked_count (mrmailbox_t*);
284 void mrmailbox_block_contact (mrmailbox_t*, uint32_t contact_id, int block);
285 char* mrmailbox_get_contact_encrinfo (mrmailbox_t*, uint32_t contact_id);
286 int mrmailbox_delete_contact (mrmailbox_t*, uint32_t contact_id);
287 mrcontact_t* mrmailbox_get_contact (mrmailbox_t*, uint32_t contact_id);
288 
289 
290 /* Import/export and Tools */
291 #define MR_IMEX_EXPORT_SELF_KEYS 1 /* param1 is a directory where the keys are written to */
292 #define MR_IMEX_IMPORT_SELF_KEYS 2 /* param1 is a directory where the keys are searched in and read from */
293 #define MR_IMEX_EXPORT_BACKUP 11 /* param1 is a directory where the backup is written to */
294 #define MR_IMEX_IMPORT_BACKUP 12 /* param1 is the file with the backup to import */
295 #define MR_BAK_PREFIX "delta-chat"
296 #define MR_BAK_SUFFIX "bak"
297 int mrmailbox_imex (mrmailbox_t*, int what, const char* param1, const char* param2);
298 char* mrmailbox_imex_has_backup (mrmailbox_t*, const char* dir);
299 int mrmailbox_check_password (mrmailbox_t*, const char* pw);
300 char* mrmailbox_initiate_key_transfer(mrmailbox_t*);
301 int mrmailbox_continue_key_transfer(mrmailbox_t*, uint32_t msg_id, const char* setup_code);
302 void mrmailbox_heartbeat (mrmailbox_t*);
303 
304 
305 /* logging */
306 void mrmailbox_log_error (mrmailbox_t*, int code, const char* msg, ...);
307 void mrmailbox_log_error_if (int* condition, mrmailbox_t*, int code, const char* msg, ...);
308 void mrmailbox_log_warning (mrmailbox_t*, int code, const char* msg, ...);
309 void mrmailbox_log_info (mrmailbox_t*, int code, const char* msg, ...);
310 
311 
312 /* error codes */
313 #define MR_ERR_SELF_NOT_IN_GROUP 1
314 #define MR_ERR_NONETWORK 2
315 
316 
317 /* deprecated functions */
318 int mrchat_set_draft (mrchat_t*, const char* msg); /* deprecated - use mrmailbox_set_draft() instead */
319 #define mrpoortext_t mrlot_t
320 #define mrpoortext_unref mrlot_unref
321 #define mrmailbox_imex_cancel mrmailbox_stop_ongoing_process
322 #define mrmailbox_configure_cancel mrmailbox_stop_ongoing_process
323 
324 
325 #ifdef __cplusplus
326 } /* /extern "C" */
327 #endif
328 #endif /* __MRMAILBOX_H__ */
An object containing a simple array.
int mrmailbox_set_config(mrmailbox_t *ths, const char *key, const char *value)
Configure the mailbox.
Definition: mrmailbox.c:1212
int mrmailbox_add_address_book(mrmailbox_t *mailbox, const char *adr_book)
Add a number of contacts.
Definition: mrmailbox.c:4476
mrcontact_t * mrmailbox_get_contact(mrmailbox_t *mailbox, uint32_t contact_id)
Get a single contact object.
Definition: mrmailbox.c:4697
void mrmailbox_forward_msgs(mrmailbox_t *mailbox, const uint32_t *msg_ids, int msg_cnt, uint32_t chat_id)
Forward messages to another chat.
Definition: mrmailbox.c:5347
The following constants are used as events reported to the callback given to mrmailbox_new().
int32_t mrmailbox_get_config_int(mrmailbox_t *ths, const char *key, int32_t def)
Get a configuration option.
Definition: mrmailbox.c:1287
char * mrmailbox_get_msg_info(mrmailbox_t *mailbox, uint32_t msg_id)
Get an informational text for a single message.
Definition: mrmailbox.c:5225
int mrmailbox_get_total_msg_count(mrmailbox_t *mailbox, uint32_t chat_id)
Get the total number of messages in a chat.
Definition: mrmailbox.c:2672
int mrmailbox_set_config_int(mrmailbox_t *ths, const char *key, int32_t value)
Configure the mailbox.
Definition: mrmailbox.c:1265
uint32_t mrmailbox_get_next_media(mrmailbox_t *mailbox, uint32_t curr_msg_id, int dir)
Get next/previous message of the same type.
Definition: mrmailbox.c:2006
char * mrmailbox_get_info(mrmailbox_t *mailbox)
Get information about the mailbox.
Definition: mrmailbox.c:1313
int mrmailbox_is_open(const mrmailbox_t *mailbox)
Check if the mailbox database is open.
Definition: mrmailbox.c:1126
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.
Definition: mrmailbox.c:5716
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.
Definition: mrmailbox.c:3996
int mrmailbox_open(mrmailbox_t *mailbox, const char *dbfile, const char *blobdir)
Open mailbox database.
Definition: mrmailbox.c:1027
mrarray_t * mrmailbox_get_fresh_msgs(mrmailbox_t *mailbox)
Returns the message IDs of all fresh messages of any chat.
Definition: mrmailbox.c:2131
uintptr_t(* mrmailboxcb_t)(mrmailbox_t *, int event, uintptr_t data1, uintptr_t data2)
Callback function that should be given to mrmailbox_new().
Definition: mrmailbox.h:191
void mrmailbox_archive_chat(mrmailbox_t *mailbox, uint32_t chat_id, int archive)
Archive or unarchive a chat.
Definition: mrmailbox.c:2740
int mrmailbox_add_contact_to_chat(mrmailbox_t *mailbox, uint32_t chat_id, uint32_t contact_id)
Add a member to a group.
Definition: mrmailbox.c:4032
void mrmailbox_marknoticed_chat(mrmailbox_t *mailbox, uint32_t chat_id)
Mark all messages in a chat as noticed.
Definition: mrmailbox.c:1827
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.
Definition: mrmailbox.c:3598
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.
Definition: mrmailbox.c:3383
uint32_t mrmailbox_create_contact(mrmailbox_t *mailbox, const char *name, const char *addr)
Add a single contact.
Definition: mrmailbox.c:4433
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).
Definition: mrmailbox.c:5433
int mrmailbox_configure_and_connect(mrmailbox_t *mailbox)
Configure and connect a mailbox.
Definition: mrmailbox_configure.c:393
An object representing a single chatlist in memory.
void mrmailbox_marknoticed_contact(mrmailbox_t *mailbox, uint32_t contact_id)
Mark all messages sent by the given contact as noticed.
Definition: mrmailbox.c:4736
int mrmailbox_continue_key_transfer(mrmailbox_t *mailbox, uint32_t msg_id, const char *setup_code)
Continue the Autocrypt Key Transfer on another device.
Definition: mrmailbox_imex.c:649
void mrmailbox_stop_ongoing_process(mrmailbox_t *mailbox)
Signal an ongoing process to stop.
Definition: mrmailbox_configure.c:789
char * mrmailbox_get_blobdir(mrmailbox_t *mailbox)
Get the blob directory.
Definition: mrmailbox.c:1146
int mrmailbox_imex(mrmailbox_t *mailbox, int what, const char *param1, const char *param2)
Import/export things.
Definition: mrmailbox_imex.c:1199
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.
Definition: mrmailbox.c:3469
int mrmailbox_get_fresh_msg_count(mrmailbox_t *mailbox, uint32_t chat_id)
Get the number of fresh messages in a chat.
Definition: mrmailbox.c:2700
mrarray_t * mrmailbox_search_msgs(mrmailbox_t *mailbox, uint32_t chat_id, const char *query)
Search messages containing the given query string.
Definition: mrmailbox.c:2303
char * mrmailbox_initiate_key_transfer(mrmailbox_t *mailbox)
Initiate Autocrypt Key Transfer.
Definition: mrmailbox_imex.c:473
uint32_t mrmailbox_send_vcard_msg(mrmailbox_t *mailbox, uint32_t chat_id, uint32_t contact_id)
Send foreign contact data to a chat.
Definition: mrmailbox.c:3643
mrchatlist_t * mrmailbox_get_chatlist(mrmailbox_t *mailbox, int listflags, const char *query)
Get a list of chats.
Definition: mrmailbox.c:1729
void mrmailbox_close(mrmailbox_t *mailbox)
Close mailbox database.
Definition: mrmailbox.c:1092
int mrmailbox_set_chat_profile_image(mrmailbox_t *mailbox, uint32_t chat_id, const char *new_image)
Set group profile image.
Definition: mrmailbox.c:3907
mrarray_t * mrmailbox_get_blocked_contacts(mrmailbox_t *mailbox)
Get blocked contacts.
Definition: mrmailbox.c:4617
An object representing a single message in memory.
An object representing a single mailbox.
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.
Definition: mrmailbox.c:2199
int mrmailbox_get_blocked_count(mrmailbox_t *mailbox)
Get the number of blocked contacts.
Definition: mrmailbox.c:4651
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.
Definition: mrmailbox.c:3513
void mrmailbox_set_draft(mrmailbox_t *mailbox, uint32_t chat_id, const char *msg)
Save a draft for a chat.
Definition: mrmailbox.c:2452
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.
Definition: mrmailbox.c:1972
uint32_t mrmailbox_create_group_chat(mrmailbox_t *mailbox, const char *chat_name)
Create a new group chat.
Definition: mrmailbox.c:3758
char * mrmailbox_imex_has_backup(mrmailbox_t *mailbox, const char *dir_name)
Check if there is a backup file.
Definition: mrmailbox_imex.c:1325
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.
Definition: mrmailbox.c:1861
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.
Definition: mrmailbox.c:3424
int mrmailbox_remove_contact_from_chat(mrmailbox_t *mailbox, uint32_t chat_id, uint32_t contact_id)
Remove a member from a group.
Definition: mrmailbox.c:4117
int mrmailbox_check_password(mrmailbox_t *mailbox, const char *test_pw)
Check if the user is authorized by the given password in some way.
Definition: mrmailbox_imex.c:1391
int mrmailbox_delete_contact(mrmailbox_t *mailbox, uint32_t contact_id)
Delete a contact.
Definition: mrmailbox.c:4987
mrchat_t * mrmailbox_get_chat(mrmailbox_t *mailbox, uint32_t chat_id)
Get chat object by a chat ID.
Definition: mrmailbox.c:1777
void mrmailbox_unref(mrmailbox_t *mailbox)
Free a mailbox object.
Definition: mrmailbox.c:948
char * mrmailbox_get_contact_encrinfo(mrmailbox_t *mailbox, uint32_t contact_id)
Get encryption info for a contact.
Definition: mrmailbox.c:4853
void mrmailbox_delete_msgs(mrmailbox_t *mailbox, const uint32_t *msg_ids, int msg_cnt)
Delete messages.
Definition: mrmailbox.c:5575
mrarray_t * mrmailbox_get_known_contacts(mrmailbox_t *mailbox, const char *query)
Returns known and unblocked contacts.
Definition: mrmailbox.c:4531
void mrmailbox_delete_chat(mrmailbox_t *mailbox, uint32_t chat_id)
Delete a chat.
Definition: mrmailbox.c:2861
void mrmailbox_block_contact(mrmailbox_t *mailbox, uint32_t contact_id, int new_blocking)
Block or unblock a contact.
Definition: mrmailbox.c:4762
mrarray_t * mrmailbox_get_chat_contacts(mrmailbox_t *mailbox, uint32_t chat_id)
Get contact IDs belonging to a chat.
Definition: mrmailbox.c:2082
void mrmailbox_heartbeat(mrmailbox_t *ths)
Stay alive.
Definition: mrmailbox.c:1697
mrmsg_t * mrmailbox_get_msg(mrmailbox_t *mailbox, uint32_t msg_id)
Get a single message object of the type mrmsg_t.
Definition: mrmailbox.c:5179
void mrmailbox_disconnect(mrmailbox_t *mailbox)
Disonnect the mailbox from the server.
Definition: mrmailbox.c:1672
An object representing a single chat in memory.
int mrmailbox_is_configured(mrmailbox_t *mailbox)
Check if the mailbox is already configured.
Definition: mrmailbox_configure.c:705
uint32_t mrmailbox_create_chat_by_contact_id(mrmailbox_t *mailbox, uint32_t contact_id)
Create a normal chat with a single user.
Definition: mrmailbox.c:1892
void * mrmailbox_get_userdata(mrmailbox_t *mailbox)
Get user data associated with a mailbox object.
Definition: mrmailbox.c:990
char * mrmailbox_get_version_str(void)
Find out the version of the Delta Chat core library.
Definition: mrmailbox.c:1550
void mrmailbox_connect(mrmailbox_t *mailbox)
Connect to the mailbox using the configured settings.
Definition: mrmailbox.c:1645
char * mrmailbox_get_config(mrmailbox_t *ths, const char *key, const char *def)
Get a configuration option.
Definition: mrmailbox.c:1243
mrmailbox_t * mrmailbox_new(mrmailboxcb_t cb, void *userdata, const char *os_name)
Create a new mailbox object.
Definition: mrmailbox.c:890
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.
Definition: mrmailbox.c:3556
int mrmailbox_set_chat_name(mrmailbox_t *mailbox, uint32_t chat_id, const char *new_name)
Set group name.
Definition: mrmailbox.c:3826
An object representing a single contact in memory.