#define TRUE 1
#endif
+/*
+ * The library version number. This must agree with the soname
+ * version in Makefile.local.
+ */
+#define LIBNOTMUCH_MAJOR_VERSION 3
+#define LIBNOTMUCH_MINOR_VERSION 1
+#define LIBNOTMUCH_MICRO_VERSION 0
+
+/*
+ * Check the version of the notmuch library being compiled against.
+ *
+ * Return true if the library being compiled against is of the
+ * specified version or above. For example:
+ *
+ * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0)
+ * (code requiring libnotmuch 3.1.0 or above)
+ * #endif
+ *
+ * LIBNOTMUCH_CHECK_VERSION has been defined since version 3.1.0; you
+ * can use #if !defined(NOTMUCH_CHECK_VERSION) to check for versions
+ * prior to that.
+ */
+#define LIBNOTMUCH_CHECK_VERSION (major, minor, micro) \
+ (LIBNOTMUCH_MAJOR_VERSION > (major) || \
+ (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION > (minor)) || \
+ (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION == (minor) && \
+ LIBNOTMUCH_MICRO_VERSION >= (micro)))
+
typedef int notmuch_bool_t;
/* Status codes used for the return values of most functions.
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;
*
* After a successful call to notmuch_database_create, the returned
* database will be open so the caller should call
- * notmuch_database_close when finished with it.
+ * notmuch_database_destroy when finished with it.
*
* The database will not yet have any data in it
* (notmuch_database_create itself is a very cheap function). Messages
* contained within 'path' can be added to the database by calling
* notmuch_database_add_message.
*
- * In case of any failure, this function returns NULL, (after printing
- * an error message on stderr).
+ * In case of any failure, this function returns an error status and
+ * sets *database to NULL (after printing an error message on stderr).
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Successfully created the database.
+ *
+ * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL.
+ *
+ * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
+ *
+ * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the
+ * database file (such as permission denied, or file not found,
+ * etc.), or the database already exists.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
*/
-notmuch_database_t *
-notmuch_database_create (const char *path);
+notmuch_status_t
+notmuch_database_create (const char *path, notmuch_database_t **database);
typedef enum {
NOTMUCH_DATABASE_MODE_READ_ONLY = 0,
NOTMUCH_DATABASE_MODE_READ_WRITE
} notmuch_database_mode_t;
-/* XXX: I think I'd like this to take an extra argument of
- * notmuch_status_t* for returning a status value on failure. */
-
/* Open an existing notmuch database located at 'path'.
*
* The database should have been created at some time in the past,
* An existing notmuch database can be identified by the presence of a
* directory named ".notmuch" below 'path'.
*
- * The caller should call notmuch_database_close when finished with
+ * The caller should call notmuch_database_destroy when finished with
* this database.
*
- * In case of any failure, this function returns NULL, (after printing
- * an error message on stderr).
+ * In case of any failure, this function returns an error status and
+ * sets *database to NULL (after printing an error message on stderr).
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Successfully opened the database.
+ *
+ * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL.
+ *
+ * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
+ *
+ * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the
+ * database file (such as permission denied, or file not found,
+ * etc.), or the database version is unknown.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
*/
-notmuch_database_t *
+notmuch_status_t
notmuch_database_open (const char *path,
- notmuch_database_mode_t mode);
+ notmuch_database_mode_t mode,
+ notmuch_database_t **database);
-/* Close the given notmuch database, freeing all associated
- * resources. See notmuch_database_open. */
+/* Close the given notmuch database.
+ *
+ * After notmuch_database_close has been called, calls to other
+ * functions on objects derived from this database may either behave
+ * as if the database had not been closed (e.g., if the required data
+ * has been cached) or may fail with a
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION.
+ *
+ * notmuch_database_close can be called multiple times. Later calls
+ * have no effect.
+ */
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 *message, void *closure);
+
+/* 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.
+ *
+ * If the optional callback function 'status_cb' is non-NULL, it will
+ * be called with diagnostic and informational messages. The argument
+ * 'closure' is passed verbatim to any callback invoked.
+ */
+notmuch_status_t
+notmuch_database_compact (const char* path,
+ const char* backup_path,
+ notmuch_compact_status_cb_t status_cb,
+ void *closure);
+
+/* Destroy the notmuch database, closing it if necessary and freeing
+ * all associated resources.
+ */
+void
+notmuch_database_destroy (notmuch_database_t *database);
+
/* Return the database path of the given database.
*
* The return value is a string owned by notmuch so should not be
* provide progress indication to the user. If non-NULL it will be
* called periodically with 'progress' as a floating-point value in
* the range of [0.0 .. 1.0] indicating the progress made so far in
- * the upgrade process.
+ * the upgrade process. The argument 'closure' is passed verbatim to
+ * any callback invoked.
*/
notmuch_status_t
notmuch_database_upgrade (notmuch_database_t *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.
+ * If this directory object does not exist in the database, this
+ * returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory.
+ *
+ * NOTMUCH_STATUS_NULL_POINTER: The given 'directory' argument is NULL.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
+ * directory not retrieved.
*/
-notmuch_directory_t *
+notmuch_status_t
notmuch_database_get_directory (notmuch_database_t *database,
- const char *path);
+ const char *path,
+ notmuch_directory_t **directory);
/* Add a new message to the given notmuch database or associate an
* additional filename with an existing message.
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 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
+ * should be very fast). However, in some cases,
+ * notmuch_query_search_threads is very much faster when omitting
+ * 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_exclude_t omit_excluded);
+
/* Specify the sorting desired for this query. */
void
notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
notmuch_thread_get_total_messages (notmuch_thread_t *thread);
/* Get a notmuch_messages_t iterator for the top-level messages in
- * 'thread'.
+ * 'thread' in oldest-first order.
*
* This iterator will not necessarily iterate over all of the messages
* in the thread. It will only iterate over the messages in the thread
* which are not replies to other messages in the thread.
*
- * To iterate over all messages in the thread, the caller will need to
- * iterate over the result of notmuch_message_get_replies for each
- * top-level message (and do that recursively for the resulting
- * messages, etc.).
+ * The returned list will be destroyed when the thread is destroyed.
*/
notmuch_messages_t *
notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
+/* Get a notmuch_thread_t iterator for all messages in 'thread' in
+ * oldest-first order.
+ *
+ * The returned list will be destroyed when the thread is destroyed.
+ */
+notmuch_messages_t *
+notmuch_thread_get_messages (notmuch_thread_t *thread);
+
/* Get the number of messages in 'thread' that matched the search.
*
* This count includes only the messages in this thread that were
- * matched by the search from which the thread was created. Contrast
- * with notmuch_thread_get_total_messages() .
+ * matched by the search from which the thread was created and were
+ * not excluded by any exclude tags passed in with the query (see
+ * notmuch_query_add_tag_exclude). Contrast with
+ * notmuch_thread_get_total_messages() .
*/
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
/* Message flags */
typedef enum _notmuch_message_flag {
- NOTMUCH_MESSAGE_FLAG_MATCH
+ NOTMUCH_MESSAGE_FLAG_MATCH,
+ NOTMUCH_MESSAGE_FLAG_EXCLUDED
} notmuch_message_flag_t;
/* Get a value of a flag for the email corresponding to 'message'. */
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