Make maildir synchronization configurable

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index bae48a6589f62868331a3c7d7d70715d12ea706c..41820b596c19c1a73d341dd45c6d067199d799f9 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -176,6 +176,12 @@ notmuch_database_open (const char *path,
 void
 notmuch_database_close (notmuch_database_t *database);
 
+/* Sets whether maildir flags should be synchronized with notmuch
+ * tags. */
+void
+notmuch_database_set_maildir_sync (notmuch_database_t *database,
+                                  notmuch_bool_t maildir_sync);
+
 /* Return the database path of the given database.
  *
  * The return value is a string owned by notmuch so should not be
@@ -219,6 +225,8 @@ notmuch_database_upgrade (notmuch_database_t *database,
  * Here, 'path' should be a path relative to the path of 'database'
  * (see notmuch_database_get_path), or else should be an absolute path
  * with initial components that match the path of 'database'.
+ *
+ * Can return NULL if a Xapian exception occurs.
  */
 notmuch_directory_t *
 notmuch_database_get_directory (notmuch_database_t *database,
@@ -236,7 +244,8 @@ notmuch_database_get_directory (notmuch_database_t *database,
  * notmuch database will reference the filename, and will not copy the
  * entire contents of the file.
  *
- * If 'message' is not NULL, then, on successful return '*message'
+ * If 'message' is not NULL, then, on successful return
+ * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'
  * will be initialized to a message object that can be used for things
  * such as adding tags to the just-added message. The user should call
  * notmuch_message_destroy when done with the message. On any failure
@@ -246,6 +255,9 @@ notmuch_database_get_directory (notmuch_database_t *database,
  *
  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
  *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ *     message not added.
+ *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
  *     ID as another message already in the database. The new
  *     filename was successfully added to the message in the database
@@ -280,6 +292,9 @@ notmuch_database_add_message (notmuch_database_t *database,
  * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
  *     message was removed from the database.
  *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ *     message not removed.
+ *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
  *     the message persists in the database with at least one other
  *     filename.
@@ -297,8 +312,11 @@ notmuch_database_remove_message (notmuch_database_t *database,
  * a new notmuch_message_t object is returned. The caller should call
  * notmuch_message_destroy when done with the message.
  *
- * If no message is found with the given message_id or if an
- * out-of-memory situation occurs, this function returns NULL.
+ * This function returns NULL in the following situations:
+ *
+ *     * No message is found with the given message_id
+ *     * An out-of-memory situation occurs
+ *     * A Xapian exception occurs
  */
 notmuch_message_t *
 notmuch_database_find_message (notmuch_database_t *database,
@@ -350,10 +368,18 @@ typedef enum {
     NOTMUCH_SORT_UNSORTED
 } notmuch_sort_t;
 
+/* Return the query_string of this query. See notmuch_query_create. */
+const char *
+notmuch_query_get_query_string (notmuch_query_t *query);
+
 /* Specify the sorting desired for this query. */
 void
 notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
 
+/* Return the sort specified for this query. See notmuch_query_set_sort. */
+notmuch_sort_t
+notmuch_query_get_sort (notmuch_query_t *query);
+
 /* Execute a query for threads, returning a notmuch_threads_t object
  * which can be used to iterate over the results. The returned threads
  * object is owned by the query and as such, will only be valid until
@@ -389,6 +415,8 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  * notmuch_threads_t object. (For consistency, we do provide a
  * notmuch_threads_destroy function, but there's no good reason
  * to call it if the query is about to be destroyed).
+ *
+ * If a Xapian exception occurs this function will return NULL.
  */
 notmuch_threads_t *
 notmuch_query_search_threads (notmuch_query_t *query);
@@ -428,6 +456,8 @@ notmuch_query_search_threads (notmuch_query_t *query);
  * notmuch_messages_t object. (For consistency, we do provide a
  * notmuch_messages_destroy function, but there's no good
  * reason to call it if the query is about to be destroyed).
+ *
+ * If a Xapian exception occurs this function will return NULL.
  */
 notmuch_messages_t *
 notmuch_query_search_messages (notmuch_query_t *query);
@@ -495,6 +525,9 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
  *
  * This function performs a search and returns Xapian's best
  * guess as to number of matching messages.
+ *
+ * If a Xapian exception occurs, this function may return 0 (after
+ * printing a message).
  */
 unsigned
 notmuch_query_count_messages (notmuch_query_t *query);
@@ -753,6 +786,7 @@ notmuch_message_get_filename (notmuch_message_t *message);
 /* Message flags */
 typedef enum _notmuch_message_flag {
     NOTMUCH_MESSAGE_FLAG_MATCH,
+    NOTMUCH_MESSAGE_FLAG_TAGS_INVALID,
 } notmuch_message_flag_t;
 
 /* Get a value of a flag for the email corresponding to 'message'. */
@@ -869,6 +903,12 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
 notmuch_status_t
 notmuch_message_remove_all_tags (notmuch_message_t *message);
 
+/* Add or remove tags based on the maildir flags in the file name.
+ */
+notmuch_status_t
+notmuch_message_maildir_to_tags (notmuch_message_t *message,
+                                const char *filename);
+
 /* Freeze the current state of 'message' within the database.
  *
  * This means that changes to the message state, (via