X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=82fd59980b9911d1d5a33b54212fc4a374145610;hp=babd2086faf4cdaca964dc11638128542b8504d9;hb=00d2ac2b41a6dba060837244ee87edce2fd1e465;hpb=fc4e5248d29cf7264481cbff82343eade5fcc2ca diff --git a/lib/notmuch.h b/lib/notmuch.h index babd2086..82fd5998 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -101,6 +101,7 @@ typedef enum _notmuch_status { 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; @@ -133,27 +134,38 @@ typedef struct _notmuch_filenames notmuch_filenames_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, @@ -165,21 +177,72 @@ typedef enum { * 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 @@ -210,7 +273,8 @@ notmuch_database_needs_upgrade (notmuch_database_t *database); * 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, @@ -260,11 +324,22 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch); * (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. @@ -449,12 +524,47 @@ typedef enum { const char * notmuch_query_get_query_string (notmuch_query_t *query); -/* Specify whether to results should omit the excluded results rather - * than just marking them excluded. This is useful for passing a - * notmuch_messages_t not containing the excluded messages to other - * functions. */ +/* 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_messages (notmuch_query_t *query, notmuch_bool_t omit); +notmuch_query_set_omit_excluded (notmuch_query_t *query, + notmuch_exclude_t omit_excluded); /* Specify the sorting desired for this query. */ void @@ -655,20 +765,21 @@ int 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.). */ 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. + */ +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 @@ -680,7 +791,7 @@ notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread); 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 @@ -694,7 +805,7 @@ notmuch_thread_get_matched_messages (notmuch_thread_t *thread); 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 @@ -926,10 +1037,13 @@ notmuch_message_set_flag (notmuch_message_t *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