X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=lib%2Fnotmuch.h;h=e96474f65861b94b30d538f5e3baebb5da4bf0c9;hb=d7e5f5827e21be7dd8993e5a877bdb73cdb64325;hp=8bba442f62b3505a8c68d7b6a03a388daca44a7c;hpb=c1e16435cfe4471c3415d9f625f7230d59c8afb4;p=notmuch diff --git a/lib/notmuch.h b/lib/notmuch.h index 8bba442f..e96474f6 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -178,56 +178,56 @@ notmuch_database_close (notmuch_database_t *database); const char * notmuch_database_get_path (notmuch_database_t *database); -/* Store a timestamp within the database. +/* Store an mtime within the database for 'path'. * - * The Notmuch database will not interpret this key nor the timestamp - * values at all. It will merely store them together and return the - * timestamp when notmuch_database_get_timestamp is called with the - * same value for 'key'. + * Here,'path' should be the path of a directory 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'. * - * The intention is for the caller to use the timestamp to allow - * efficient identification of new messages to be added to the - * database. The recommended usage is as follows: + * The intention is for the caller to use the mtime to allow efficient + * identification of new messages to be added to the database. The + * recommended usage is as follows: * * o Read the mtime of a directory from the filesystem * * o Call add_message for all mail files in the directory * - * o Call notmuch_database_set_timestamp with the path of the - * directory as 'key' and the originally read mtime as 'value'. + * o Call notmuch_database_set_directory_mtime * * Then, when wanting to check for updates to the directory in the - * future, the client can call notmuch_database_get_timestamp and know - * that it only needs to add files if the mtime of the directory and - * files are newer than the stored timestamp. + * future, the client can call notmuch_database_get_directory_mtime + * and know that it only needs to add files if the mtime of the + * directory and files are newer than the stored timestamp. * - * Note: The notmuch_database_get_timestamp function does not allow - * the caller to distinguish a timestamp of 0 from a non-existent - * timestamp. So don't store a timestamp of 0 unless you are - * comfortable with that. + * Note: The notmuch_database_get_directory_mtime function does not + * allow the caller to distinguish a timestamp of 0 from a + * non-existent timestamp. So don't store a timestamp of 0 unless you + * are comfortable with that. * * Return value: * - * NOTMUCH_STATUS_SUCCESS: Timestamp successfully stored in database. + * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database. * * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception - * occurred. Timestamp not stored. + * occurred, mtime not stored. */ notmuch_status_t -notmuch_database_set_timestamp (notmuch_database_t *database, - const char *key, time_t timestamp); +notmuch_database_set_directory_mtime (notmuch_database_t *database, + const char *path, + time_t mtime); -/* Retrieve a timestamp from the database. +/* Retrieve the mtime from the database for 'path'. * - * Returns the timestamp value previously stored by calling - * notmuch_database_set_timestamp with the same value for 'key'. + * Returns the mtime value previously stored by calling + * notmuch_database_set_directory_mtime with the same 'path'. * - * Returns 0 if no timestamp is stored for 'key' or if any error - * occurred querying the database. + * Returns 0 if no mtime is stored for 'path' or if any error occurred + * querying the database. */ time_t -notmuch_database_get_timestamp (notmuch_database_t *database, - const char *key); +notmuch_database_get_directory_mtime (notmuch_database_t *database, + const char *path); /* Add a new message to the given notmuch database. * @@ -280,6 +280,16 @@ notmuch_message_t * notmuch_database_find_message (notmuch_database_t *database, const char *message_id); +/* Return a list of all tags found in the database. + * + * This function creates a list of all tags found in the database. The + * resulting list contains all tags from all messages found in the database. + * + * On error this function returns NULL. + */ +notmuch_tags_t * +notmuch_database_get_all_tags (notmuch_database_t *db); + /* Create a new query for 'database'. * * Here, 'database' should be an open database, (see @@ -625,6 +635,21 @@ notmuch_messages_advance (notmuch_messages_t *messages); void notmuch_messages_destroy (notmuch_messages_t *messages); +/* Return a list of tags from all messages. + * + * The resulting list is guaranteed not to contain duplicated tags. + * + * WARNING: You can no longer iterate over messages after calling this + * function, because the iterator will point at the end of the list. + * We do not have a function to reset the iterator yet and the only + * way how you can iterate over the list again is to recreate the + * message list. + * + * The function returns NULL on error. + */ +notmuch_tags_t * +notmuch_messages_collect_tags (notmuch_messages_t *messages); + /* Get the message ID of 'message'. * * The returned string belongs to 'message' and as such, should not be @@ -673,17 +698,38 @@ notmuch_message_get_thread_id (notmuch_message_t *message); notmuch_messages_t * notmuch_message_get_replies (notmuch_message_t *message); -/* Get the filename for the email corresponding to 'message'. +/* Get a filename for the email corresponding to 'message'. * * The returned filename is an absolute filename, (the initial * component will match notmuch_database_get_path() ). * * The returned string belongs to the message so should not be * modified or freed by the caller (nor should it be referenced after - * the message is destroyed). */ + * the message is destroyed). + * + * Note: If this message corresponds to multiple files in the mail + * store, (that is, multiple files contain identical message IDs), + * this function will arbitrarily return a single one of those + * filenames. + */ const char * notmuch_message_get_filename (notmuch_message_t *message); +/* Message flags */ +typedef enum _notmuch_message_flag { + NOTMUCH_MESSAGE_FLAG_MATCH, +} notmuch_message_flag_t; + +/* Get a value of a flag for the email corresponding to 'message'. */ +notmuch_bool_t +notmuch_message_get_flag (notmuch_message_t *message, + notmuch_message_flag_t flag); + +/* Set a value of a flag for the email corresponding to 'message'. */ +void +notmuch_message_set_flag (notmuch_message_t *message, + notmuch_message_flag_t flag, notmuch_bool_t value); + /* Get the date of 'message' as a time_t value. * * For the original textual representation of the Date header from the