lib: Replace NOTMUCH_*_VERSION with LIBNOTMUCH_*_VERSION
[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 http://www.gnu.org/licenses/ .
17  *
18  * Author: Carl Worth <cworth@cworth.org>
19  */
20
21 #ifndef NOTMUCH_H
22 #define NOTMUCH_H
23
24 #ifdef  __cplusplus
25 # define NOTMUCH_BEGIN_DECLS  extern "C" {
26 # define NOTMUCH_END_DECLS    }
27 #else
28 # define NOTMUCH_BEGIN_DECLS
29 # define NOTMUCH_END_DECLS
30 #endif
31
32 NOTMUCH_BEGIN_DECLS
33
34 #include <time.h>
35
36 #ifndef FALSE
37 #define FALSE 0
38 #endif
39
40 #ifndef TRUE
41 #define TRUE 1
42 #endif
43
44 /*
45  * The library version number.  This must agree with the soname
46  * version in Makefile.local.
47  */
48 #define LIBNOTMUCH_MAJOR_VERSION        3
49 #define LIBNOTMUCH_MINOR_VERSION        0
50 #define LIBNOTMUCH_MICRO_VERSION        0
51
52 /*
53  * Check the version of the notmuch library being compiled against.
54  *
55  * Return true if the library being compiled against is of the
56  * specified version or above. For example:
57  *
58  * #if LIBNOTMUCH_CHECK_VERSION(3, 0, 0)
59  *     (code requiring libnotmuch 3.0.0 or above)
60  * #endif
61  *
62  * LIBNOTMUCH_CHECK_VERSION has been defined since version 3.0.0; you
63  * can use #if !defined(NOTMUCH_CHECK_VERSION) to check for versions
64  * prior to that.
65  */
66 #define LIBNOTMUCH_CHECK_VERSION (major, minor, micro)                  \
67     (LIBNOTMUCH_MAJOR_VERSION > (major) ||                                      \
68      (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION > (minor)) || \
69      (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION == (minor) && \
70       LIBNOTMUCH_MICRO_VERSION >= (micro)))
71
72 typedef int notmuch_bool_t;
73
74 /* Status codes used for the return values of most functions.
75  *
76  * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function
77  * completed without error. Any other value indicates an error as
78  * follows:
79  *
80  * NOTMUCH_STATUS_SUCCESS: No error occurred.
81  *
82  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory
83  *
84  * XXX: We don't really want to expose this lame XAPIAN_EXCEPTION
85  * value. Instead we should map to things like DATABASE_LOCKED or
86  * whatever.
87  *
88  * NOTMUCH_STATUS_READ_ONLY_DATABASE: An attempt was made to write to
89  *      a database opened in read-only mode.
90  *
91  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
92  *
93  * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to read or
94  *      write to a file (this could be file not found, permission
95  *      denied, etc.)
96  *
97  * NOTMUCH_STATUS_FILE_NOT_EMAIL: A file was presented that doesn't
98  *      appear to be an email message.
99  *
100  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: A file contains a message ID
101  *      that is identical to a message already in the database.
102  *
103  * NOTMUCH_STATUS_NULL_POINTER: The user erroneously passed a NULL
104  *      pointer to a notmuch function.
105  *
106  * NOTMUCH_STATUS_TAG_TOO_LONG: A tag value is too long (exceeds
107  *      NOTMUCH_TAG_MAX)
108  *
109  * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: The notmuch_message_thaw
110  *      function has been called more times than notmuch_message_freeze.
111  *
112  * NOTMUCH_STATUS_UNBALANCED_ATOMIC: notmuch_database_end_atomic has
113  *      been called more times than notmuch_database_begin_atomic.
114  *
115  * And finally:
116  *
117  * NOTMUCH_STATUS_LAST_STATUS: Not an actual status value. Just a way
118  *      to find out how many valid status values there are.
119  */
120 typedef enum _notmuch_status {
121     NOTMUCH_STATUS_SUCCESS = 0,
122     NOTMUCH_STATUS_OUT_OF_MEMORY,
123     NOTMUCH_STATUS_READ_ONLY_DATABASE,
124     NOTMUCH_STATUS_XAPIAN_EXCEPTION,
125     NOTMUCH_STATUS_FILE_ERROR,
126     NOTMUCH_STATUS_FILE_NOT_EMAIL,
127     NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID,
128     NOTMUCH_STATUS_NULL_POINTER,
129     NOTMUCH_STATUS_TAG_TOO_LONG,
130     NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
131     NOTMUCH_STATUS_UNBALANCED_ATOMIC,
132     NOTMUCH_STATUS_UNSUPPORTED_OPERATION,
133
134     NOTMUCH_STATUS_LAST_STATUS
135 } notmuch_status_t;
136
137 /* Get a string representation of a notmuch_status_t value.
138  *
139  * The result is read-only.
140  */
141 const char *
142 notmuch_status_to_string (notmuch_status_t status);
143
144 /* Various opaque data types. For each notmuch_<foo>_t see the various
145  * notmuch_<foo> functions below. */
146 typedef struct _notmuch_database notmuch_database_t;
147 typedef struct _notmuch_query notmuch_query_t;
148 typedef struct _notmuch_threads notmuch_threads_t;
149 typedef struct _notmuch_thread notmuch_thread_t;
150 typedef struct _notmuch_messages notmuch_messages_t;
151 typedef struct _notmuch_message notmuch_message_t;
152 typedef struct _notmuch_tags notmuch_tags_t;
153 typedef struct _notmuch_directory notmuch_directory_t;
154 typedef struct _notmuch_filenames notmuch_filenames_t;
155
156 /* Create a new, empty notmuch database located at 'path'.
157  *
158  * The path should be a top-level directory to a collection of
159  * plain-text email messages (one message per file). This call will
160  * create a new ".notmuch" directory within 'path' where notmuch will
161  * store its data.
162  *
163  * After a successful call to notmuch_database_create, the returned
164  * database will be open so the caller should call
165  * notmuch_database_destroy when finished with it.
166  *
167  * The database will not yet have any data in it
168  * (notmuch_database_create itself is a very cheap function). Messages
169  * contained within 'path' can be added to the database by calling
170  * notmuch_database_add_message.
171  *
172  * In case of any failure, this function returns an error status and
173  * sets *database to NULL (after printing an error message on stderr).
174  *
175  * Return value:
176  *
177  * NOTMUCH_STATUS_SUCCESS: Successfully created the database.
178  *
179  * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL.
180  *
181  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
182  *
183  * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the
184  *      database file (such as permission denied, or file not found,
185  *      etc.), or the database already exists.
186  *
187  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
188  */
189 notmuch_status_t
190 notmuch_database_create (const char *path, notmuch_database_t **database);
191
192 typedef enum {
193     NOTMUCH_DATABASE_MODE_READ_ONLY = 0,
194     NOTMUCH_DATABASE_MODE_READ_WRITE
195 } notmuch_database_mode_t;
196
197 /* Open an existing notmuch database located at 'path'.
198  *
199  * The database should have been created at some time in the past,
200  * (not necessarily by this process), by calling
201  * notmuch_database_create with 'path'. By default the database should be
202  * opened for reading only. In order to write to the database you need to
203  * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.
204  *
205  * An existing notmuch database can be identified by the presence of a
206  * directory named ".notmuch" below 'path'.
207  *
208  * The caller should call notmuch_database_destroy when finished with
209  * this database.
210  *
211  * In case of any failure, this function returns an error status and
212  * sets *database to NULL (after printing an error message on stderr).
213  *
214  * Return value:
215  *
216  * NOTMUCH_STATUS_SUCCESS: Successfully opened the database.
217  *
218  * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL.
219  *
220  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
221  *
222  * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the
223  *      database file (such as permission denied, or file not found,
224  *      etc.), or the database version is unknown.
225  *
226  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
227  */
228 notmuch_status_t
229 notmuch_database_open (const char *path,
230                        notmuch_database_mode_t mode,
231                        notmuch_database_t **database);
232
233 /* Close the given notmuch database.
234  *
235  * After notmuch_database_close has been called, calls to other
236  * functions on objects derived from this database may either behave
237  * as if the database had not been closed (e.g., if the required data
238  * has been cached) or may fail with a
239  * NOTMUCH_STATUS_XAPIAN_EXCEPTION.
240  *
241  * notmuch_database_close can be called multiple times.  Later calls
242  * have no effect.
243  */
244 void
245 notmuch_database_close (notmuch_database_t *database);
246
247 /* A callback invoked by notmuch_database_compact to notify the user
248  * of the progress of the compaction process.
249  */
250 typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure);
251
252 /* Compact a notmuch database, backing up the original database to the
253  * given path.
254  *
255  * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE
256  * during the compaction process to ensure no writes are made.
257  *
258  * If the optional callback function 'status_cb' is non-NULL, it will
259  * be called with diagnostic and informational messages. The argument
260  * 'closure' is passed verbatim to any callback invoked.
261  */
262 notmuch_status_t
263 notmuch_database_compact (const char* path,
264                           const char* backup_path,
265                           notmuch_compact_status_cb_t status_cb,
266                           void *closure);
267
268 /* Destroy the notmuch database, closing it if necessary and freeing
269  * all associated resources.
270  */
271 void
272 notmuch_database_destroy (notmuch_database_t *database);
273
274 /* Return the database path of the given database.
275  *
276  * The return value is a string owned by notmuch so should not be
277  * modified nor freed by the caller. */
278 const char *
279 notmuch_database_get_path (notmuch_database_t *database);
280
281 /* Return the database format version of the given database. */
282 unsigned int
283 notmuch_database_get_version (notmuch_database_t *database);
284
285 /* Does this database need to be upgraded before writing to it?
286  *
287  * If this function returns TRUE then no functions that modify the
288  * database (notmuch_database_add_message, notmuch_message_add_tag,
289  * notmuch_directory_set_mtime, etc.) will work unless the function
290  * notmuch_database_upgrade is called successfully first. */
291 notmuch_bool_t
292 notmuch_database_needs_upgrade (notmuch_database_t *database);
293
294 /* Upgrade the current database.
295  *
296  * After opening a database in read-write mode, the client should
297  * check if an upgrade is needed (notmuch_database_needs_upgrade) and
298  * if so, upgrade with this function before making any modifications.
299  *
300  * The optional progress_notify callback can be used by the caller to
301  * provide progress indication to the user. If non-NULL it will be
302  * called periodically with 'progress' as a floating-point value in
303  * the range of [0.0 .. 1.0] indicating the progress made so far in
304  * the upgrade process.  The argument 'closure' is passed verbatim to
305  * any callback invoked.
306  */
307 notmuch_status_t
308 notmuch_database_upgrade (notmuch_database_t *database,
309                           void (*progress_notify) (void *closure,
310                                                    double progress),
311                           void *closure);
312
313 /* Begin an atomic database operation.
314  *
315  * Any modifications performed between a successful begin and a
316  * notmuch_database_end_atomic will be applied to the database
317  * atomically.  Note that, unlike a typical database transaction, this
318  * only ensures atomicity, not durability; neither begin nor end
319  * necessarily flush modifications to disk.
320  *
321  * Atomic sections may be nested.  begin_atomic and end_atomic must
322  * always be called in pairs.
323  *
324  * Return value:
325  *
326  * NOTMUCH_STATUS_SUCCESS: Successfully entered atomic section.
327  *
328  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
329  *      atomic section not entered.
330  */
331 notmuch_status_t
332 notmuch_database_begin_atomic (notmuch_database_t *notmuch);
333
334 /* Indicate the end of an atomic database operation.
335  *
336  * Return value:
337  *
338  * NOTMUCH_STATUS_SUCCESS: Successfully completed atomic section.
339  *
340  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
341  *      atomic section not ended.
342  *
343  * NOTMUCH_STATUS_UNBALANCED_ATOMIC: The database is not currently in
344  *      an atomic section.
345  */
346 notmuch_status_t
347 notmuch_database_end_atomic (notmuch_database_t *notmuch);
348
349 /* Retrieve a directory object from the database for 'path'.
350  *
351  * Here, 'path' should be a path relative to the path of 'database'
352  * (see notmuch_database_get_path), or else should be an absolute path
353  * with initial components that match the path of 'database'.
354  *
355  * If this directory object does not exist in the database, this
356  * returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL.
357  *
358  * Return value:
359  *
360  * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory.
361  *
362  * NOTMUCH_STATUS_NULL_POINTER: The given 'directory' argument is NULL.
363  *
364  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
365  *      directory not retrieved.
366  */
367 notmuch_status_t
368 notmuch_database_get_directory (notmuch_database_t *database,
369                                 const char *path,
370                                 notmuch_directory_t **directory);
371
372 /* Add a new message to the given notmuch database or associate an
373  * additional filename with an existing message.
374  *
375  * Here, 'filename' should be a path relative to the path of
376  * 'database' (see notmuch_database_get_path), or else should be an
377  * absolute filename with initial components that match the path of
378  * 'database'.
379  *
380  * The file should be a single mail message (not a multi-message mbox)
381  * that is expected to remain at its current location, (since the
382  * notmuch database will reference the filename, and will not copy the
383  * entire contents of the file.
384  *
385  * If another message with the same message ID already exists in the
386  * database, rather than creating a new message, this adds 'filename'
387  * to the list of the filenames for the existing message.
388  *
389  * If 'message' is not NULL, then, on successful return
390  * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'
391  * will be initialized to a message object that can be used for things
392  * such as adding tags to the just-added message. The user should call
393  * notmuch_message_destroy when done with the message. On any failure
394  * '*message' will be set to NULL.
395  *
396  * Return value:
397  *
398  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
399  *
400  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
401  *      message not added.
402  *
403  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
404  *      ID as another message already in the database. The new
405  *      filename was successfully added to the message in the database
406  *      (if not already present) and the existing message is returned.
407  *
408  * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
409  *      file, (such as permission denied, or file not found,
410  *      etc.). Nothing added to the database.
411  *
412  * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look
413  *      like an email message. Nothing added to the database.
414  *
415  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
416  *      mode so no message can be added.
417  */
418 notmuch_status_t
419 notmuch_database_add_message (notmuch_database_t *database,
420                               const char *filename,
421                               notmuch_message_t **message);
422
423 /* Remove a message filename from the given notmuch database. If the
424  * message has no more filenames, remove the message.
425  *
426  * If the same message (as determined by the message ID) is still
427  * available via other filenames, then the message will persist in the
428  * database for those filenames. When the last filename is removed for
429  * a particular message, the database content for that message will be
430  * entirely removed.
431  *
432  * Return value:
433  *
434  * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
435  *      message was removed from the database.
436  *
437  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
438  *      message not removed.
439  *
440  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
441  *      the message persists in the database with at least one other
442  *      filename.
443  *
444  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
445  *      mode so no message can be removed.
446  */
447 notmuch_status_t
448 notmuch_database_remove_message (notmuch_database_t *database,
449                                  const char *filename);
450
451 /* Find a message with the given message_id.
452  *
453  * If a message with the given message_id is found then, on successful return
454  * (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to a message
455  * object.  The caller should call notmuch_message_destroy when done with the
456  * message.
457  *
458  * On any failure or when the message is not found, this function initializes
459  * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the
460  * caller is supposed to check '*message' for NULL to find out whether the
461  * message with the given message_id was found.
462  *
463  * Return value:
464  *
465  * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'.
466  *
467  * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL
468  *
469  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating message object
470  *
471  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
472  */
473 notmuch_status_t
474 notmuch_database_find_message (notmuch_database_t *database,
475                                const char *message_id,
476                                notmuch_message_t **message);
477
478 /* Find a message with the given filename.
479  *
480  * If the database contains a message with the given filename then, on
481  * successful return (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to
482  * a message object. The caller should call notmuch_message_destroy when done
483  * with the message.
484  *
485  * On any failure or when the message is not found, this function initializes
486  * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the
487  * caller is supposed to check '*message' for NULL to find out whether the
488  * message with the given filename is found.
489  *
490  * Return value:
491  *
492  * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'
493  *
494  * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL
495  *
496  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message object
497  *
498  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
499  */
500 notmuch_status_t
501 notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
502                                            const char *filename,
503                                            notmuch_message_t **message);
504
505 /* Return a list of all tags found in the database.
506  *
507  * This function creates a list of all tags found in the database. The
508  * resulting list contains all tags from all messages found in the database.
509  *
510  * On error this function returns NULL.
511  */
512 notmuch_tags_t *
513 notmuch_database_get_all_tags (notmuch_database_t *db);
514
515 /* Create a new query for 'database'.
516  *
517  * Here, 'database' should be an open database, (see
518  * notmuch_database_open and notmuch_database_create).
519  *
520  * For the query string, we'll document the syntax here more
521  * completely in the future, but it's likely to be a specialized
522  * version of the general Xapian query syntax:
523  *
524  * http://xapian.org/docs/queryparser.html
525  *
526  * As a special case, passing either a length-zero string, (that is ""),
527  * or a string consisting of a single asterisk (that is "*"), will
528  * result in a query that returns all messages in the database.
529  *
530  * See notmuch_query_set_sort for controlling the order of results.
531  * See notmuch_query_search_messages and notmuch_query_search_threads
532  * to actually execute the query.
533  *
534  * User should call notmuch_query_destroy when finished with this
535  * query.
536  *
537  * Will return NULL if insufficient memory is available.
538  */
539 notmuch_query_t *
540 notmuch_query_create (notmuch_database_t *database,
541                       const char *query_string);
542
543 /* Sort values for notmuch_query_set_sort */
544 typedef enum {
545     NOTMUCH_SORT_OLDEST_FIRST,
546     NOTMUCH_SORT_NEWEST_FIRST,
547     NOTMUCH_SORT_MESSAGE_ID,
548     NOTMUCH_SORT_UNSORTED
549 } notmuch_sort_t;
550
551 /* Return the query_string of this query. See notmuch_query_create. */
552 const char *
553 notmuch_query_get_query_string (notmuch_query_t *query);
554
555 /* Exclude values for notmuch_query_set_omit_excluded. The strange
556  * order is to maintain backward compatibility: the old FALSE/TRUE
557  * options correspond to the new
558  * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
559  */
560 typedef enum {
561     NOTMUCH_EXCLUDE_FLAG,
562     NOTMUCH_EXCLUDE_TRUE,
563     NOTMUCH_EXCLUDE_FALSE,
564     NOTMUCH_EXCLUDE_ALL
565 } notmuch_exclude_t;
566
567 /* Specify whether to omit excluded results or simply flag them.  By
568  * default, this is set to TRUE.
569  *
570  * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded
571  * messages from the results, and notmuch_query_search_threads will omit
572  * threads that match only in excluded messages.  If set to TRUE,
573  * notmuch_query_search_threads will include all messages in threads that
574  * match in at least one non-excluded message.  Otherwise, if set to ALL,
575  * notmuch_query_search_threads will omit excluded messages from all threads.
576  *
577  * If set to FALSE or FLAG then both notmuch_query_search_messages and
578  * notmuch_query_search_threads will return all matching
579  * messages/threads regardless of exclude status. If set to FLAG then
580  * the exclude flag will be set for any excluded message that is
581  * returned by notmuch_query_search_messages, and the thread counts
582  * for threads returned by notmuch_query_search_threads will be the
583  * number of non-excluded messages/matches. Otherwise, if set to
584  * FALSE, then the exclude status is completely ignored.
585  *
586  * The performance difference when calling
587  * notmuch_query_search_messages should be relatively small (and both
588  * should be very fast).  However, in some cases,
589  * notmuch_query_search_threads is very much faster when omitting
590  * excluded messages as it does not need to construct the threads that
591  * only match in excluded messages.
592  */
593 void
594 notmuch_query_set_omit_excluded (notmuch_query_t *query,
595                                  notmuch_exclude_t omit_excluded);
596
597 /* Specify the sorting desired for this query. */
598 void
599 notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
600
601 /* Return the sort specified for this query. See notmuch_query_set_sort. */
602 notmuch_sort_t
603 notmuch_query_get_sort (notmuch_query_t *query);
604
605 /* Add a tag that will be excluded from the query results by default.
606  * This exclusion will be overridden if this tag appears explicitly in
607  * the query. */
608 void
609 notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
610
611 /* Execute a query for threads, returning a notmuch_threads_t object
612  * which can be used to iterate over the results. The returned threads
613  * object is owned by the query and as such, will only be valid until
614  * notmuch_query_destroy.
615  *
616  * Typical usage might be:
617  *
618  *     notmuch_query_t *query;
619  *     notmuch_threads_t *threads;
620  *     notmuch_thread_t *thread;
621  *
622  *     query = notmuch_query_create (database, query_string);
623  *
624  *     for (threads = notmuch_query_search_threads (query);
625  *          notmuch_threads_valid (threads);
626  *          notmuch_threads_move_to_next (threads))
627  *     {
628  *         thread = notmuch_threads_get (threads);
629  *         ....
630  *         notmuch_thread_destroy (thread);
631  *     }
632  *
633  *     notmuch_query_destroy (query);
634  *
635  * Note: If you are finished with a thread before its containing
636  * query, you can call notmuch_thread_destroy to clean up some memory
637  * sooner (as in the above example). Otherwise, if your thread objects
638  * are long-lived, then you don't need to call notmuch_thread_destroy
639  * and all the memory will still be reclaimed when the query is
640  * destroyed.
641  *
642  * Note that there's no explicit destructor needed for the
643  * notmuch_threads_t object. (For consistency, we do provide a
644  * notmuch_threads_destroy function, but there's no good reason
645  * to call it if the query is about to be destroyed).
646  *
647  * If a Xapian exception occurs this function will return NULL.
648  */
649 notmuch_threads_t *
650 notmuch_query_search_threads (notmuch_query_t *query);
651
652 /* Execute a query for messages, returning a notmuch_messages_t object
653  * which can be used to iterate over the results. The returned
654  * messages object is owned by the query and as such, will only be
655  * valid until notmuch_query_destroy.
656  *
657  * Typical usage might be:
658  *
659  *     notmuch_query_t *query;
660  *     notmuch_messages_t *messages;
661  *     notmuch_message_t *message;
662  *
663  *     query = notmuch_query_create (database, query_string);
664  *
665  *     for (messages = notmuch_query_search_messages (query);
666  *          notmuch_messages_valid (messages);
667  *          notmuch_messages_move_to_next (messages))
668  *     {
669  *         message = notmuch_messages_get (messages);
670  *         ....
671  *         notmuch_message_destroy (message);
672  *     }
673  *
674  *     notmuch_query_destroy (query);
675  *
676  * Note: If you are finished with a message before its containing
677  * query, you can call notmuch_message_destroy to clean up some memory
678  * sooner (as in the above example). Otherwise, if your message
679  * objects are long-lived, then you don't need to call
680  * notmuch_message_destroy and all the memory will still be reclaimed
681  * when the query is destroyed.
682  *
683  * Note that there's no explicit destructor needed for the
684  * notmuch_messages_t object. (For consistency, we do provide a
685  * notmuch_messages_destroy function, but there's no good
686  * reason to call it if the query is about to be destroyed).
687  *
688  * If a Xapian exception occurs this function will return NULL.
689  */
690 notmuch_messages_t *
691 notmuch_query_search_messages (notmuch_query_t *query);
692
693 /* Destroy a notmuch_query_t along with any associated resources.
694  *
695  * This will in turn destroy any notmuch_threads_t and
696  * notmuch_messages_t objects generated by this query, (and in
697  * turn any notmuch_thread_t and notmuch_message_t objects generated
698  * from those results, etc.), if such objects haven't already been
699  * destroyed.
700  */
701 void
702 notmuch_query_destroy (notmuch_query_t *query);
703
704 /* Is the given 'threads' iterator pointing at a valid thread.
705  *
706  * When this function returns TRUE, notmuch_threads_get will return a
707  * valid object. Whereas when this function returns FALSE,
708  * notmuch_threads_get will return NULL.
709  *
710  * See the documentation of notmuch_query_search_threads for example
711  * code showing how to iterate over a notmuch_threads_t object.
712  */
713 notmuch_bool_t
714 notmuch_threads_valid (notmuch_threads_t *threads);
715
716 /* Get the current thread from 'threads' as a notmuch_thread_t.
717  *
718  * Note: The returned thread belongs to 'threads' and has a lifetime
719  * identical to it (and the query to which it belongs).
720  *
721  * See the documentation of notmuch_query_search_threads for example
722  * code showing how to iterate over a notmuch_threads_t object.
723  *
724  * If an out-of-memory situation occurs, this function will return
725  * NULL.
726  */
727 notmuch_thread_t *
728 notmuch_threads_get (notmuch_threads_t *threads);
729
730 /* Move the 'threads' iterator to the next thread.
731  *
732  * If 'threads' is already pointing at the last thread then the
733  * iterator will be moved to a point just beyond that last thread,
734  * (where notmuch_threads_valid will return FALSE and
735  * notmuch_threads_get will return NULL).
736  *
737  * See the documentation of notmuch_query_search_threads for example
738  * code showing how to iterate over a notmuch_threads_t object.
739  */
740 void
741 notmuch_threads_move_to_next (notmuch_threads_t *threads);
742
743 /* Destroy a notmuch_threads_t object.
744  *
745  * It's not strictly necessary to call this function. All memory from
746  * the notmuch_threads_t object will be reclaimed when the
747  * containing query object is destroyed.
748  */
749 void
750 notmuch_threads_destroy (notmuch_threads_t *threads);
751
752 /* Return an estimate of the number of messages matching a search
753  *
754  * This function performs a search and returns Xapian's best
755  * guess as to number of matching messages.
756  *
757  * If a Xapian exception occurs, this function may return 0 (after
758  * printing a message).
759  */
760 unsigned
761 notmuch_query_count_messages (notmuch_query_t *query);
762  
763 /* Return the number of threads matching a search.
764  *
765  * This function performs a search and returns the number of unique thread IDs
766  * in the matching messages. This is the same as number of threads matching a
767  * search.
768  *
769  * Note that this is a significantly heavier operation than
770  * notmuch_query_count_messages().
771  *
772  * If an error occurs, this function may return 0.
773  */
774 unsigned
775 notmuch_query_count_threads (notmuch_query_t *query);
776
777 /* Get the thread ID of 'thread'.
778  *
779  * The returned string belongs to 'thread' and as such, should not be
780  * modified by the caller and will only be valid for as long as the
781  * thread is valid, (which is until notmuch_thread_destroy or until
782  * the query from which it derived is destroyed).
783  */
784 const char *
785 notmuch_thread_get_thread_id (notmuch_thread_t *thread);
786
787 /* Get the total number of messages in 'thread'.
788  *
789  * This count consists of all messages in the database belonging to
790  * this thread. Contrast with notmuch_thread_get_matched_messages() .
791  */
792 int
793 notmuch_thread_get_total_messages (notmuch_thread_t *thread);
794
795 /* Get a notmuch_messages_t iterator for the top-level messages in
796  * 'thread' in oldest-first order.
797  *
798  * This iterator will not necessarily iterate over all of the messages
799  * in the thread. It will only iterate over the messages in the thread
800  * which are not replies to other messages in the thread.
801  *
802  * The returned list will be destroyed when the thread is destroyed.
803  */
804 notmuch_messages_t *
805 notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
806
807 /* Get a notmuch_thread_t iterator for all messages in 'thread' in
808  * oldest-first order.
809  *
810  * The returned list will be destroyed when the thread is destroyed.
811  */
812 notmuch_messages_t *
813 notmuch_thread_get_messages (notmuch_thread_t *thread);
814
815 /* Get the number of messages in 'thread' that matched the search.
816  *
817  * This count includes only the messages in this thread that were
818  * matched by the search from which the thread was created and were
819  * not excluded by any exclude tags passed in with the query (see
820  * notmuch_query_add_tag_exclude). Contrast with
821  * notmuch_thread_get_total_messages() .
822  */
823 int
824 notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
825
826 /* Get the authors of 'thread' as a UTF-8 string.
827  *
828  * The returned string is a comma-separated list of the names of the
829  * authors of mail messages in the query results that belong to this
830  * thread.
831  *
832  * The returned string belongs to 'thread' and as such, should not be
833  * modified by the caller and will only be valid for as long as the
834  * thread is valid, (which is until notmuch_thread_destroy or until
835  * the query from which it derived is destroyed).
836  */
837 const char *
838 notmuch_thread_get_authors (notmuch_thread_t *thread);
839
840 /* Get the subject of 'thread' as a UTF-8 string.
841  *
842  * The subject is taken from the first message (according to the query
843  * order---see notmuch_query_set_sort) in the query results that
844  * belongs to this thread.
845  *
846  * The returned string belongs to 'thread' and as such, should not be
847  * modified by the caller and will only be valid for as long as the
848  * thread is valid, (which is until notmuch_thread_destroy or until
849  * the query from which it derived is destroyed).
850  */
851 const char *
852 notmuch_thread_get_subject (notmuch_thread_t *thread);
853
854 /* Get the date of the oldest message in 'thread' as a time_t value.
855  */
856 time_t
857 notmuch_thread_get_oldest_date (notmuch_thread_t *thread);
858
859 /* Get the date of the newest message in 'thread' as a time_t value.
860  */
861 time_t
862 notmuch_thread_get_newest_date (notmuch_thread_t *thread);
863
864 /* Get the tags for 'thread', returning a notmuch_tags_t object which
865  * can be used to iterate over all tags.
866  *
867  * Note: In the Notmuch database, tags are stored on individual
868  * messages, not on threads. So the tags returned here will be all
869  * tags of the messages which matched the search and which belong to
870  * this thread.
871  *
872  * The tags object is owned by the thread and as such, will only be
873  * valid for as long as the thread is valid, (for example, until
874  * notmuch_thread_destroy or until the query from which it derived is
875  * destroyed).
876  *
877  * Typical usage might be:
878  *
879  *     notmuch_thread_t *thread;
880  *     notmuch_tags_t *tags;
881  *     const char *tag;
882  *
883  *     thread = notmuch_threads_get (threads);
884  *
885  *     for (tags = notmuch_thread_get_tags (thread);
886  *          notmuch_tags_valid (tags);
887  *          notmuch_result_move_to_next (tags))
888  *     {
889  *         tag = notmuch_tags_get (tags);
890  *         ....
891  *     }
892  *
893  *     notmuch_thread_destroy (thread);
894  *
895  * Note that there's no explicit destructor needed for the
896  * notmuch_tags_t object. (For consistency, we do provide a
897  * notmuch_tags_destroy function, but there's no good reason to call
898  * it if the message is about to be destroyed).
899  */
900 notmuch_tags_t *
901 notmuch_thread_get_tags (notmuch_thread_t *thread);
902
903 /* Destroy a notmuch_thread_t object. */
904 void
905 notmuch_thread_destroy (notmuch_thread_t *thread);
906
907 /* Is the given 'messages' iterator pointing at a valid message.
908  *
909  * When this function returns TRUE, notmuch_messages_get will return a
910  * valid object. Whereas when this function returns FALSE,
911  * notmuch_messages_get will return NULL.
912  *
913  * See the documentation of notmuch_query_search_messages for example
914  * code showing how to iterate over a notmuch_messages_t object.
915  */
916 notmuch_bool_t
917 notmuch_messages_valid (notmuch_messages_t *messages);
918
919 /* Get the current message from 'messages' as a notmuch_message_t.
920  *
921  * Note: The returned message belongs to 'messages' and has a lifetime
922  * identical to it (and the query to which it belongs).
923  *
924  * See the documentation of notmuch_query_search_messages for example
925  * code showing how to iterate over a notmuch_messages_t object.
926  *
927  * If an out-of-memory situation occurs, this function will return
928  * NULL.
929  */
930 notmuch_message_t *
931 notmuch_messages_get (notmuch_messages_t *messages);
932
933 /* Move the 'messages' iterator to the next message.
934  *
935  * If 'messages' is already pointing at the last message then the
936  * iterator will be moved to a point just beyond that last message,
937  * (where notmuch_messages_valid will return FALSE and
938  * notmuch_messages_get will return NULL).
939  *
940  * See the documentation of notmuch_query_search_messages for example
941  * code showing how to iterate over a notmuch_messages_t object.
942  */
943 void
944 notmuch_messages_move_to_next (notmuch_messages_t *messages);
945
946 /* Destroy a notmuch_messages_t object.
947  *
948  * It's not strictly necessary to call this function. All memory from
949  * the notmuch_messages_t object will be reclaimed when the containing
950  * query object is destroyed.
951  */
952 void
953 notmuch_messages_destroy (notmuch_messages_t *messages);
954
955 /* Return a list of tags from all messages.
956  *
957  * The resulting list is guaranteed not to contain duplicated tags.
958  *
959  * WARNING: You can no longer iterate over messages after calling this
960  * function, because the iterator will point at the end of the list.
961  * We do not have a function to reset the iterator yet and the only
962  * way how you can iterate over the list again is to recreate the
963  * message list.
964  *
965  * The function returns NULL on error.
966  */
967 notmuch_tags_t *
968 notmuch_messages_collect_tags (notmuch_messages_t *messages);
969
970 /* Get the message ID of 'message'.
971  *
972  * The returned string belongs to 'message' and as such, should not be
973  * modified by the caller and will only be valid for as long as the
974  * message is valid, (which is until the query from which it derived
975  * is destroyed).
976  *
977  * This function will not return NULL since Notmuch ensures that every
978  * message has a unique message ID, (Notmuch will generate an ID for a
979  * message if the original file does not contain one).
980  */
981 const char *
982 notmuch_message_get_message_id (notmuch_message_t *message);
983
984 /* Get the thread ID of 'message'.
985  *
986  * The returned string belongs to 'message' and as such, should not be
987  * modified by the caller and will only be valid for as long as the
988  * message is valid, (for example, until the user calls
989  * notmuch_message_destroy on 'message' or until a query from which it
990  * derived is destroyed).
991  *
992  * This function will not return NULL since Notmuch ensures that every
993  * message belongs to a single thread.
994  */
995 const char *
996 notmuch_message_get_thread_id (notmuch_message_t *message);
997
998 /* Get a notmuch_messages_t iterator for all of the replies to
999  * 'message'.
1000  *
1001  * Note: This call only makes sense if 'message' was ultimately
1002  * obtained from a notmuch_thread_t object, (such as by coming
1003  * directly from the result of calling notmuch_thread_get_
1004  * toplevel_messages or by any number of subsequent
1005  * calls to notmuch_message_get_replies).
1006  *
1007  * If 'message' was obtained through some non-thread means, (such as
1008  * by a call to notmuch_query_search_messages), then this function
1009  * will return NULL.
1010  *
1011  * If there are no replies to 'message', this function will return
1012  * NULL. (Note that notmuch_messages_valid will accept that NULL
1013  * value as legitimate, and simply return FALSE for it.)
1014  */
1015 notmuch_messages_t *
1016 notmuch_message_get_replies (notmuch_message_t *message);
1017
1018 /* Get a filename for the email corresponding to 'message'.
1019  *
1020  * The returned filename is an absolute filename, (the initial
1021  * component will match notmuch_database_get_path() ).
1022  *
1023  * The returned string belongs to the message so should not be
1024  * modified or freed by the caller (nor should it be referenced after
1025  * the message is destroyed).
1026  *
1027  * Note: If this message corresponds to multiple files in the mail
1028  * store, (that is, multiple files contain identical message IDs),
1029  * this function will arbitrarily return a single one of those
1030  * filenames. See notmuch_message_get_filenames for returning the
1031  * complete list of filenames.
1032  */
1033 const char *
1034 notmuch_message_get_filename (notmuch_message_t *message);
1035
1036 /* Get all filenames for the email corresponding to 'message'.
1037  *
1038  * Returns a notmuch_filenames_t iterator listing all the filenames
1039  * associated with 'message'. These files may not have identical
1040  * content, but each will have the identical Message-ID.
1041  *
1042  * Each filename in the iterator is an absolute filename, (the initial
1043  * component will match notmuch_database_get_path() ).
1044  */
1045 notmuch_filenames_t *
1046 notmuch_message_get_filenames (notmuch_message_t *message);
1047
1048 /* Message flags */
1049 typedef enum _notmuch_message_flag {
1050     NOTMUCH_MESSAGE_FLAG_MATCH,
1051     NOTMUCH_MESSAGE_FLAG_EXCLUDED
1052 } notmuch_message_flag_t;
1053
1054 /* Get a value of a flag for the email corresponding to 'message'. */
1055 notmuch_bool_t
1056 notmuch_message_get_flag (notmuch_message_t *message,
1057                           notmuch_message_flag_t flag);
1058
1059 /* Set a value of a flag for the email corresponding to 'message'. */
1060 void
1061 notmuch_message_set_flag (notmuch_message_t *message,
1062                           notmuch_message_flag_t flag, notmuch_bool_t value);
1063
1064 /* Get the date of 'message' as a time_t value.
1065  *
1066  * For the original textual representation of the Date header from the
1067  * message call notmuch_message_get_header() with a header value of
1068  * "date". */
1069 time_t
1070 notmuch_message_get_date  (notmuch_message_t *message);
1071
1072 /* Get the value of the specified header from 'message' as a UTF-8 string.
1073  *
1074  * Common headers are stored in the database when the message is
1075  * indexed and will be returned from the database.  Other headers will
1076  * be read from the actual message file.
1077  *
1078  * The header name is case insensitive.
1079  *
1080  * The returned string belongs to the message so should not be
1081  * modified or freed by the caller (nor should it be referenced after
1082  * the message is destroyed).
1083  *
1084  * Returns an empty string ("") if the message does not contain a
1085  * header line matching 'header'. Returns NULL if any error occurs.
1086  */
1087 const char *
1088 notmuch_message_get_header (notmuch_message_t *message, const char *header);
1089
1090 /* Get the tags for 'message', returning a notmuch_tags_t object which
1091  * can be used to iterate over all tags.
1092  *
1093  * The tags object is owned by the message and as such, will only be
1094  * valid for as long as the message is valid, (which is until the
1095  * query from which it derived is destroyed).
1096  *
1097  * Typical usage might be:
1098  *
1099  *     notmuch_message_t *message;
1100  *     notmuch_tags_t *tags;
1101  *     const char *tag;
1102  *
1103  *     message = notmuch_database_find_message (database, message_id);
1104  *
1105  *     for (tags = notmuch_message_get_tags (message);
1106  *          notmuch_tags_valid (tags);
1107  *          notmuch_result_move_to_next (tags))
1108  *     {
1109  *         tag = notmuch_tags_get (tags);
1110  *         ....
1111  *     }
1112  *
1113  *     notmuch_message_destroy (message);
1114  *
1115  * Note that there's no explicit destructor needed for the
1116  * notmuch_tags_t object. (For consistency, we do provide a
1117  * notmuch_tags_destroy function, but there's no good reason to call
1118  * it if the message is about to be destroyed).
1119  */
1120 notmuch_tags_t *
1121 notmuch_message_get_tags (notmuch_message_t *message);
1122
1123 /* The longest possible tag value. */
1124 #define NOTMUCH_TAG_MAX 200
1125
1126 /* Add a tag to the given message.
1127  *
1128  * Return value:
1129  *
1130  * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message
1131  *
1132  * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
1133  *
1134  * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
1135  *      (exceeds NOTMUCH_TAG_MAX)
1136  *
1137  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1138  *      mode so message cannot be modified.
1139  */
1140 notmuch_status_t
1141 notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
1142
1143 /* Remove a tag from the given message.
1144  *
1145  * Return value:
1146  *
1147  * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message
1148  *
1149  * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
1150  *
1151  * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
1152  *      (exceeds NOTMUCH_TAG_MAX)
1153  *
1154  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1155  *      mode so message cannot be modified.
1156  */
1157 notmuch_status_t
1158 notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
1159
1160 /* Remove all tags from the given message.
1161  *
1162  * See notmuch_message_freeze for an example showing how to safely
1163  * replace tag values.
1164  *
1165  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1166  *      mode so message cannot be modified.
1167  */
1168 notmuch_status_t
1169 notmuch_message_remove_all_tags (notmuch_message_t *message);
1170
1171 /* Add/remove tags according to maildir flags in the message filename(s)
1172  *
1173  * This function examines the filenames of 'message' for maildir
1174  * flags, and adds or removes tags on 'message' as follows when these
1175  * flags are present:
1176  *
1177  *      Flag    Action if present
1178  *      ----    -----------------
1179  *      'D'     Adds the "draft" tag to the message
1180  *      'F'     Adds the "flagged" tag to the message
1181  *      'P'     Adds the "passed" tag to the message
1182  *      'R'     Adds the "replied" tag to the message
1183  *      'S'     Removes the "unread" tag from the message
1184  *
1185  * For each flag that is not present, the opposite action (add/remove)
1186  * is performed for the corresponding tags.
1187  *
1188  * Flags are identified as trailing components of the filename after a
1189  * sequence of ":2,".
1190  *
1191  * If there are multiple filenames associated with this message, the
1192  * flag is considered present if it appears in one or more
1193  * filenames. (That is, the flags from the multiple filenames are
1194  * combined with the logical OR operator.)
1195  *
1196  * A client can ensure that notmuch database tags remain synchronized
1197  * with maildir flags by calling this function after each call to
1198  * notmuch_database_add_message. See also
1199  * notmuch_message_tags_to_maildir_flags for synchronizing tag changes
1200  * back to maildir flags.
1201  */
1202 notmuch_status_t
1203 notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
1204
1205 /* Rename message filename(s) to encode tags as maildir flags
1206  *
1207  * Specifically, for each filename corresponding to this message:
1208  *
1209  * If the filename is not in a maildir directory, do nothing.  (A
1210  * maildir directory is determined as a directory named "new" or
1211  * "cur".) Similarly, if the filename has invalid maildir info,
1212  * (repeated or outof-ASCII-order flag characters after ":2,"), then
1213  * do nothing.
1214  *
1215  * If the filename is in a maildir directory, rename the file so that
1216  * its filename ends with the sequence ":2," followed by zero or more
1217  * of the following single-character flags (in ASCII order):
1218  *
1219  *   'D' iff the message has the "draft" tag
1220  *   'F' iff the message has the "flagged" tag
1221  *   'P' iff the message has the "passed" tag
1222  *   'R' iff the message has the "replied" tag
1223  *   'S' iff the message does not have the "unread" tag
1224  *
1225  * Any existing flags unmentioned in the list above will be preserved
1226  * in the renaming.
1227  *
1228  * Also, if this filename is in a directory named "new", rename it to
1229  * be within the neighboring directory named "cur".
1230  *
1231  * A client can ensure that maildir filename flags remain synchronized
1232  * with notmuch database tags by calling this function after changing
1233  * tags, (after calls to notmuch_message_add_tag,
1234  * notmuch_message_remove_tag, or notmuch_message_freeze/
1235  * notmuch_message_thaw). See also notmuch_message_maildir_flags_to_tags
1236  * for synchronizing maildir flag changes back to tags.
1237  */
1238 notmuch_status_t
1239 notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);
1240
1241 /* Freeze the current state of 'message' within the database.
1242  *
1243  * This means that changes to the message state, (via
1244  * notmuch_message_add_tag, notmuch_message_remove_tag, and
1245  * notmuch_message_remove_all_tags), will not be committed to the
1246  * database until the message is thawed with notmuch_message_thaw.
1247  *
1248  * Multiple calls to freeze/thaw are valid and these calls will
1249  * "stack". That is there must be as many calls to thaw as to freeze
1250  * before a message is actually thawed.
1251  *
1252  * The ability to do freeze/thaw allows for safe transactions to
1253  * change tag values. For example, explicitly setting a message to
1254  * have a given set of tags might look like this:
1255  *
1256  *    notmuch_message_freeze (message);
1257  *
1258  *    notmuch_message_remove_all_tags (message);
1259  *
1260  *    for (i = 0; i < NUM_TAGS; i++)
1261  *        notmuch_message_add_tag (message, tags[i]);
1262  *
1263  *    notmuch_message_thaw (message);
1264  *
1265  * With freeze/thaw used like this, the message in the database is
1266  * guaranteed to have either the full set of original tag values, or
1267  * the full set of new tag values, but nothing in between.
1268  *
1269  * Imagine the example above without freeze/thaw and the operation
1270  * somehow getting interrupted. This could result in the message being
1271  * left with no tags if the interruption happened after
1272  * notmuch_message_remove_all_tags but before notmuch_message_add_tag.
1273  *
1274  * Return value:
1275  *
1276  * NOTMUCH_STATUS_SUCCESS: Message successfully frozen.
1277  *
1278  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1279  *      mode so message cannot be modified.
1280  */
1281 notmuch_status_t
1282 notmuch_message_freeze (notmuch_message_t *message);
1283
1284 /* Thaw the current 'message', synchronizing any changes that may have
1285  * occurred while 'message' was frozen into the notmuch database.
1286  *
1287  * See notmuch_message_freeze for an example of how to use this
1288  * function to safely provide tag changes.
1289  *
1290  * Multiple calls to freeze/thaw are valid and these calls with
1291  * "stack". That is there must be as many calls to thaw as to freeze
1292  * before a message is actually thawed.
1293  *
1294  * Return value:
1295  *
1296  * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least
1297  *      its frozen count has successfully been reduced by 1).
1298  *
1299  * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw
1300  *      an unfrozen message. That is, there have been an unbalanced
1301  *      number of calls to notmuch_message_freeze and
1302  *      notmuch_message_thaw.
1303  */
1304 notmuch_status_t
1305 notmuch_message_thaw (notmuch_message_t *message);
1306
1307 /* Destroy a notmuch_message_t object.
1308  *
1309  * It can be useful to call this function in the case of a single
1310  * query object with many messages in the result, (such as iterating
1311  * over the entire database). Otherwise, it's fine to never call this
1312  * function and there will still be no memory leaks. (The memory from
1313  * the messages get reclaimed when the containing query is destroyed.)
1314  */
1315 void
1316 notmuch_message_destroy (notmuch_message_t *message);
1317
1318 /* Is the given 'tags' iterator pointing at a valid tag.
1319  *
1320  * When this function returns TRUE, notmuch_tags_get will return a
1321  * valid string. Whereas when this function returns FALSE,
1322  * notmuch_tags_get will return NULL.
1323  *
1324  * See the documentation of notmuch_message_get_tags for example code
1325  * showing how to iterate over a notmuch_tags_t object.
1326  */
1327 notmuch_bool_t
1328 notmuch_tags_valid (notmuch_tags_t *tags);
1329
1330 /* Get the current tag from 'tags' as a string.
1331  *
1332  * Note: The returned string belongs to 'tags' and has a lifetime
1333  * identical to it (and the query to which it ultimately belongs).
1334  *
1335  * See the documentation of notmuch_message_get_tags for example code
1336  * showing how to iterate over a notmuch_tags_t object.
1337  */
1338 const char *
1339 notmuch_tags_get (notmuch_tags_t *tags);
1340
1341 /* Move the 'tags' iterator to the next tag.
1342  *
1343  * If 'tags' is already pointing at the last tag then the iterator
1344  * will be moved to a point just beyond that last tag, (where
1345  * notmuch_tags_valid will return FALSE and notmuch_tags_get will
1346  * return NULL).
1347  *
1348  * See the documentation of notmuch_message_get_tags for example code
1349  * showing how to iterate over a notmuch_tags_t object.
1350  */
1351 void
1352 notmuch_tags_move_to_next (notmuch_tags_t *tags);
1353
1354 /* Destroy a notmuch_tags_t object.
1355  *
1356  * It's not strictly necessary to call this function. All memory from
1357  * the notmuch_tags_t object will be reclaimed when the containing
1358  * message or query objects are destroyed.
1359  */
1360 void
1361 notmuch_tags_destroy (notmuch_tags_t *tags);
1362
1363 /* Store an mtime within the database for 'directory'.
1364  *
1365  * The 'directory' should be an object retrieved from the database
1366  * with notmuch_database_get_directory for a particular path.
1367  *
1368  * The intention is for the caller to use the mtime to allow efficient
1369  * identification of new messages to be added to the database. The
1370  * recommended usage is as follows:
1371  *
1372  *   o Read the mtime of a directory from the filesystem
1373  *
1374  *   o Call add_message for all mail files in the directory
1375  *
1376  *   o Call notmuch_directory_set_mtime with the mtime read from the
1377  *     filesystem.
1378  *
1379  * Then, when wanting to check for updates to the directory in the
1380  * future, the client can call notmuch_directory_get_mtime and know
1381  * that it only needs to add files if the mtime of the directory and
1382  * files are newer than the stored timestamp.
1383  *
1384  * Note: The notmuch_directory_get_mtime function does not allow the
1385  * caller to distinguish a timestamp of 0 from a non-existent
1386  * timestamp. So don't store a timestamp of 0 unless you are
1387  * comfortable with that.
1388  *
1389  * Return value:
1390  *
1391  * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database.
1392  *
1393  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
1394  *      occurred, mtime not stored.
1395  *
1396  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
1397  *      mode so directory mtime cannot be modified.
1398  */
1399 notmuch_status_t
1400 notmuch_directory_set_mtime (notmuch_directory_t *directory,
1401                              time_t mtime);
1402
1403 /* Get the mtime of a directory, (as previously stored with
1404  * notmuch_directory_set_mtime).
1405  *
1406  * Returns 0 if no mtime has previously been stored for this
1407  * directory.*/
1408 time_t
1409 notmuch_directory_get_mtime (notmuch_directory_t *directory);
1410
1411 /* Get a notmuch_filenames_t iterator listing all the filenames of
1412  * messages in the database within the given directory.
1413  *
1414  * The returned filenames will be the basename-entries only (not
1415  * complete paths). */
1416 notmuch_filenames_t *
1417 notmuch_directory_get_child_files (notmuch_directory_t *directory);
1418
1419 /* Get a notmuch_filenams_t iterator listing all the filenames of
1420  * sub-directories in the database within the given directory.
1421  *
1422  * The returned filenames will be the basename-entries only (not
1423  * complete paths). */
1424 notmuch_filenames_t *
1425 notmuch_directory_get_child_directories (notmuch_directory_t *directory);
1426
1427 /* Destroy a notmuch_directory_t object. */
1428 void
1429 notmuch_directory_destroy (notmuch_directory_t *directory);
1430
1431 /* Is the given 'filenames' iterator pointing at a valid filename.
1432  *
1433  * When this function returns TRUE, notmuch_filenames_get will return
1434  * a valid string. Whereas when this function returns FALSE,
1435  * notmuch_filenames_get will return NULL.
1436  *
1437  * It is acceptable to pass NULL for 'filenames', in which case this
1438  * function will always return FALSE.
1439  */
1440 notmuch_bool_t
1441 notmuch_filenames_valid (notmuch_filenames_t *filenames);
1442
1443 /* Get the current filename from 'filenames' as a string.
1444  *
1445  * Note: The returned string belongs to 'filenames' and has a lifetime
1446  * identical to it (and the directory to which it ultimately belongs).
1447  *
1448  * It is acceptable to pass NULL for 'filenames', in which case this
1449  * function will always return NULL.
1450  */
1451 const char *
1452 notmuch_filenames_get (notmuch_filenames_t *filenames);
1453
1454 /* Move the 'filenames' iterator to the next filename.
1455  *
1456  * If 'filenames' is already pointing at the last filename then the
1457  * iterator will be moved to a point just beyond that last filename,
1458  * (where notmuch_filenames_valid will return FALSE and
1459  * notmuch_filenames_get will return NULL).
1460  *
1461  * It is acceptable to pass NULL for 'filenames', in which case this
1462  * function will do nothing.
1463  */
1464 void
1465 notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);
1466
1467 /* Destroy a notmuch_filenames_t object.
1468  *
1469  * It's not strictly necessary to call this function. All memory from
1470  * the notmuch_filenames_t object will be reclaimed when the
1471  * containing directory object is destroyed.
1472  *
1473  * It is acceptable to pass NULL for 'filenames', in which case this
1474  * function will do nothing.
1475  */
1476 void
1477 notmuch_filenames_destroy (notmuch_filenames_t *filenames);
1478
1479 NOTMUCH_END_DECLS
1480
1481 #endif