X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=fe01e7321494ad936ad254544d125eb2ce6f99bb;hp=0d9cb0f597399332e84c34b94331b4d445e1e3c0;hb=088801a14ab1ccf4c65e5bf7b50b3a1172c477d7;hpb=7f2629520cedf32157868610882600ac3d08f2cf diff --git a/lib/notmuch.h b/lib/notmuch.h index 0d9cb0f5..fe01e732 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -156,7 +156,7 @@ typedef enum { * (not necessarily by this process), by calling * notmuch_database_create with 'path'. By default the database should be * opened for reading only. In order to write to the database you need to - * pass the NOTMUCH_DATABASE_MODE_WRITABLE mode. + * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode. * * An existing notmuch database can be identified by the presence of a * directory named ".notmuch" below 'path'. @@ -219,6 +219,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 +238,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,9 +249,13 @@ 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. + * ID as another message already in the database. The new + * filename was successfully added to the message in the database + * (if not already present). * * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the * file, (such as permission denied, or file not found, @@ -279,6 +286,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. @@ -296,8 +306,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, @@ -324,7 +337,8 @@ notmuch_database_get_all_tags (notmuch_database_t *db); * * http://xapian.org/docs/queryparser.html * - * As a special case, passing a length-zero string, (that is ""), will + * As a special case, passing either a length-zero string, (that is ""), + * or a string consisting of a single asterisk (that is "*"), will * result in a query that returns all messages in the database. * * See notmuch_query_set_sort for controlling the order of results. @@ -344,13 +358,22 @@ notmuch_query_create (notmuch_database_t *database, typedef enum { NOTMUCH_SORT_OLDEST_FIRST, NOTMUCH_SORT_NEWEST_FIRST, - NOTMUCH_SORT_MESSAGE_ID + NOTMUCH_SORT_MESSAGE_ID, + 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 @@ -386,6 +409,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); @@ -425,6 +450,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); @@ -492,6 +519,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); @@ -750,6 +780,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'. */ @@ -866,6 +897,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