X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=bfcd47026c638df720d9d96a5811b92c4c0bc551;hp=60834fb50bb687da9d097ed5b41c15f394554854;hb=95deec1b2767695bce5f4e3dc3336859825682f7;hpb=6da656657621febf2d5b9e1ba69c8856f9882140 diff --git a/lib/notmuch.h b/lib/notmuch.h index 60834fb5..bfcd4702 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -114,6 +114,8 @@ typedef struct _notmuch_thread notmuch_thread_t; typedef struct _notmuch_messages notmuch_messages_t; typedef struct _notmuch_message notmuch_message_t; typedef struct _notmuch_tags notmuch_tags_t; +typedef struct _notmuch_directory notmuch_directory_t; +typedef struct _notmuch_files notmuch_files_t; /* Create a new, empty notmuch database located at 'path'. * @@ -178,56 +180,47 @@ notmuch_database_close (notmuch_database_t *database); const char * notmuch_database_get_path (notmuch_database_t *database); -/* Store a timestamp within the database. +/* Read the stored contents of a directory from the database. * - * 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'. - * - * 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: - * - * 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'. - * - * 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. - * - * 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. - * - * Return value: - * - * NOTMUCH_STATUS_SUCCESS: Timestamp successfully stored in database. + * Here, 'dirname' should be a path relative to the path of + * 'database' (see notmuch_database_get_path), or else should be an + * absolute filename with initial components that match the path of + * 'database'. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception - * occurred. Timestamp not stored. + * The stored mtime of the directory along with a list of messages + * and directories in the database contained in 'dirname' are + * returned in 'directory'. The entries are sorted by filename. */ notmuch_status_t -notmuch_database_set_timestamp (notmuch_database_t *database, - const char *key, time_t timestamp); +notmuch_database_read_directory (notmuch_database_t *database, + const char *filename, + notmuch_directory_t **directory); -/* Retrieve a timestamp from the database. - * - * Returns the timestamp value previously stored by calling - * notmuch_database_set_timestamp with the same value for 'key'. - * - * Returns 0 if no timestamp is stored for 'key' or if any error - * occurred querying the database. +/* Return the recorded 'mtime' for the given directory */ time_t -notmuch_database_get_timestamp (notmuch_database_t *database, - const char *key); +notmuch_directory_get_mtime (notmuch_directory_t *directory); + +/* Return a notmuch_files_t iterator for all regular files in 'directory'. + */ +notmuch_files_t * +notmuch_directory_get_files (notmuch_directory_t *directory); + +/* Return a notmuch_files_t iterator for all sub-directories of + * 'directory'. + */ +notmuch_files_t * +notmuch_directory_get_subdirs (notmuch_directory_t *directory); + +/* Does the given notmuch_files_t object contain any more results. + */ +notmuch_bool_t +notmuch_files_has_more (notmuch_files_t *files); + +/* Get the current filename from 'files' as a string. + */ +const char * +notmuch_files_get_filename (notmuch_files_t *files); /* Add a new message to the given notmuch database. * @@ -267,6 +260,19 @@ notmuch_database_add_message (notmuch_database_t *database, const char *filename, notmuch_message_t **message); +/* Remove a message from the given notmuch database. + * + * Note that the only this particular filename association is removed + * from the database. If the same message (as determined by the + * message ID) is still available via other filenames, then the + * message will persist in the database for those filenames. When the + * last filename is removed for a particular message, the database + * content for that message will be entirely removed. + */ +notmuch_status_t +notmuch_database_remove_message (notmuch_database_t *database, + const char *filename); + /* Find a message with the given message_id. * * If the database contains a message with the given message_id, then @@ -698,17 +704,33 @@ 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); +/* Remove a filename for the email corresponding to 'message'. + * + * This removes the association between a filename and a message, + * when the last filename is gone, the entire message is removed + * from the database. + */ +notmuch_status_t +notmuch_message_remove_filename (notmuch_message_t *message, + const char *filename); + /* Message flags */ typedef enum _notmuch_message_flag { NOTMUCH_MESSAGE_FLAG_MATCH,