d9f3003fad32381151d92ea9d847d695daf65a77
[notmuch] / lib / notmuch.h
1 /* notmuch - Not much of an email library, (just index and search)
2  *
3  * Copyright © 2009 Carl Worth
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation, either version 3 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program.  If not, see https://www.gnu.org/licenses/ .
17  *
18  * Author: Carl Worth <cworth@cworth.org>
19  */
20
21 /**
22  * @defgroup notmuch The notmuch API
23  *
24  * Not much of an email library, (just index and search)
25  *
26  * @{
27  */
28
29 #ifndef NOTMUCH_H
30 #define NOTMUCH_H
31
32 #ifndef __DOXYGEN__
33
34 #ifdef  __cplusplus
35 # define NOTMUCH_BEGIN_DECLS  extern "C" {
36 # define NOTMUCH_END_DECLS    }
37 #else
38 # define NOTMUCH_BEGIN_DECLS
39 # define NOTMUCH_END_DECLS
40 #endif
41
42 NOTMUCH_BEGIN_DECLS
43
44 #include <time.h>
45
46 #pragma GCC visibility push(default)
47
48 #ifndef FALSE
49 #define FALSE 0
50 #endif
51
52 #ifndef TRUE
53 #define TRUE 1
54 #endif
55
56 /*
57  * The library version number.  This must agree with the soname
58  * version in Makefile.local.
59  */
60 #define LIBNOTMUCH_MAJOR_VERSION        5
61 #define LIBNOTMUCH_MINOR_VERSION        3
62 #define LIBNOTMUCH_MICRO_VERSION        0
63
64
65 #if defined (__clang_major__) && __clang_major__ >= 3 \
66     || defined (__GNUC__) && __GNUC__ >= 5 \
67     || defined (__GNUC__) && __GNUC__ == 4 && __GNUC_MINOR__ >= 5
68 #define NOTMUCH_DEPRECATED(major, minor) \
69     __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor)))
70 #else
71 #define NOTMUCH_DEPRECATED(major, minor) __attribute__ ((deprecated))
72 #endif
73
74
75 #endif /* __DOXYGEN__ */
76
77 /**
78  * Check the version of the notmuch library being compiled against.
79  *
80  * Return true if the library being compiled against is of the
81  * specified version or above. For example:
82  *
83  * @code
84  * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0)
85  *     (code requiring libnotmuch 3.1.0 or above)
86  * #endif
87  * @endcode
88  *
89  * LIBNOTMUCH_CHECK_VERSION has been defined since version 3.1.0; to
90  * check for versions prior to that, use:
91  *
92  * @code
93  * #if !defined(NOTMUCH_CHECK_VERSION)
94  *     (code requiring libnotmuch prior to 3.1.0)
95  * #endif
96  * @endcode
97  */
98 #define LIBNOTMUCH_CHECK_VERSION(major, minor, micro)                   \
99     (LIBNOTMUCH_MAJOR_VERSION > (major) ||                                      \
100      (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION > (minor)) || \
101      (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION == (minor) && \
102       LIBNOTMUCH_MICRO_VERSION >= (micro)))
103
104 /**
105  * Notmuch boolean type.
106  */
107 typedef int notmuch_bool_t;
108
109 /**
110  * Status codes used for the return values of most functions.
111  *
112  * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function
113  * completed without error. Any other value indicates an error.
114  */
115 typedef enum _notmuch_status {
116     /**
117      * No error occurred.
118      */
119     NOTMUCH_STATUS_SUCCESS = 0,
120     /**
121      * Out of memory.
122      */
123     NOTMUCH_STATUS_OUT_OF_MEMORY,
124     /**
125      * An attempt was made to write to a database opened in read-only
126      * mode.
127      */
128     NOTMUCH_STATUS_READ_ONLY_DATABASE,
129     /**
130      * A Xapian exception occurred.
131      *
132      * @todo We don't really want to expose this lame XAPIAN_EXCEPTION
133      * value. Instead we should map to things like DATABASE_LOCKED or
134      * whatever.
135      */
136     NOTMUCH_STATUS_XAPIAN_EXCEPTION,
137     /**
138      * An error occurred trying to read or write to a file (this could
139      * be file not found, permission denied, etc.)
140      */
141     NOTMUCH_STATUS_FILE_ERROR,
142     /**
143      * A file was presented that doesn't appear to be an email
144      * message.
145      */
146     NOTMUCH_STATUS_FILE_NOT_EMAIL,
147     /**
148      * A file contains a message ID that is identical to a message
149      * already in the database.
150      */
151     NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID,
152     /**
153      * The user erroneously passed a NULL pointer to a notmuch
154      * function.
155      */
156     NOTMUCH_STATUS_NULL_POINTER,
157     /**
158      * A tag value is too long (exceeds NOTMUCH_TAG_MAX).
159      */
160     NOTMUCH_STATUS_TAG_TOO_LONG,
161     /**
162      * The notmuch_message_thaw function has been called more times
163      * than notmuch_message_freeze.
164      */
165     NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
166     /**
167      * notmuch_database_end_atomic has been called more times than
168      * notmuch_database_begin_atomic.
169      */
170     NOTMUCH_STATUS_UNBALANCED_ATOMIC,
171     /**
172      * The operation is not supported.
173      */
174     NOTMUCH_STATUS_UNSUPPORTED_OPERATION,
175     /**
176      * The operation requires a database upgrade.
177      */
178     NOTMUCH_STATUS_UPGRADE_REQUIRED,
179     /**
180      * There is a problem with the proposed path, e.g. a relative path
181      * passed to a function expecting an absolute path.
182      */
183     NOTMUCH_STATUS_PATH_ERROR,
184     /**
185      * The requested operation was ignored. Depending on the function,
186      * this may not be an actual error.
187      */
188     NOTMUCH_STATUS_IGNORED,
189     /**
190      * One of the arguments violates the preconditions for the
191      * function, in a way not covered by a more specific argument.
192      */
193     NOTMUCH_STATUS_ILLEGAL_ARGUMENT,
194     /**
195      * A MIME object claimed to have cryptographic protection which
196      * notmuch tried to handle, but the protocol was not specified in
197      * an intelligible way.
198      */
199     NOTMUCH_STATUS_MALFORMED_CRYPTO_PROTOCOL,
200     /**
201      * Notmuch attempted to do crypto processing, but could not
202      * initialize the engine needed to do so.
203      */
204     NOTMUCH_STATUS_FAILED_CRYPTO_CONTEXT_CREATION,
205     /**
206      * A MIME object claimed to have cryptographic protection, and
207      * notmuch attempted to process it, but the specific protocol was
208      * something that notmuch doesn't know how to handle.
209      */
210     NOTMUCH_STATUS_UNKNOWN_CRYPTO_PROTOCOL,
211     /**
212      * Not an actual status value. Just a way to find out how many
213      * valid status values there are.
214      */
215     NOTMUCH_STATUS_LAST_STATUS
216 } notmuch_status_t;
217
218 /**
219  * Get a string representation of a notmuch_status_t value.
220  *
221  * The result is read-only.
222  */
223 const char *
224 notmuch_status_to_string (notmuch_status_t status);
225
226 /* Various opaque data types. For each notmuch_<foo>_t see the various
227  * notmuch_<foo> functions below. */
228 #ifndef __DOXYGEN__
229 typedef struct _notmuch_database notmuch_database_t;
230 typedef struct _notmuch_query notmuch_query_t;
231 typedef struct _notmuch_threads notmuch_threads_t;
232 typedef struct _notmuch_thread notmuch_thread_t;
233 typedef struct _notmuch_messages notmuch_messages_t;
234 typedef struct _notmuch_message notmuch_message_t;
235 typedef struct _notmuch_tags notmuch_tags_t;
236 typedef struct _notmuch_directory notmuch_directory_t;
237 typedef struct _notmuch_filenames notmuch_filenames_t;
238 typedef struct _notmuch_config_list notmuch_config_list_t;
239 typedef struct _notmuch_indexopts notmuch_indexopts_t;
240 #endif /* __DOXYGEN__ */
241
242 /**
243  * Create a new, empty notmuch database located at 'path'.
244  *
245  * The path should be a top-level directory to a collection of
246  * plain-text email messages (one message per file). This call will
247  * create a new ".notmuch" directory within 'path' where notmuch will
248  * store its data.
249  *
250  * After a successful call to notmuch_database_create, the returned
251  * database will be open so the caller should call
252  * notmuch_database_destroy when finished with it.
253  *
254  * The database will not yet have any data in it
255  * (notmuch_database_create itself is a very cheap function). Messages
256  * contained within 'path' can be added to the database by calling
257  * notmuch_database_index_file.
258  *
259  * In case of any failure, this function returns an error status and
260  * sets *database to NULL (after printing an error message on stderr).
261  *
262  * Return value:
263  *
264  * NOTMUCH_STATUS_SUCCESS: Successfully created the database.
265  *
266  * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL.
267  *
268  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
269  *
270  * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the
271  *      database file (such as permission denied, or file not found,
272  *      etc.), or the database already exists.
273  *
274  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
275  */
276 notmuch_status_t
277 notmuch_database_create (const char *path, notmuch_database_t **database);
278
279 /**
280  * Like notmuch_database_create, except optionally return an error
281  * message. This message is allocated by malloc and should be freed by
282  * the caller.
283  */
284 notmuch_status_t
285 notmuch_database_create_verbose (const char *path,
286                                  notmuch_database_t **database,
287                                  char **error_message);
288
289 /**
290  * Database open mode for notmuch_database_open.
291  */
292 typedef enum {
293     /**
294      * Open database for reading only.
295      */
296     NOTMUCH_DATABASE_MODE_READ_ONLY = 0,
297     /**
298      * Open database for reading and writing.
299      */
300     NOTMUCH_DATABASE_MODE_READ_WRITE
301 } notmuch_database_mode_t;
302
303 /**
304  * Open an existing notmuch database located at 'path'.
305  *
306  * The database should have been created at some time in the past,
307  * (not necessarily by this process), by calling
308  * notmuch_database_create with 'path'. By default the database should be
309  * opened for reading only. In order to write to the database you need to
310  * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.
311  *
312  * An existing notmuch database can be identified by the presence of a
313  * directory named ".notmuch" below 'path'.
314  *
315  * The caller should call notmuch_database_destroy when finished with
316  * this database.
317  *
318  * In case of any failure, this function returns an error status and
319  * sets *database to NULL (after printing an error message on stderr).
320  *
321  * Return value:
322  *
323  * NOTMUCH_STATUS_SUCCESS: Successfully opened the database.
324  *
325  * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL.
326  *
327  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
328  *
329  * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the
330  *      database file (such as permission denied, or file not found,
331  *      etc.), or the database version is unknown.
332  *
333  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
334  */
335 notmuch_status_t
336 notmuch_database_open (const char *path,
337                        notmuch_database_mode_t mode,
338                        notmuch_database_t **database);
339 /**
340  * Like notmuch_database_open, except optionally return an error
341  * message. This message is allocated by malloc and should be freed by
342  * the caller.
343  */
344
345 notmuch_status_t
346 notmuch_database_open_verbose (const char *path,
347                                notmuch_database_mode_t mode,
348                                notmuch_database_t **database,
349                                char **error_message);
350
351 /**
352  * Retrieve last status string for given database.
353  *
354  */
355 const char *
356 notmuch_database_status_string (const notmuch_database_t *notmuch);
357
358 /**
359  * Commit changes and close the given notmuch database.
360  *
361  * After notmuch_database_close has been called, calls to other
362  * functions on objects derived from this database may either behave
363  * as if the database had not been closed (e.g., if the required data
364  * has been cached) or may fail with a
365  * NOTMUCH_STATUS_XAPIAN_EXCEPTION. The only further operation
366  * permitted on the database itself is to call
367  * notmuch_database_destroy.
368  *
369  * notmuch_database_close can be called multiple times.  Later calls
370  * have no effect.
371  *
372  * For writable databases, notmuch_database_close commits all changes
373  * to disk before closing the database.  If the caller is currently in
374  * an atomic section (there was a notmuch_database_begin_atomic
375  * without a matching notmuch_database_end_atomic), this will discard
376  * changes made in that atomic section (but still commit changes made
377  * prior to entering the atomic section).
378  *
379  * Return value:
380  *
381  * NOTMUCH_STATUS_SUCCESS: Successfully closed the database.
382  *
383  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; the
384  *      database has been closed but there are no guarantees the
385  *      changes to the database, if any, have been flushed to disk.
386  */
387 notmuch_status_t
388 notmuch_database_close (notmuch_database_t *database);
389
390 /**
391  * A callback invoked by notmuch_database_compact to notify the user
392  * of the progress of the compaction process.
393  */
394 typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure);
395
396 /**
397  * Compact a notmuch database, backing up the original database to the
398  * given path.
399  *
400  * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE
401  * during the compaction process to ensure no writes are made.
402  *
403  * If the optional callback function 'status_cb' is non-NULL, it will
404  * be called with diagnostic and informational messages. The argument
405  * 'closure' is passed verbatim to any callback invoked.
406  */
407 notmuch_status_t
408 notmuch_database_compact (const char *path,
409                           const char *backup_path,
410                           notmuch_compact_status_cb_t status_cb,
411                           void *closure);
412
413 /**
414  * Destroy the notmuch database, closing it if necessary and freeing
415  * all associated resources.
416  *
417  * Return value as in notmuch_database_close if the database was open;
418  * notmuch_database_destroy itself has no failure modes.
419  */
420 notmuch_status_t
421 notmuch_database_destroy (notmuch_database_t *database);
422
423 /**
424  * Return the database path of the given database.
425  *
426  * The return value is a string owned by notmuch so should not be
427  * modified nor freed by the caller.
428  */
429 const char *
430 notmuch_database_get_path (notmuch_database_t *database);
431
432 /**
433  * Return the database format version of the given database.
434  *
435  * @retval 0 on error
436  */
437 unsigned int
438 notmuch_database_get_version (notmuch_database_t *database);
439
440 /**
441  * Can the database be upgraded to a newer database version?
442  *
443  * If this function returns TRUE, then the caller may call
444  * notmuch_database_upgrade to upgrade the database.  If the caller
445  * does not upgrade an out-of-date database, then some functions may
446  * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED.  This always returns
447  * FALSE for a read-only database because there's no way to upgrade a
448  * read-only database.
449  *
450  */
451 notmuch_bool_t
452 notmuch_database_needs_upgrade (notmuch_database_t *database);
453
454 /**
455  * Upgrade the current database to the latest supported version.
456  *
457  * This ensures that all current notmuch functionality will be
458  * available on the database.  After opening a database in read-write
459  * mode, it is recommended that clients check if an upgrade is needed
460  * (notmuch_database_needs_upgrade) and if so, upgrade with this
461  * function before making any modifications.  If
462  * notmuch_database_needs_upgrade returns FALSE, this will be a no-op.
463  *
464  * The optional progress_notify callback can be used by the caller to
465  * provide progress indication to the user. If non-NULL it will be
466  * called periodically with 'progress' as a floating-point value in
467  * the range of [0.0 .. 1.0] indicating the progress made so far in
468  * the upgrade process.  The argument 'closure' is passed verbatim to
469  * any callback invoked.
470  */
471 notmuch_status_t
472 notmuch_database_upgrade (notmuch_database_t *database,
473                           void (*progress_notify)(void *closure,
474                                                   double progress),
475                           void *closure);
476
477 /**
478  * Begin an atomic database operation.
479  *
480  * Any modifications performed between a successful begin and a
481  * notmuch_database_end_atomic will be applied to the database
482  * atomically.  Note that, unlike a typical database transaction, this
483  * only ensures atomicity, not durability; neither begin nor end
484  * necessarily flush modifications to disk.
485  *
486  * Atomic sections may be nested.  begin_atomic and end_atomic must
487  * always be called in pairs.
488  *
489  * Return value:
490  *
491  * NOTMUCH_STATUS_SUCCESS: Successfully entered atomic section.
492  *
493  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
494  *      atomic section not entered.
495  */
496 notmuch_status_t
497 notmuch_database_begin_atomic (notmuch_database_t *notmuch);
498
499 /**
500  * Indicate the end of an atomic database operation.
501  *
502  * Return value:
503  *
504  * NOTMUCH_STATUS_SUCCESS: Successfully completed atomic section.
505  *
506  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
507  *      atomic section not ended.
508  *
509  * NOTMUCH_STATUS_UNBALANCED_ATOMIC: The database is not currently in
510  *      an atomic section.
511  */
512 notmuch_status_t
513 notmuch_database_end_atomic (notmuch_database_t *notmuch);
514
515 /**
516  * Return the committed database revision and UUID.
517  *
518  * The database revision number increases monotonically with each
519  * commit to the database.  Hence, all messages and message changes
520  * committed to the database (that is, visible to readers) have a last
521  * modification revision <= the committed database revision.  Any
522  * messages committed in the future will be assigned a modification
523  * revision > the committed database revision.
524  *
525  * The UUID is a NUL-terminated opaque string that uniquely identifies
526  * this database.  Two revision numbers are only comparable if they
527  * have the same database UUID.
528  */
529 unsigned long
530 notmuch_database_get_revision (notmuch_database_t *notmuch,
531                                const char **uuid);
532
533 /**
534  * Retrieve a directory object from the database for 'path'.
535  *
536  * Here, 'path' should be a path relative to the path of 'database'
537  * (see notmuch_database_get_path), or else should be an absolute path
538  * with initial components that match the path of 'database'.
539  *
540  * If this directory object does not exist in the database, this
541  * returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL.
542  *
543  * Otherwise the returned directory object is owned by the database
544  * and as such, will only be valid until notmuch_database_destroy is
545  * called.
546  *
547  * Return value:
548  *
549  * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory.
550  *
551  * NOTMUCH_STATUS_NULL_POINTER: The given 'directory' argument is NULL.
552  *
553  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
554  *      directory not retrieved.
555  *
556  * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
557  *      database to use this function.
558  */
559 notmuch_status_t
560 notmuch_database_get_directory (notmuch_database_t *database,
561                                 const char *path,
562                                 notmuch_directory_t **directory);
563
564 /**
565  * Add a message file to a database, indexing it for retrieval by
566  * future searches.  If a message already exists with the same message
567  * ID as the specified file, their indexes will be merged, and this
568  * new filename will also be associated with the existing message.
569  *
570  * Here, 'filename' should be a path relative to the path of
571  * 'database' (see notmuch_database_get_path), or else should be an
572  * absolute filename with initial components that match the path of
573  * 'database'.
574  *
575  * The file should be a single mail message (not a multi-message mbox)
576  * that is expected to remain at its current location, (since the
577  * notmuch database will reference the filename, and will not copy the
578  * entire contents of the file.
579  *
580  * If another message with the same message ID already exists in the
581  * database, rather than creating a new message, this adds the search
582  * terms from the identified file to the existing message's index, and
583  * adds 'filename' to the list of filenames known for the message.
584  *
585  * The 'indexopts' parameter can be NULL (meaning, use the indexing
586  * defaults from the database), or can be an explicit choice of
587  * indexing options that should govern the indexing of this specific
588  * 'filename'.
589  *
590  * If 'message' is not NULL, then, on successful return
591  * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'
592  * will be initialized to a message object that can be used for things
593  * such as adding tags to the just-added message. The user should call
594  * notmuch_message_destroy when done with the message. On any failure
595  * '*message' will be set to NULL.
596  *
597  * Return value:
598  *
599  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
600  *
601  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
602  *      message not added.
603  *
604  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
605  *      ID as another message already in the database. The new
606  *      filename was successfully added to the message in the database
607  *      (if not already present) and the existing message is returned.
608  *
609  * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
610  *      file, (such as permission denied, or file not found,
611  *      etc.). Nothing added to the database.
612  *
613  * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look
614  *      like an email message. Nothing added to the database.
615  *
616  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
617  *      mode so no message can be added.
618  *
619  * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
620  *      database to use this function.
621  *
622  * @since libnotmuch 5.1 (notmuch 0.26)
623  */
624 notmuch_status_t
625 notmuch_database_index_file (notmuch_database_t *database,
626                              const char *filename,
627                              notmuch_indexopts_t *indexopts,
628                              notmuch_message_t **message);
629
630 /**
631  * Deprecated alias for notmuch_database_index_file called with
632  * NULL indexopts.
633  *
634  * @deprecated Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please
635  * use notmuch_database_index_file instead.
636  *
637  */
638 NOTMUCH_DEPRECATED (5, 1)
639 notmuch_status_t
640 notmuch_database_add_message (notmuch_database_t *database,
641                               const char *filename,
642                               notmuch_message_t **message);
643
644 /**
645  * Remove a message filename from the given notmuch database. If the
646  * message has no more filenames, remove the message.
647  *
648  * If the same message (as determined by the message ID) is still
649  * available via other filenames, then the message will persist in the
650  * database for those filenames. When the last filename is removed for
651  * a particular message, the database content for that message will be
652  * entirely removed.
653  *
654  * Return value:
655  *
656  * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
657  *      message was removed from the database.
658  *
659  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
660  *      message not removed.
661  *
662  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
663  *      the message persists in the database with at least one other
664  *      filename.
665  *
666  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
667  *      mode so no message can be removed.
668  *
669  * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
670  *      database to use this function.
671  */
672 notmuch_status_t
673 notmuch_database_remove_message (notmuch_database_t *database,
674                                  const char *filename);
675
676 /**
677  * Find a message with the given message_id.
678  *
679  * If a message with the given message_id is found then, on successful return
680  * (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to a message
681  * object.  The caller should call notmuch_message_destroy when done with the
682  * message.
683  *
684  * On any failure or when the message is not found, this function initializes
685  * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the
686  * caller is supposed to check '*message' for NULL to find out whether the
687  * message with the given message_id was found.
688  *
689  * Return value:
690  *
691  * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'.
692  *
693  * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL
694  *
695  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating message object
696  *
697  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
698  */
699 notmuch_status_t
700 notmuch_database_find_message (notmuch_database_t *database,
701                                const char *message_id,
702                                notmuch_message_t **message);
703
704 /**
705  * Find a message with the given filename.
706  *
707  * If the database contains a message with the given filename then, on
708  * successful return (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to
709  * a message object. The caller should call notmuch_message_destroy when done
710  * with the message.
711  *
712  * On any failure or when the message is not found, this function initializes
713  * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the
714  * caller is supposed to check '*message' for NULL to find out whether the
715  * message with the given filename is found.
716  *
717  * Return value:
718  *
719  * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'
720  *
721  * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL
722  *
723  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message object
724  *
725  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
726  *
727  * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
728  *      database to use this function.
729  */
730 notmuch_status_t
731 notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
732                                            const char *filename,
733                                            notmuch_message_t **message);
734
735 /**
736  * Return a list of all tags found in the database.
737  *
738  * This function creates a list of all tags found in the database. The
739  * resulting list contains all tags from all messages found in the database.
740  *
741  * On error this function returns NULL.
742  */
743 notmuch_tags_t *
744 notmuch_database_get_all_tags (notmuch_database_t *db);
745
746 /**
747  * Create a new query for 'database'.
748  *
749  * Here, 'database' should be an open database, (see
750  * notmuch_database_open and notmuch_database_create).
751  *
752  * For the query string, we'll document the syntax here more
753  * completely in the future, but it's likely to be a specialized
754  * version of the general Xapian query syntax:
755  *
756  * https://xapian.org/docs/queryparser.html
757  *
758  * As a special case, passing either a length-zero string, (that is ""),
759  * or a string consisting of a single asterisk (that is "*"), will
760  * result in a query that returns all messages in the database.
761  *
762  * See notmuch_query_set_sort for controlling the order of results.
763  * See notmuch_query_search_messages and notmuch_query_search_threads
764  * to actually execute the query.
765  *
766  * User should call notmuch_query_destroy when finished with this
767  * query.
768  *
769  * Will return NULL if insufficient memory is available.
770  */
771 notmuch_query_t *
772 notmuch_query_create (notmuch_database_t *database,
773                       const char *query_string);
774
775 /**
776  * Sort values for notmuch_query_set_sort.
777  */
778 typedef enum {
779     /**
780      * Oldest first.
781      */
782     NOTMUCH_SORT_OLDEST_FIRST,
783     /**
784      * Newest first.
785      */
786     NOTMUCH_SORT_NEWEST_FIRST,
787     /**
788      * Sort by message-id.
789      */
790     NOTMUCH_SORT_MESSAGE_ID,
791     /**
792      * Do not sort.
793      */
794     NOTMUCH_SORT_UNSORTED
795 } notmuch_sort_t;
796
797 /**
798  * Return the query_string of this query. See notmuch_query_create.
799  */
800 const char *
801 notmuch_query_get_query_string (const notmuch_query_t *query);
802
803 /**
804  * Return the notmuch database of this query. See notmuch_query_create.
805  */
806 notmuch_database_t *
807 notmuch_query_get_database (const notmuch_query_t *query);
808
809 /**
810  * Exclude values for notmuch_query_set_omit_excluded. The strange
811  * order is to maintain backward compatibility: the old FALSE/TRUE
812  * options correspond to the new
813  * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
814  */
815 typedef enum {
816     NOTMUCH_EXCLUDE_FLAG,
817     NOTMUCH_EXCLUDE_TRUE,
818     NOTMUCH_EXCLUDE_FALSE,
819     NOTMUCH_EXCLUDE_ALL
820 } notmuch_exclude_t;
821
822 /**
823  * Specify whether to omit excluded results or simply flag them.  By
824  * default, this is set to TRUE.
825  *
826  * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded
827  * messages from the results, and notmuch_query_search_threads will omit
828  * threads that match only in excluded messages.  If set to TRUE,
829  * notmuch_query_search_threads will include all messages in threads that
830  * match in at least one non-excluded message.  Otherwise, if set to ALL,
831  * notmuch_query_search_threads will omit excluded messages from all threads.
832  *
833  * If set to FALSE or FLAG then both notmuch_query_search_messages and
834  * notmuch_query_search_threads will return all matching
835  * messages/threads regardless of exclude status. If set to FLAG then
836  * the exclude flag will be set for any excluded message that is
837  * returned by notmuch_query_search_messages, and the thread counts
838  * for threads returned by notmuch_query_search_threads will be the
839  * number of non-excluded messages/matches. Otherwise, if set to
840  * FALSE, then the exclude status is completely ignored.
841  *
842  * The performance difference when calling
843  * notmuch_query_search_messages should be relatively small (and both
844  * should be very fast).  However, in some cases,
845  * notmuch_query_search_threads is very much faster when omitting
846  * excluded messages as it does not need to construct the threads that
847  * only match in excluded messages.
848  */
849 void
850 notmuch_query_set_omit_excluded (notmuch_query_t *query,
851                                  notmuch_exclude_t omit_excluded);
852
853 /**
854  * Specify the sorting desired for this query.
855  */
856 void
857 notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
858
859 /**
860  * Return the sort specified for this query. See
861  * notmuch_query_set_sort.
862  */
863 notmuch_sort_t
864 notmuch_query_get_sort (const notmuch_query_t *query);
865
866 /**
867  * Add a tag that will be excluded from the query results by default.
868  * This exclusion will be ignored if this tag appears explicitly in
869  * the query.
870  *
871  * @returns
872  *
873  * NOTMUCH_STATUS_SUCCESS: excluded was added successfully.
874  *
875  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred.
876  *      Most likely a problem lazily parsing the query string.
877  *
878  * NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so
879  *              not excluded.
880  */
881 notmuch_status_t
882 notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
883
884 /**
885  * Execute a query for threads, returning a notmuch_threads_t object
886  * which can be used to iterate over the results. The returned threads
887  * object is owned by the query and as such, will only be valid until
888  * notmuch_query_destroy.
889  *
890  * Typical usage might be:
891  *
892  *     notmuch_query_t *query;
893  *     notmuch_threads_t *threads;
894  *     notmuch_thread_t *thread;
895  *     notmuch_status_t stat;
896  *
897  *     query = notmuch_query_create (database, query_string);
898  *
899  *     for (stat = notmuch_query_search_threads (query, &threads);
900  *          stat == NOTMUCH_STATUS_SUCCESS &&
901  *          notmuch_threads_valid (threads);
902  *          notmuch_threads_move_to_next (threads))
903  *     {
904  *         thread = notmuch_threads_get (threads);
905  *         ....
906  *         notmuch_thread_destroy (thread);
907  *     }
908  *
909  *     notmuch_query_destroy (query);
910  *
911  * Note: If you are finished with a thread before its containing
912  * query, you can call notmuch_thread_destroy to clean up some memory
913  * sooner (as in the above example). Otherwise, if your thread objects
914  * are long-lived, then you don't need to call notmuch_thread_destroy
915  * and all the memory will still be reclaimed when the query is
916  * destroyed.
917  *
918  * Note that there's no explicit destructor needed for the
919  * notmuch_threads_t object. (For consistency, we do provide a
920  * notmuch_threads_destroy function, but there's no good reason
921  * to call it if the query is about to be destroyed).
922  *
923  * @since libnotmuch 5.0 (notmuch 0.25)
924  */
925 notmuch_status_t
926 notmuch_query_search_threads (notmuch_query_t *query,
927                               notmuch_threads_t **out);
928
929 /**
930  * Deprecated alias for notmuch_query_search_threads.
931  *
932  * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please
933  * use notmuch_query_search_threads instead.
934  *
935  */
936 NOTMUCH_DEPRECATED (5, 0)
937 notmuch_status_t
938 notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out);
939
940 /**
941  * Execute a query for messages, returning a notmuch_messages_t object
942  * which can be used to iterate over the results. The returned
943  * messages object is owned by the query and as such, will only be
944  * valid until notmuch_query_destroy.
945  *
946  * Typical usage might be:
947  *
948  *     notmuch_query_t *query;
949  *     notmuch_messages_t *messages;
950  *     notmuch_message_t *message;
951  *
952  *     query = notmuch_query_create (database, query_string);
953  *
954  *     for (messages = notmuch_query_search_messages (query);
955  *          notmuch_messages_valid (messages);
956  *          notmuch_messages_move_to_next (messages))
957  *     {
958  *         message = notmuch_messages_get (messages);
959  *         ....
960  *         notmuch_message_destroy (message);
961  *     }
962  *
963  *     notmuch_query_destroy (query);
964  *
965  * Note: If you are finished with a message before its containing
966  * query, you can call notmuch_message_destroy to clean up some memory
967  * sooner (as in the above example). Otherwise, if your message
968  * objects are long-lived, then you don't need to call
969  * notmuch_message_destroy and all the memory will still be reclaimed
970  * when the query is destroyed.
971  *
972  * Note that there's no explicit destructor needed for the
973  * notmuch_messages_t object. (For consistency, we do provide a
974  * notmuch_messages_destroy function, but there's no good
975  * reason to call it if the query is about to be destroyed).
976  *
977  * If a Xapian exception occurs this function will return NULL.
978  *
979  * @since libnotmuch 5 (notmuch 0.25)
980  */
981 notmuch_status_t
982 notmuch_query_search_messages (notmuch_query_t *query,
983                                notmuch_messages_t **out);
984 /**
985  * Deprecated alias for notmuch_query_search_messages
986  *
987  * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please use
988  * notmuch_query_search_messages instead.
989  *
990  */
991
992 NOTMUCH_DEPRECATED (5, 0)
993 notmuch_status_t
994 notmuch_query_search_messages_st (notmuch_query_t *query,
995                                   notmuch_messages_t **out);
996
997 /**
998  * Destroy a notmuch_query_t along with any associated resources.
999  *
1000  * This will in turn destroy any notmuch_threads_t and
1001  * notmuch_messages_t objects generated by this query, (and in
1002  * turn any notmuch_thread_t and notmuch_message_t objects generated
1003  * from those results, etc.), if such objects haven't already been
1004  * destroyed.
1005  */
1006 void
1007 notmuch_query_destroy (notmuch_query_t *query);
1008
1009 /**
1010  * Is the given 'threads' iterator pointing at a valid thread.
1011  *
1012  * When this function returns TRUE, notmuch_threads_get will return a
1013  * valid object. Whereas when this function returns FALSE,
1014  * notmuch_threads_get will return NULL.
1015  *
1016  * If passed a NULL pointer, this function returns FALSE
1017  *
1018  * See the documentation of notmuch_query_search_threads for example
1019  * code showing how to iterate over a notmuch_threads_t object.
1020  */
1021 notmuch_bool_t
1022 notmuch_threads_valid (notmuch_threads_t *threads);
1023
1024 /**
1025  * Get the current thread from 'threads' as a notmuch_thread_t.
1026  *
1027  * Note: The returned thread belongs to 'threads' and has a lifetime
1028  * identical to it (and the query to which it belongs).
1029  *
1030  * See the documentation of notmuch_query_search_threads for example
1031  * code showing how to iterate over a notmuch_threads_t object.
1032  *
1033  * If an out-of-memory situation occurs, this function will return
1034  * NULL.
1035  */
1036 notmuch_thread_t *
1037 notmuch_threads_get (notmuch_threads_t *threads);
1038
1039 /**
1040  * Move the 'threads' iterator to the next thread.
1041  *
1042  * If 'threads' is already pointing at the last thread then the
1043  * iterator will be moved to a point just beyond that last thread,
1044  * (where notmuch_threads_valid will return FALSE and
1045  * notmuch_threads_get will return NULL).
1046  *
1047  * See the documentation of notmuch_query_search_threads for example
1048  * code showing how to iterate over a notmuch_threads_t object.
1049  */
1050 void
1051 notmuch_threads_move_to_next (notmuch_threads_t *threads);
1052
1053 /**
1054  * Destroy a notmuch_threads_t object.
1055  *
1056  * It's not strictly necessary to call this function. All memory from
1057  * the notmuch_threads_t object will be reclaimed when the
1058  * containing query object is destroyed.
1059  */
1060 void
1061 notmuch_threads_destroy (notmuch_threads_t *threads);
1062
1063 /**
1064  * Return the number of messages matching a search.
1065  *
1066  * This function performs a search and returns the number of matching
1067  * messages.
1068  *
1069  * @returns
1070  *
1071  * NOTMUCH_STATUS_SUCCESS: query completed successfully.
1072  *
1073  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The
1074  *      value of *count is not defined.
1075  *
1076  * @since libnotmuch 5 (notmuch 0.25)
1077  */
1078 notmuch_status_t
1079 notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count);
1080
1081 /**
1082  * Deprecated alias for notmuch_query_count_messages
1083  *
1084  *
1085  * @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please
1086  * use notmuch_query_count_messages instead.
1087  */
1088 NOTMUCH_DEPRECATED (5, 0)
1089 notmuch_status_t
1090 notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count);
1091
1092 /**
1093  * Return the number of threads matching a search.
1094  *
1095  * This function performs a search and returns the number of unique thread IDs
1096  * in the matching messages. This is the same as number of threads matching a
1097  * search.
1098  *
1099  * Note that this is a significantly heavier operation than
1100  * notmuch_query_count_messages{_st}().
1101  *
1102  * @returns
1103  *
1104  * NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value
1105  *      of *count is not defined
1106  *
1107  * NOTMUCH_STATUS_SUCCESS: query completed successfully.
1108  *
1109  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The
1110  *      value of *count is not defined.
1111  *
1112  * @since libnotmuch 5 (notmuch 0.25)
1113  */
1114 notmuch_status_t
1115 notmuch_query_count_threads (notmuch_query_t *query, unsigned *count);
1116
1117 /**
1118  * Deprecated alias for notmuch_query_count_threads
1119  *
1120  * @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please
1121  * use notmuch_query_count_threads_st instead.
1122  */
1123 NOTMUCH_DEPRECATED (5, 0)
1124 notmuch_status_t
1125 notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count);
1126
1127 /**
1128  * Get the thread ID of 'thread'.
1129  *
1130  * The returned string belongs to 'thread' and as such, should not be
1131  * modified by the caller and will only be valid for as long as the
1132  * thread is valid, (which is until notmuch_thread_destroy or until
1133  * the query from which it derived is destroyed).
1134  */
1135 const char *
1136 notmuch_thread_get_thread_id (notmuch_thread_t *thread);
1137
1138 /**
1139  * Get the total number of messages in 'thread'.
1140  *
1141  * This count consists of all messages in the database belonging to
1142  * this thread. Contrast with notmuch_thread_get_matched_messages() .
1143  */
1144 int
1145 notmuch_thread_get_total_messages (notmuch_thread_t *thread);
1146
1147 /**
1148  * Get the total number of files in 'thread'.
1149  *
1150  * This sums notmuch_message_count_files over all messages in the
1151  * thread
1152  * @returns Non-negative integer
1153  * @since libnotmuch 5.0 (notmuch 0.25)
1154  */
1155
1156 int
1157 notmuch_thread_get_total_files (notmuch_thread_t *thread);
1158
1159 /**
1160  * Get a notmuch_messages_t iterator for the top-level messages in
1161  * 'thread' in oldest-first order.
1162  *
1163  * This iterator will not necessarily iterate over all of the messages
1164  * in the thread. It will only iterate over the messages in the thread
1165  * which are not replies to other messages in the thread.
1166  *
1167  * The returned list will be destroyed when the thread is destroyed.
1168  */
1169 notmuch_messages_t *
1170 notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
1171
1172 /**
1173  * Get a notmuch_thread_t iterator for all messages in 'thread' in
1174  * oldest-first order.
1175  *
1176  * The returned list will be destroyed when the thread is destroyed.
1177  */
1178 notmuch_messages_t *
1179 notmuch_thread_get_messages (notmuch_thread_t *thread);
1180
1181 /**
1182  * Get the number of messages in 'thread' that matched the search.
1183  *
1184  * This count includes only the messages in this thread that were
1185  * matched by the search from which the thread was created and were
1186  * not excluded by any exclude tags passed in with the query (see
1187  * notmuch_query_add_tag_exclude). Contrast with
1188  * notmuch_thread_get_total_messages() .
1189  */
1190 int
1191 notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
1192
1193 /**
1194  * Get the authors of 'thread' as a UTF-8 string.
1195  *
1196  * The returned string is a comma-separated list of the names of the
1197  * authors of mail messages in the query results that belong to this
1198  * thread.
1199  *
1200  * The string contains authors of messages matching the query first, then
1201  * non-matched authors (with the two groups separated by '|'). Within
1202  * each group, authors are ordered by date.
1203  *
1204  * The returned string belongs to 'thread' and as such, should not be
1205  * modified by the caller and will only be valid for as long as the
1206  * thread is valid, (which is until notmuch_thread_destroy or until
1207  * the query from which it derived is destroyed).
1208  */
1209 const char *
1210 notmuch_thread_get_authors (notmuch_thread_t *thread);
1211
1212 /**
1213  * Get the subject of 'thread' as a UTF-8 string.
1214  *
1215  * The subject is taken from the first message (according to the query
1216  * order---see notmuch_query_set_sort) in the query results that
1217  * belongs to this thread.
1218  *
1219  * The returned string belongs to 'thread' and as such, should not be
1220  * modified by the caller and will only be valid for as long as the
1221  * thread is valid, (which is until notmuch_thread_destroy or until
1222  * the query from which it derived is destroyed).
1223  */
1224 const char *
1225 notmuch_thread_get_subject (notmuch_thread_t *thread);
1226
1227 /**
1228  * Get the date of the oldest message in 'thread' as a time_t value.
1229  */
1230 time_t
1231 notmuch_thread_get_oldest_date (notmuch_thread_t *thread);
1232
1233 /**
1234  * Get the date of the newest message in 'thread' as a time_t value.
1235  */
1236 time_t
1237 notmuch_thread_get_newest_date (notmuch_thread_t *thread);
1238
1239 /**
1240  * Get the tags for 'thread', returning a notmuch_tags_t object which
1241  * can be used to iterate over all tags.
1242  *
1243  * Note: In the Notmuch database, tags are stored on individual
1244  * messages, not on threads. So the tags returned here will be all
1245  * tags of the messages which matched the search and which belong to
1246  * this thread.
1247  *
1248  * The tags object is owned by the thread and as such, will only be
1249  * valid for as long as the thread is valid, (for example, until
1250  * notmuch_thread_destroy or until the query from which it derived is
1251  * destroyed).
1252  *
1253  * Typical usage might be:
1254  *
1255  *     notmuch_thread_t *thread;
1256  *     notmuch_tags_t *tags;
1257  *     const char *tag;
1258  *
1259  *     thread = notmuch_threads_get (threads);
1260  *
1261  *     for (tags = notmuch_thread_get_tags (thread);
1262  *          notmuch_tags_valid (tags);
1263  *          notmuch_tags_move_to_next (tags))
1264  *     {
1265  *         tag = notmuch_tags_get (tags);
1266  *         ....
1267  *     }
1268  *
1269  *     notmuch_thread_destroy (thread);
1270  *
1271  * Note that there's no explicit destructor needed for the
1272  * notmuch_tags_t object. (For consistency, we do provide a
1273  * notmuch_tags_destroy function, but there's no good reason to call
1274  * it if the message is about to be destroyed).
1275  */
1276 notmuch_tags_t *
1277 notmuch_thread_get_tags (notmuch_thread_t *thread);
1278
1279 /**
1280  * Destroy a notmuch_thread_t object.
1281  */
1282 void
1283 notmuch_thread_destroy (notmuch_thread_t *thread);
1284
1285 /**
1286  * Is the given 'messages' iterator pointing at a valid message.
1287  *
1288  * When this function returns TRUE, notmuch_messages_get will return a
1289  * valid object. Whereas when this function returns FALSE,
1290  * notmuch_messages_get will return NULL.
1291  *
1292  * See the documentation of notmuch_query_search_messages for example
1293  * code showing how to iterate over a notmuch_messages_t object.
1294  */
1295 notmuch_bool_t
1296 notmuch_messages_valid (notmuch_messages_t *messages);
1297
1298 /**
1299  * Get the current message from 'messages' as a notmuch_message_t.
1300  *
1301  * Note: The returned message belongs to 'messages' and has a lifetime
1302  * identical to it (and the query to which it belongs).
1303  *
1304  * See the documentation of notmuch_query_search_messages for example
1305  * code showing how to iterate over a notmuch_messages_t object.
1306  *
1307  * If an out-of-memory situation occurs, this function will return
1308  * NULL.
1309  */
1310 notmuch_message_t *
1311 notmuch_messages_get (notmuch_messages_t *messages);
1312
1313 /**
1314  * Move the 'messages' iterator to the next message.
1315  *
1316  * If 'messages' is already pointing at the last message then the
1317  * iterator will be moved to a point just beyond that last message,
1318  * (where notmuch_messages_valid will return FALSE and
1319  * notmuch_messages_get will return NULL).
1320  *
1321  * See the documentation of notmuch_query_search_messages for example
1322  * code showing how to iterate over a notmuch_messages_t object.
1323  */
1324 void
1325 notmuch_messages_move_to_next (notmuch_messages_t *messages);
1326
1327 /**
1328  * Destroy a notmuch_messages_t object.
1329  *
1330  * It's not strictly necessary to call this function. All memory from
1331  * the notmuch_messages_t object will be reclaimed when the containing
1332  * query object is destroyed.
1333  */
1334 void
1335 notmuch_messages_destroy (notmuch_messages_t *messages);
1336
1337 /**
1338  * Return a list of tags from all messages.
1339  *
1340  * The resulting list is guaranteed not to contain duplicated tags.
1341  *
1342  * WARNING: You can no longer iterate over messages after calling this
1343  * function, because the iterator will point at the end of the list.
1344  * We do not have a function to reset the iterator yet and the only
1345  * way how you can iterate over the list again is to recreate the
1346  * message list.
1347  *
1348  * The function returns NULL on error.
1349  */
1350 notmuch_tags_t *
1351 notmuch_messages_collect_tags (notmuch_messages_t *messages);
1352
1353 /**
1354  * Get the database associated with this message.
1355  *
1356  * @since libnotmuch 5.2 (notmuch 0.27)
1357  */
1358 notmuch_database_t *
1359 notmuch_message_get_database (const notmuch_message_t *message);
1360
1361 /**
1362  * Get the message ID of 'message'.
1363  *
1364  * The returned string belongs to 'message' and as such, should not be
1365  * modified by the caller and will only be valid for as long as the
1366  * message is valid, (which is until the query from which it derived
1367  * is destroyed).
1368  *
1369  * This function will return NULL if triggers an unhandled Xapian
1370  * exception.
1371  */
1372 const char *
1373 notmuch_message_get_message_id (notmuch_message_t *message);
1374
1375 /**
1376  * Get the thread ID of 'message'.
1377  *
1378  * The returned string belongs to 'message' and as such, should not be
1379  * modified by the caller and will only be valid for as long as the
1380  * message is valid, (for example, until the user calls
1381  * notmuch_message_destroy on 'message' or until a query from which it
1382  * derived is destroyed).
1383  *
1384  * This function will return NULL if triggers an unhandled Xapian
1385  * exception.
1386  */
1387 const char *
1388 notmuch_message_get_thread_id (notmuch_message_t *message);
1389
1390 /**
1391  * Get a notmuch_messages_t iterator for all of the replies to
1392  * 'message'.
1393  *
1394  * Note: This call only makes sense if 'message' was ultimately
1395  * obtained from a notmuch_thread_t object, (such as by coming
1396  * directly from the result of calling notmuch_thread_get_
1397  * toplevel_messages or by any number of subsequent
1398  * calls to notmuch_message_get_replies).
1399  *
1400  * If 'message' was obtained through some non-thread means, (such as
1401  * by a call to notmuch_query_search_messages), then this function
1402  * will return NULL.
1403  *
1404  * If there are no replies to 'message', this function will return
1405  * NULL. (Note that notmuch_messages_valid will accept that NULL
1406  * value as legitimate, and simply return FALSE for it.)
1407  *
1408  * This function also returns NULL if it triggers a Xapian exception.
1409  *
1410  * The returned list will be destroyed when the thread is
1411  * destroyed.
1412  */
1413 notmuch_messages_t *
1414 notmuch_message_get_replies (notmuch_message_t *message);
1415
1416 /**
1417  * Get the total number of files associated with a message.
1418  * @returns Non-negative integer for file count.
1419  * @returns Negative integer for error.
1420  * @since libnotmuch 5.0 (notmuch 0.25)
1421  */
1422 int
1423 notmuch_message_count_files (notmuch_message_t *message);
1424
1425 /**
1426  * Get a filename for the email corresponding to 'message'.
1427  *
1428  * The returned filename is an absolute filename, (the initial
1429  * component will match notmuch_database_get_path() ).
1430  *
1431  * The returned string belongs to the message so should not be
1432  * modified or freed by the caller (nor should it be referenced after
1433  * the message is destroyed).
1434  *
1435  * Note: If this message corresponds to multiple files in the mail
1436  * store, (that is, multiple files contain identical message IDs),
1437  * this function will arbitrarily return a single one of those
1438  * filenames. See notmuch_message_get_filenames for returning the
1439  * complete list of filenames.
1440  *
1441  * This function returns NULL if it triggers a Xapian exception.
1442  */
1443 const char *
1444 notmuch_message_get_filename (notmuch_message_t *message);
1445
1446 /**
1447  * Get all filenames for the email corresponding to 'message'.
1448  *
1449  * Returns a notmuch_filenames_t iterator listing all the filenames
1450  * associated with 'message'. These files may not have identical
1451  * content, but each will have the identical Message-ID.
1452  *
1453  * Each filename in the iterator is an absolute filename, (the initial
1454  * component will match notmuch_database_get_path() ).
1455  *
1456  * This function returns NULL if it triggers a Xapian exception.
1457  */
1458 notmuch_filenames_t *
1459 notmuch_message_get_filenames (notmuch_message_t *message);
1460
1461 /**
1462  * Re-index the e-mail corresponding to 'message' using the supplied index options
1463  *
1464  * Returns the status of the re-index operation.  (see the return
1465  * codes documented in notmuch_database_index_file)
1466  *
1467  * After reindexing, the user should discard the message object passed
1468  * in here by calling notmuch_message_destroy, since it refers to the
1469  * original message, not to the reindexed message.
1470  */
1471 notmuch_status_t
1472 notmuch_message_reindex (notmuch_message_t *message,
1473                          notmuch_indexopts_t *indexopts);
1474
1475 /**
1476  * Message flags.
1477  */
1478 typedef enum _notmuch_message_flag {
1479     NOTMUCH_MESSAGE_FLAG_MATCH,
1480     NOTMUCH_MESSAGE_FLAG_EXCLUDED,
1481
1482     /* This message is a "ghost message", meaning it has no filenames
1483      * or content, but we know it exists because it was referenced by
1484      * some other message.  A ghost message has only a message ID and
1485      * thread ID.
1486      */
1487     NOTMUCH_MESSAGE_FLAG_GHOST,
1488 } notmuch_message_flag_t;
1489
1490 /**
1491  * Get a value of a flag for the email corresponding to 'message'.
1492  *
1493  * returns FALSE in case of errors.
1494  *
1495  * @deprecated Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please
1496  * use notmuch_message_get_flag_st instead.
1497  */
1498 NOTMUCH_DEPRECATED(5,3)
1499 notmuch_bool_t
1500 notmuch_message_get_flag (notmuch_message_t *message,
1501                           notmuch_message_flag_t flag);
1502
1503 /**
1504  * Get a value of a flag for the email corresponding to 'message'.
1505  *
1506  * @param message a message object
1507  * @param flag flag to check
1508  * @param is_set pointer to boolean to store flag value.
1509  *
1510  * @retval #NOTMUCH_STATUS_SUCCESS
1511  * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL
1512  * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database
1513  * triggered an exception.
1514  *
1515  * @since libnotmuch 5.3 (notmuch 0.31)
1516  */
1517 notmuch_status_t
1518 notmuch_message_get_flag_st (notmuch_message_t *message,
1519                              notmuch_message_flag_t flag,
1520                              notmuch_bool_t *is_set);
1521
1522 /**
1523  * Set a value of a flag for the email corresponding to 'message'.
1524  */
1525 void
1526 notmuch_message_set_flag (notmuch_message_t *message,
1527                           notmuch_message_flag_t flag, notmuch_bool_t value);
1528
1529 /**
1530  * Get the date of 'message' as a time_t value.
1531  *
1532  * For the original textual representation of the Date header from the
1533  * message call notmuch_message_get_header() with a header value of
1534  * "date".
1535  *
1536  * Returns 0 in case of error.
1537  */
1538 time_t
1539 notmuch_message_get_date (notmuch_message_t *message);
1540
1541 /**
1542  * Get the value of the specified header from 'message' as a UTF-8 string.
1543  *
1544  * Common headers are stored in the database when the message is
1545  * indexed and will be returned from the database.  Other headers will
1546  * be read from the actual message file.
1547  *
1548  * The header name is case insensitive.
1549  *
1550  * The returned string belongs to the message so should not be
1551  * modified or freed by the caller (nor should it be referenced after
1552  * the message is destroyed).
1553  *
1554  * Returns an empty string ("") if the message does not contain a
1555  * header line matching 'header'. Returns NULL if any error occurs.
1556  */
1557 const char *
1558 notmuch_message_get_header (notmuch_message_t *message, const char *header);
1559
1560 /**
1561  * Get the tags for 'message', returning a notmuch_tags_t object which
1562  * can be used to iterate over all tags.
1563  *
1564  * The tags object is owned by the message and as such, will only be
1565  * valid for as long as the message is valid, (which is until the
1566  * query from which it derived is destroyed).
1567  *
1568  * Typical usage might be:
1569  *
1570  *     notmuch_message_t *message;
1571  *     notmuch_tags_t *tags;
1572  *     const char *tag;
1573  *
1574  *     message = notmuch_database_find_message (database, message_id);
1575  *
1576  *     for (tags = notmuch_message_get_tags (message);
1577  *          notmuch_tags_valid (tags);
1578  *          notmuch_tags_move_to_next (tags))
1579  *     {
1580  *         tag = notmuch_tags_get (tags);
1581  *         ....
1582  *     }
1583  *
1584  *     notmuch_message_destroy (message);
1585  *
1586  * Note that there's no explicit destructor needed for the
1587  * notmuch_tags_t object. (For consistency, we do provide a
1588  * notmuch_tags_destroy function, but there's no good reason to call
1589  * it if the message is about to be destroyed).
1590  */
1591 notmuch_tags_t *
1592 notmuch_message_get_tags (notmuch_message_t *message);
1593
1594 /**
1595  * The longest possible tag value.
1596  */
1597 #define NOTMUCH_TAG_MAX 200
1598
1599 /**
1600  * Add a tag to the given message.
1601  *
1602  * Return value:
1603  *
1604  * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message
1605  *
1606  * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
1607  *
1608  * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
1609  *      (exceeds NOTMUCH_TAG_MAX)
1610  *
1611  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1612  *      mode so message cannot be modified.
1613  */
1614 notmuch_status_t
1615 notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
1616
1617 /**
1618  * Remove a tag from the given message.
1619  *
1620  * Return value:
1621  *
1622  * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message
1623  *
1624  * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
1625  *
1626  * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
1627  *      (exceeds NOTMUCH_TAG_MAX)
1628  *
1629  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1630  *      mode so message cannot be modified.
1631  */
1632 notmuch_status_t
1633 notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
1634
1635 /**
1636  * Remove all tags from the given message.
1637  *
1638  * See notmuch_message_freeze for an example showing how to safely
1639  * replace tag values.
1640  *
1641  * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
1642  *      read-only mode so message cannot be modified.
1643  * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an execption was thrown
1644  *      accessing the database.
1645  */
1646 notmuch_status_t
1647 notmuch_message_remove_all_tags (notmuch_message_t *message);
1648
1649 /**
1650  * Add/remove tags according to maildir flags in the message filename(s).
1651  *
1652  * This function examines the filenames of 'message' for maildir
1653  * flags, and adds or removes tags on 'message' as follows when these
1654  * flags are present:
1655  *
1656  *      Flag    Action if present
1657  *      ----    -----------------
1658  *      'D'     Adds the "draft" tag to the message
1659  *      'F'     Adds the "flagged" tag to the message
1660  *      'P'     Adds the "passed" tag to the message
1661  *      'R'     Adds the "replied" tag to the message
1662  *      'S'     Removes the "unread" tag from the message
1663  *
1664  * For each flag that is not present, the opposite action (add/remove)
1665  * is performed for the corresponding tags.
1666  *
1667  * Flags are identified as trailing components of the filename after a
1668  * sequence of ":2,".
1669  *
1670  * If there are multiple filenames associated with this message, the
1671  * flag is considered present if it appears in one or more
1672  * filenames. (That is, the flags from the multiple filenames are
1673  * combined with the logical OR operator.)
1674  *
1675  * A client can ensure that notmuch database tags remain synchronized
1676  * with maildir flags by calling this function after each call to
1677  * notmuch_database_index_file. See also
1678  * notmuch_message_tags_to_maildir_flags for synchronizing tag changes
1679  * back to maildir flags.
1680  */
1681 notmuch_status_t
1682 notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
1683
1684 /**
1685  * return TRUE if any filename of 'message' has maildir flag 'flag',
1686  * FALSE otherwise.
1687  *
1688  * Deprecated wrapper for notmuch_message_has_maildir_flag_st
1689  *
1690  * @returns FALSE in case of error
1691  * @deprecated libnotmuch 5.3 (notmuch 0.31)
1692  */
1693 NOTMUCH_DEPRECATED(5, 3)
1694 notmuch_bool_t
1695 notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag);
1696
1697 /**
1698  * check message for maildir flag
1699  *
1700  * @param [in,out]      message message to check
1701  * @param [in] flag     flag to check for
1702  * @param [out] is_set  pointer to boolean
1703  *
1704  * @retval #NOTMUCH_STATUS_SUCCESS
1705  * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL
1706  * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database
1707  * triggered an exception.
1708  */
1709 notmuch_status_t
1710 notmuch_message_has_maildir_flag_st (notmuch_message_t *message,
1711                                      char flag,
1712                                      notmuch_bool_t *is_set);
1713
1714 /**
1715  * Rename message filename(s) to encode tags as maildir flags.
1716  *
1717  * Specifically, for each filename corresponding to this message:
1718  *
1719  * If the filename is not in a maildir directory, do nothing.  (A
1720  * maildir directory is determined as a directory named "new" or
1721  * "cur".) Similarly, if the filename has invalid maildir info,
1722  * (repeated or outof-ASCII-order flag characters after ":2,"), then
1723  * do nothing.
1724  *
1725  * If the filename is in a maildir directory, rename the file so that
1726  * its filename ends with the sequence ":2," followed by zero or more
1727  * of the following single-character flags (in ASCII order):
1728  *
1729  *   * flag 'D' iff the message has the "draft" tag
1730  *   * flag 'F' iff the message has the "flagged" tag
1731  *   * flag 'P' iff the message has the "passed" tag
1732  *   * flag 'R' iff the message has the "replied" tag
1733  *   * flag 'S' iff the message does not have the "unread" tag
1734  *
1735  * Any existing flags unmentioned in the list above will be preserved
1736  * in the renaming.
1737  *
1738  * Also, if this filename is in a directory named "new", rename it to
1739  * be within the neighboring directory named "cur".
1740  *
1741  * A client can ensure that maildir filename flags remain synchronized
1742  * with notmuch database tags by calling this function after changing
1743  * tags, (after calls to notmuch_message_add_tag,
1744  * notmuch_message_remove_tag, or notmuch_message_freeze/
1745  * notmuch_message_thaw). See also notmuch_message_maildir_flags_to_tags
1746  * for synchronizing maildir flag changes back to tags.
1747  */
1748 notmuch_status_t
1749 notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);
1750
1751 /**
1752  * Freeze the current state of 'message' within the database.
1753  *
1754  * This means that changes to the message state, (via
1755  * notmuch_message_add_tag, notmuch_message_remove_tag, and
1756  * notmuch_message_remove_all_tags), will not be committed to the
1757  * database until the message is thawed with notmuch_message_thaw.
1758  *
1759  * Multiple calls to freeze/thaw are valid and these calls will
1760  * "stack". That is there must be as many calls to thaw as to freeze
1761  * before a message is actually thawed.
1762  *
1763  * The ability to do freeze/thaw allows for safe transactions to
1764  * change tag values. For example, explicitly setting a message to
1765  * have a given set of tags might look like this:
1766  *
1767  *    notmuch_message_freeze (message);
1768  *
1769  *    notmuch_message_remove_all_tags (message);
1770  *
1771  *    for (i = 0; i < NUM_TAGS; i++)
1772  *        notmuch_message_add_tag (message, tags[i]);
1773  *
1774  *    notmuch_message_thaw (message);
1775  *
1776  * With freeze/thaw used like this, the message in the database is
1777  * guaranteed to have either the full set of original tag values, or
1778  * the full set of new tag values, but nothing in between.
1779  *
1780  * Imagine the example above without freeze/thaw and the operation
1781  * somehow getting interrupted. This could result in the message being
1782  * left with no tags if the interruption happened after
1783  * notmuch_message_remove_all_tags but before notmuch_message_add_tag.
1784  *
1785  * Return value:
1786  *
1787  * NOTMUCH_STATUS_SUCCESS: Message successfully frozen.
1788  *
1789  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1790  *      mode so message cannot be modified.
1791  */
1792 notmuch_status_t
1793 notmuch_message_freeze (notmuch_message_t *message);
1794
1795 /**
1796  * Thaw the current 'message', synchronizing any changes that may have
1797  * occurred while 'message' was frozen into the notmuch database.
1798  *
1799  * See notmuch_message_freeze for an example of how to use this
1800  * function to safely provide tag changes.
1801  *
1802  * Multiple calls to freeze/thaw are valid and these calls with
1803  * "stack". That is there must be as many calls to thaw as to freeze
1804  * before a message is actually thawed.
1805  *
1806  * Return value:
1807  *
1808  * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least
1809  *      its frozen count has successfully been reduced by 1).
1810  *
1811  * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw
1812  *      an unfrozen message. That is, there have been an unbalanced
1813  *      number of calls to notmuch_message_freeze and
1814  *      notmuch_message_thaw.
1815  */
1816 notmuch_status_t
1817 notmuch_message_thaw (notmuch_message_t *message);
1818
1819 /**
1820  * Destroy a notmuch_message_t object.
1821  *
1822  * It can be useful to call this function in the case of a single
1823  * query object with many messages in the result, (such as iterating
1824  * over the entire database). Otherwise, it's fine to never call this
1825  * function and there will still be no memory leaks. (The memory from
1826  * the messages get reclaimed when the containing query is destroyed.)
1827  */
1828 void
1829 notmuch_message_destroy (notmuch_message_t *message);
1830
1831 /**
1832  * @name Message Properties
1833  *
1834  * This interface provides the ability to attach arbitrary (key,value)
1835  * string pairs to a message, to remove such pairs, and to iterate
1836  * over them.  The caller should take some care as to what keys they
1837  * add or delete values for, as other subsystems or extensions may
1838  * depend on these properties.
1839  *
1840  * Please see notmuch-properties(7) for more details about specific
1841  * properties and conventions around their use.
1842  *
1843  */
1844 /**@{*/
1845 /**
1846  * Retrieve the value for a single property key
1847  *
1848  * *value* is set to a string owned by the message or NULL if there is
1849  * no such key. In the case of multiple values for the given key, the
1850  * first one is retrieved.
1851  *
1852  * @returns
1853  * - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL.
1854  * - NOTMUCH_STATUS_SUCCESS: No error occurred.
1855  * @since libnotmuch 4.4 (notmuch 0.23)
1856  */
1857 notmuch_status_t
1858 notmuch_message_get_property (notmuch_message_t *message, const char *key, const char **value);
1859
1860 /**
1861  * Add a (key,value) pair to a message
1862  *
1863  * @returns
1864  * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
1865  * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
1866  * - NOTMUCH_STATUS_SUCCESS: No error occurred.
1867  * @since libnotmuch 4.4 (notmuch 0.23)
1868  */
1869 notmuch_status_t
1870 notmuch_message_add_property (notmuch_message_t *message, const char *key, const char *value);
1871
1872 /**
1873  * Remove a (key,value) pair from a message.
1874  *
1875  * It is not an error to remove a non-existant (key,value) pair
1876  *
1877  * @returns
1878  * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
1879  * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
1880  * - NOTMUCH_STATUS_SUCCESS: No error occurred.
1881  * @since libnotmuch 4.4 (notmuch 0.23)
1882  */
1883 notmuch_status_t
1884 notmuch_message_remove_property (notmuch_message_t *message, const char *key, const char *value);
1885
1886 /**
1887  * Remove all (key,value) pairs from the given message.
1888  *
1889  * @param[in,out] message  message to operate on.
1890  * @param[in]     key      key to delete properties for. If NULL, delete
1891  *                         properties for all keys
1892  * @returns
1893  * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
1894  *   read-only mode so message cannot be modified.
1895  * - NOTMUCH_STATUS_SUCCESS: No error occurred.
1896  *
1897  * @since libnotmuch 4.4 (notmuch 0.23)
1898  */
1899 notmuch_status_t
1900 notmuch_message_remove_all_properties (notmuch_message_t *message, const char *key);
1901
1902 /**
1903  * Remove all (prefix*,value) pairs from the given message
1904  *
1905  * @param[in,out] message  message to operate on.
1906  * @param[in]     prefix   delete properties with keys that start with prefix.
1907  *                         If NULL, delete all properties
1908  * @returns
1909  * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
1910  *   read-only mode so message cannot be modified.
1911  * - NOTMUCH_STATUS_SUCCESS: No error occurred.
1912  *
1913  * @since libnotmuch 5.1 (notmuch 0.26)
1914  */
1915 notmuch_status_t
1916 notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, const char *prefix);
1917
1918 /**
1919  * Opaque message property iterator
1920  */
1921 typedef struct _notmuch_string_map_iterator notmuch_message_properties_t;
1922
1923 /**
1924  * Get the properties for *message*, returning a
1925  * notmuch_message_properties_t object which can be used to iterate
1926  * over all properties.
1927  *
1928  * The notmuch_message_properties_t object is owned by the message and
1929  * as such, will only be valid for as long as the message is valid,
1930  * (which is until the query from which it derived is destroyed).
1931  *
1932  * @param[in] message  The message to examine
1933  * @param[in] key      key or key prefix
1934  * @param[in] exact    if TRUE, require exact match with key. Otherwise
1935  *                     treat as prefix.
1936  *
1937  * Typical usage might be:
1938  *
1939  *     notmuch_message_properties_t *list;
1940  *
1941  *     for (list = notmuch_message_get_properties (message, "testkey1", TRUE);
1942  *          notmuch_message_properties_valid (list); notmuch_message_properties_move_to_next (list)) {
1943  *        printf("%s\n", notmuch_message_properties_value(list));
1944  *     }
1945  *
1946  *     notmuch_message_properties_destroy (list);
1947  *
1948  * Note that there's no explicit destructor needed for the
1949  * notmuch_message_properties_t object. (For consistency, we do
1950  * provide a notmuch_message_properities_destroy function, but there's
1951  * no good reason to call it if the message is about to be destroyed).
1952  *
1953  * @since libnotmuch 4.4 (notmuch 0.23)
1954  */
1955 notmuch_message_properties_t *
1956 notmuch_message_get_properties (notmuch_message_t *message, const char *key, notmuch_bool_t exact);
1957
1958 /**
1959  * Return the number of properties named "key" belonging to the specific message.
1960  *
1961  * @param[in] message  The message to examine
1962  * @param[in] key      key to count
1963  * @param[out] count   The number of matching properties associated with this message.
1964  *
1965  * @returns
1966  *
1967  * NOTMUCH_STATUS_SUCCESS: successful count, possibly some other error.
1968  *
1969  * @since libnotmuch 5.2 (notmuch 0.27)
1970  */
1971 notmuch_status_t
1972 notmuch_message_count_properties (notmuch_message_t *message, const char *key, unsigned int *count);
1973
1974 /**
1975  * Is the given *properties* iterator pointing at a valid (key,value)
1976  * pair.
1977  *
1978  * When this function returns TRUE,
1979  * notmuch_message_properties_{key,value} will return a valid string,
1980  * and notmuch_message_properties_move_to_next will do what it
1981  * says. Whereas when this function returns FALSE, calling any of
1982  * these functions results in undefined behaviour.
1983  *
1984  * See the documentation of notmuch_message_get_properties for example
1985  * code showing how to iterate over a notmuch_message_properties_t
1986  * object.
1987  *
1988  * @since libnotmuch 4.4 (notmuch 0.23)
1989  */
1990 notmuch_bool_t
1991 notmuch_message_properties_valid (notmuch_message_properties_t *properties);
1992
1993 /**
1994  * Move the *properties* iterator to the next (key,value) pair
1995  *
1996  * If *properties* is already pointing at the last pair then the iterator
1997  * will be moved to a point just beyond that last pair, (where
1998  * notmuch_message_properties_valid will return FALSE).
1999  *
2000  * See the documentation of notmuch_message_get_properties for example
2001  * code showing how to iterate over a notmuch_message_properties_t object.
2002  *
2003  * @since libnotmuch 4.4 (notmuch 0.23)
2004  */
2005 void
2006 notmuch_message_properties_move_to_next (notmuch_message_properties_t *properties);
2007
2008 /**
2009  * Return the key from the current (key,value) pair.
2010  *
2011  * this could be useful if iterating for a prefix
2012  *
2013  * @since libnotmuch 4.4 (notmuch 0.23)
2014  */
2015 const char *
2016 notmuch_message_properties_key (notmuch_message_properties_t *properties);
2017
2018 /**
2019  * Return the value from the current (key,value) pair.
2020  *
2021  * This could be useful if iterating for a prefix.
2022  *
2023  * @since libnotmuch 4.4 (notmuch 0.23)
2024  */
2025 const char *
2026 notmuch_message_properties_value (notmuch_message_properties_t *properties);
2027
2028
2029 /**
2030  * Destroy a notmuch_message_properties_t object.
2031  *
2032  * It's not strictly necessary to call this function. All memory from
2033  * the notmuch_message_properties_t object will be reclaimed when the
2034  * containing message object is destroyed.
2035  *
2036  * @since libnotmuch 4.4 (notmuch 0.23)
2037  */
2038 void
2039 notmuch_message_properties_destroy (notmuch_message_properties_t *properties);
2040
2041 /**@}*/
2042
2043 /**
2044  * Is the given 'tags' iterator pointing at a valid tag.
2045  *
2046  * When this function returns TRUE, notmuch_tags_get will return a
2047  * valid string. Whereas when this function returns FALSE,
2048  * notmuch_tags_get will return NULL.
2049  *
2050  * See the documentation of notmuch_message_get_tags for example code
2051  * showing how to iterate over a notmuch_tags_t object.
2052  */
2053 notmuch_bool_t
2054 notmuch_tags_valid (notmuch_tags_t *tags);
2055
2056 /**
2057  * Get the current tag from 'tags' as a string.
2058  *
2059  * Note: The returned string belongs to 'tags' and has a lifetime
2060  * identical to it (and the query to which it ultimately belongs).
2061  *
2062  * See the documentation of notmuch_message_get_tags for example code
2063  * showing how to iterate over a notmuch_tags_t object.
2064  */
2065 const char *
2066 notmuch_tags_get (notmuch_tags_t *tags);
2067
2068 /**
2069  * Move the 'tags' iterator to the next tag.
2070  *
2071  * If 'tags' is already pointing at the last tag then the iterator
2072  * will be moved to a point just beyond that last tag, (where
2073  * notmuch_tags_valid will return FALSE and notmuch_tags_get will
2074  * return NULL).
2075  *
2076  * See the documentation of notmuch_message_get_tags for example code
2077  * showing how to iterate over a notmuch_tags_t object.
2078  */
2079 void
2080 notmuch_tags_move_to_next (notmuch_tags_t *tags);
2081
2082 /**
2083  * Destroy a notmuch_tags_t object.
2084  *
2085  * It's not strictly necessary to call this function. All memory from
2086  * the notmuch_tags_t object will be reclaimed when the containing
2087  * message or query objects are destroyed.
2088  */
2089 void
2090 notmuch_tags_destroy (notmuch_tags_t *tags);
2091
2092 /**
2093  * Store an mtime within the database for 'directory'.
2094  *
2095  * The 'directory' should be an object retrieved from the database
2096  * with notmuch_database_get_directory for a particular path.
2097  *
2098  * The intention is for the caller to use the mtime to allow efficient
2099  * identification of new messages to be added to the database. The
2100  * recommended usage is as follows:
2101  *
2102  *   o Read the mtime of a directory from the filesystem
2103  *
2104  *   o Call index_file for all mail files in the directory
2105  *
2106  *   o Call notmuch_directory_set_mtime with the mtime read from the
2107  *     filesystem.
2108  *
2109  * Then, when wanting to check for updates to the directory in the
2110  * future, the client can call notmuch_directory_get_mtime and know
2111  * that it only needs to add files if the mtime of the directory and
2112  * files are newer than the stored timestamp.
2113  *
2114  * Note: The notmuch_directory_get_mtime function does not allow the
2115  * caller to distinguish a timestamp of 0 from a non-existent
2116  * timestamp. So don't store a timestamp of 0 unless you are
2117  * comfortable with that.
2118  *
2119  * Return value:
2120  *
2121  * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database.
2122  *
2123  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
2124  *      occurred, mtime not stored.
2125  *
2126  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
2127  *      mode so directory mtime cannot be modified.
2128  */
2129 notmuch_status_t
2130 notmuch_directory_set_mtime (notmuch_directory_t *directory,
2131                              time_t mtime);
2132
2133 /**
2134  * Get the mtime of a directory, (as previously stored with
2135  * notmuch_directory_set_mtime).
2136  *
2137  * Returns 0 if no mtime has previously been stored for this
2138  * directory.
2139  */
2140 time_t
2141 notmuch_directory_get_mtime (notmuch_directory_t *directory);
2142
2143 /**
2144  * Get a notmuch_filenames_t iterator listing all the filenames of
2145  * messages in the database within the given directory.
2146  *
2147  * The returned filenames will be the basename-entries only (not
2148  * complete paths).
2149  */
2150 notmuch_filenames_t *
2151 notmuch_directory_get_child_files (notmuch_directory_t *directory);
2152
2153 /**
2154  * Get a notmuch_filenames_t iterator listing all the filenames of
2155  * sub-directories in the database within the given directory.
2156  *
2157  * The returned filenames will be the basename-entries only (not
2158  * complete paths).
2159  */
2160 notmuch_filenames_t *
2161 notmuch_directory_get_child_directories (notmuch_directory_t *directory);
2162
2163 /**
2164  * Delete directory document from the database, and destroy the
2165  * notmuch_directory_t object. Assumes any child directories and files
2166  * have been deleted by the caller.
2167  *
2168  * @since libnotmuch 4.3 (notmuch 0.21)
2169  */
2170 notmuch_status_t
2171 notmuch_directory_delete (notmuch_directory_t *directory);
2172
2173 /**
2174  * Destroy a notmuch_directory_t object.
2175  */
2176 void
2177 notmuch_directory_destroy (notmuch_directory_t *directory);
2178
2179 /**
2180  * Is the given 'filenames' iterator pointing at a valid filename.
2181  *
2182  * When this function returns TRUE, notmuch_filenames_get will return
2183  * a valid string. Whereas when this function returns FALSE,
2184  * notmuch_filenames_get will return NULL.
2185  *
2186  * It is acceptable to pass NULL for 'filenames', in which case this
2187  * function will always return FALSE.
2188  */
2189 notmuch_bool_t
2190 notmuch_filenames_valid (notmuch_filenames_t *filenames);
2191
2192 /**
2193  * Get the current filename from 'filenames' as a string.
2194  *
2195  * Note: The returned string belongs to 'filenames' and has a lifetime
2196  * identical to it (and the directory to which it ultimately belongs).
2197  *
2198  * It is acceptable to pass NULL for 'filenames', in which case this
2199  * function will always return NULL.
2200  */
2201 const char *
2202 notmuch_filenames_get (notmuch_filenames_t *filenames);
2203
2204 /**
2205  * Move the 'filenames' iterator to the next filename.
2206  *
2207  * If 'filenames' is already pointing at the last filename then the
2208  * iterator will be moved to a point just beyond that last filename,
2209  * (where notmuch_filenames_valid will return FALSE and
2210  * notmuch_filenames_get will return NULL).
2211  *
2212  * It is acceptable to pass NULL for 'filenames', in which case this
2213  * function will do nothing.
2214  */
2215 void
2216 notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);
2217
2218 /**
2219  * Destroy a notmuch_filenames_t object.
2220  *
2221  * It's not strictly necessary to call this function. All memory from
2222  * the notmuch_filenames_t object will be reclaimed when the
2223  * containing directory object is destroyed.
2224  *
2225  * It is acceptable to pass NULL for 'filenames', in which case this
2226  * function will do nothing.
2227  */
2228 void
2229 notmuch_filenames_destroy (notmuch_filenames_t *filenames);
2230
2231
2232 /**
2233  * set config 'key' to 'value'
2234  *
2235  * @since libnotmuch 4.4 (notmuch 0.23)
2236  */
2237 notmuch_status_t
2238 notmuch_database_set_config (notmuch_database_t *db, const char *key, const char *value);
2239
2240 /**
2241  * retrieve config item 'key', assign to  'value'
2242  *
2243  * keys which have not been previously set with n_d_set_config will
2244  * return an empty string.
2245  *
2246  * return value is allocated by malloc and should be freed by the
2247  * caller.
2248  *
2249  * @since libnotmuch 4.4 (notmuch 0.23)
2250  */
2251 notmuch_status_t
2252 notmuch_database_get_config (notmuch_database_t *db, const char *key, char **value);
2253
2254 /**
2255  * Create an iterator for all config items with keys matching a given prefix
2256  *
2257  * @since libnotmuch 4.4 (notmuch 0.23)
2258  */
2259 notmuch_status_t
2260 notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix, notmuch_config_list_t **out);
2261
2262 /**
2263  * Is 'config_list' iterator valid (i.e. _key, _value, _move_to_next can be called).
2264  *
2265  * @since libnotmuch 4.4 (notmuch 0.23)
2266  */
2267 notmuch_bool_t
2268 notmuch_config_list_valid (notmuch_config_list_t *config_list);
2269
2270 /**
2271  * return key for current config pair
2272  *
2273  * return value is owned by the iterator, and will be destroyed by the
2274  * next call to notmuch_config_list_key or notmuch_config_list_destroy.
2275  *
2276  * @since libnotmuch 4.4 (notmuch 0.23)
2277  */
2278 const char *
2279 notmuch_config_list_key (notmuch_config_list_t *config_list);
2280
2281 /**
2282  * return 'value' for current config pair
2283  *
2284  * return value is owned by the iterator, and will be destroyed by the
2285  * next call to notmuch_config_list_value or notmuch config_list_destroy
2286  *
2287  * @since libnotmuch 4.4 (notmuch 0.23)
2288  */
2289 const char *
2290 notmuch_config_list_value (notmuch_config_list_t *config_list);
2291
2292
2293 /**
2294  * move 'config_list' iterator to the next pair
2295  *
2296  * @since libnotmuch 4.4 (notmuch 0.23)
2297  */
2298 void
2299 notmuch_config_list_move_to_next (notmuch_config_list_t *config_list);
2300
2301 /**
2302  * free any resources held by 'config_list'
2303  *
2304  * @since libnotmuch 4.4 (notmuch 0.23)
2305  */
2306 void
2307 notmuch_config_list_destroy (notmuch_config_list_t *config_list);
2308
2309
2310 /**
2311  * get the current default indexing options for a given database.
2312  *
2313  * This object will survive until the database itself is destroyed,
2314  * but the caller may also release it earlier with
2315  * notmuch_indexopts_destroy.
2316  *
2317  * This object represents a set of options on how a message can be
2318  * added to the index.  At the moment it is a featureless stub.
2319  *
2320  * @since libnotmuch 5.1 (notmuch 0.26)
2321  */
2322 notmuch_indexopts_t *
2323 notmuch_database_get_default_indexopts (notmuch_database_t *db);
2324
2325 /**
2326  * Stating a policy about how to decrypt messages.
2327  *
2328  * See index.decrypt in notmuch-config(1) for more details.
2329  */
2330 typedef enum {
2331     NOTMUCH_DECRYPT_FALSE,
2332     NOTMUCH_DECRYPT_TRUE,
2333     NOTMUCH_DECRYPT_AUTO,
2334     NOTMUCH_DECRYPT_NOSTASH,
2335 } notmuch_decryption_policy_t;
2336
2337 /**
2338  * Specify whether to decrypt encrypted parts while indexing.
2339  *
2340  * Be aware that the index is likely sufficient to reconstruct the
2341  * cleartext of the message itself, so please ensure that the notmuch
2342  * message index is adequately protected. DO NOT SET THIS FLAG TO TRUE
2343  * without considering the security of your index.
2344  *
2345  * @since libnotmuch 5.1 (notmuch 0.26)
2346  */
2347 notmuch_status_t
2348 notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts,
2349                                       notmuch_decryption_policy_t decrypt_policy);
2350
2351 /**
2352  * Return whether to decrypt encrypted parts while indexing.
2353  * see notmuch_indexopts_set_decrypt_policy.
2354  *
2355  * @since libnotmuch 5.1 (notmuch 0.26)
2356  */
2357 notmuch_decryption_policy_t
2358 notmuch_indexopts_get_decrypt_policy (const notmuch_indexopts_t *indexopts);
2359
2360 /**
2361  * Destroy a notmuch_indexopts_t object.
2362  *
2363  * @since libnotmuch 5.1 (notmuch 0.26)
2364  */
2365 void
2366 notmuch_indexopts_destroy (notmuch_indexopts_t *options);
2367
2368
2369 /**
2370  * interrogate the library for compile time features
2371  *
2372  * @since libnotmuch 4.4 (notmuch 0.23)
2373  */
2374 notmuch_bool_t
2375 notmuch_built_with (const char *name);
2376 /**@}*/
2377
2378 #pragma GCC visibility pop
2379
2380 NOTMUCH_END_DECLS
2381
2382 #endif