NOTMUCH_STATUS_TAG_TOO_LONG,
NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
NOTMUCH_STATUS_UNBALANCED_ATOMIC,
+ NOTMUCH_STATUS_UNSUPPORTED_OPERATION,
NOTMUCH_STATUS_LAST_STATUS
} notmuch_status_t;
void
notmuch_database_close (notmuch_database_t *database);
+/* A callback invoked by notmuch_database_compact to notify the user
+ * of the progress of the compaction process.
+ */
+typedef void (*notmuch_compact_status_cb_t)(const char*);
+
+/* Compact a notmuch database, backing up the original database to the
+ * given path.
+ *
+ * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE
+ * during the compaction process to ensure no writes are made.
+ *
+ */
+notmuch_status_t
+notmuch_database_compact (const char* path,
+ const char* backup_path,
+ notmuch_compact_status_cb_t status_cb);
+
/* Destroy the notmuch database, closing it if necessary and freeing
-* all associated resources. */
+ * all associated resources.
+ */
void
notmuch_database_destroy (notmuch_database_t *database);
const char *
notmuch_query_get_query_string (notmuch_query_t *query);
+/* Exclude values for notmuch_query_set_omit_excluded. The strange
+ * order is to maintain backward compatibility: the old FALSE/TRUE
+ * options correspond to the new
+ * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
+ */
+typedef enum {
+ NOTMUCH_EXCLUDE_FLAG,
+ NOTMUCH_EXCLUDE_TRUE,
+ NOTMUCH_EXCLUDE_FALSE,
+ NOTMUCH_EXCLUDE_ALL
+} notmuch_exclude_t;
+
/* Specify whether to omit excluded results or simply flag them. By
* default, this is set to TRUE.
*
- * If this is TRUE, notmuch_query_search_messages will omit excluded
- * messages from the results. notmuch_query_search_threads will omit
- * threads that match only in excluded messages, but will include all
- * messages in threads that match in at least one non-excluded
- * message.
+ * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded
+ * messages from the results, and notmuch_query_search_threads will omit
+ * threads that match only in excluded messages. If set to TRUE,
+ * notmuch_query_search_threads will include all messages in threads that
+ * match in at least one non-excluded message. Otherwise, if set to ALL,
+ * notmuch_query_search_threads will omit excluded messages from all threads.
+ *
+ * If set to FALSE or FLAG then both notmuch_query_search_messages and
+ * notmuch_query_search_threads will return all matching
+ * messages/threads regardless of exclude status. If set to FLAG then
+ * the exclude flag will be set for any excluded message that is
+ * returned by notmuch_query_search_messages, and the thread counts
+ * for threads returned by notmuch_query_search_threads will be the
+ * number of non-excluded messages/matches. Otherwise, if set to
+ * FALSE, then the exclude status is completely ignored.
*
* The performance difference when calling
* notmuch_query_search_messages should be relatively small (and both
* excluded messages as it does not need to construct the threads that
* only match in excluded messages.
*/
-
void
-notmuch_query_set_omit_excluded (notmuch_query_t *query, notmuch_bool_t omit_excluded);
+notmuch_query_set_omit_excluded (notmuch_query_t *query,
+ notmuch_exclude_t omit_excluded);
/* Specify the sorting desired for this query. */
void
int
notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
-/* Get the authors of 'thread'
+/* Get the authors of 'thread' as a UTF-8 string.
*
* The returned string is a comma-separated list of the names of the
* authors of mail messages in the query results that belong to this
const char *
notmuch_thread_get_authors (notmuch_thread_t *thread);
-/* Get the subject of 'thread'
+/* Get the subject of 'thread' as a UTF-8 string.
*
* The subject is taken from the first message (according to the query
* order---see notmuch_query_set_sort) in the query results that
time_t
notmuch_message_get_date (notmuch_message_t *message);
-/* Get the value of the specified header from 'message'.
+/* Get the value of the specified header from 'message' as a UTF-8 string.
+ *
+ * Common headers are stored in the database when the message is
+ * indexed and will be returned from the database. Other headers will
+ * be read from the actual message file.
*
- * The value will be read from the actual message file, not from the
- * notmuch database. The header name is case insensitive.
+ * The header name is case insensitive.
*
* The returned string belongs to the message so should not be
* modified or freed by the caller (nor should it be referenced after