X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=d8508dfd682821bdeaed809e622a71db1635086f;hp=110061c29ae62d37e8df2b53038980d2e3a76cea;hb=909f52bd8c4bdfa11cd3e75e3d0959e0293689bd;hpb=4b418343f656c2de5503d907d075019626561373 diff --git a/lib/notmuch.h b/lib/notmuch.h index 110061c2..d8508dfd 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -57,8 +57,8 @@ typedef int notmuch_bool_t; * value. Instead we should map to things like DATABASE_LOCKED or * whatever. * - * NOTMUCH_STATUS_READONLY_DATABASE: An attempt was made to write to a - * database opened in read-only mode. + * NOTMUCH_STATUS_READ_ONLY_DATABASE: An attempt was made to write to + * a database opened in read-only mode. * * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred * @@ -89,7 +89,7 @@ typedef int notmuch_bool_t; typedef enum _notmuch_status { NOTMUCH_STATUS_SUCCESS = 0, NOTMUCH_STATUS_OUT_OF_MEMORY, - NOTMUCH_STATUS_READONLY_DATABASE, + NOTMUCH_STATUS_READ_ONLY_DATABASE, NOTMUCH_STATUS_XAPIAN_EXCEPTION, NOTMUCH_STATUS_FILE_ERROR, NOTMUCH_STATUS_FILE_NOT_EMAIL, @@ -183,15 +183,43 @@ notmuch_database_close (notmuch_database_t *database); const char * notmuch_database_get_path (notmuch_database_t *database); +/* Return the database format version of the given database. */ +unsigned int +notmuch_database_get_version (notmuch_database_t *database); + +/* Does this database need to be upgraded before writing to it? + * + * If this function returns TRUE then no functions that modify the + * database (notmuch_database_add_message, notmuch_message_add_tag, + * notmuch_directory_set_mtime, etc.) will work unless the function + * notmuch_database_upgrade is called successfully first. */ +notmuch_bool_t +notmuch_database_needs_upgrade (notmuch_database_t *database); + +/* Upgrade the current database. + * + * After opening a database in read-write mode, the client should + * check if an upgrade is needed (notmuch_database_needs_upgrade) and + * if so, upgrade with this function before making any modifications. + * + * The optional progress_notify callback can be used by the caller to + * provide progress indication to the user. If non-NULL it will be + * called periodically with 'count' as the number of messages upgraded + * so far and 'total' the overall number of messages that will be + * converted. + */ +notmuch_status_t +notmuch_database_upgrade (notmuch_database_t *database, + void (*progress_notify) (void *closure, + unsigned int count, + unsigned int total), + void *closure); + /* Retrieve a directory object from the database for 'path'. * * 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'. - * - * Note: The resulting notmuch_directory_t object will represent the - * state as it currently exists in the database, (and will not reflect - * subsequent changes). */ notmuch_directory_t * notmuch_database_get_directory (notmuch_database_t *database, @@ -229,6 +257,9 @@ notmuch_database_get_directory (notmuch_database_t *database, * * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look * like an email message. Nothing added to the database. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so no message can be added. */ notmuch_status_t notmuch_database_add_message (notmuch_database_t *database, @@ -252,6 +283,9 @@ notmuch_database_add_message (notmuch_database_t *database, * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but * the message persists in the database with at least one other * filename. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so no message can be removed. */ notmuch_status_t notmuch_database_remove_message (notmuch_database_t *database, @@ -789,6 +823,9 @@ notmuch_message_get_tags (notmuch_message_t *message); * * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long * (exceeds NOTMUCH_TAG_MAX) + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ notmuch_status_t notmuch_message_add_tag (notmuch_message_t *message, const char *tag); @@ -803,6 +840,9 @@ notmuch_message_add_tag (notmuch_message_t *message, const char *tag); * * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long * (exceeds NOTMUCH_TAG_MAX) + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ notmuch_status_t notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); @@ -811,8 +851,11 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); * * See notmuch_message_freeze for an example showing how to safely * replace tag values. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ -void +notmuch_status_t notmuch_message_remove_all_tags (notmuch_message_t *message); /* Freeze the current state of 'message' within the database. @@ -847,8 +890,15 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * somehow getting interrupted. This could result in the message being * left with no tags if the interruption happened after * notmuch_message_remove_all_tags but before notmuch_message_add_tag. + * + * Return value: + * + * NOTMUCH_STATUS_SUCCESS: Message successfully frozen. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ -void +notmuch_status_t notmuch_message_freeze (notmuch_message_t *message); /* Thaw the current 'message', synchronizing any changes that may have @@ -957,6 +1007,9 @@ notmuch_tags_destroy (notmuch_tags_t *tags); * * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception * occurred, mtime not stored. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so directory mtime cannot be modified. */ notmuch_status_t notmuch_directory_set_mtime (notmuch_directory_t *directory, @@ -965,7 +1018,7 @@ notmuch_directory_set_mtime (notmuch_directory_t *directory, /* Get the mtime of a directory, (as previously stored with * notmuch_directory_set_mtime). * - * Returns 0 if not mtime has previously been stored for this + * Returns 0 if no mtime has previously been stored for this * directory.*/ time_t notmuch_directory_get_mtime (notmuch_directory_t *directory); @@ -996,6 +1049,9 @@ notmuch_directory_destroy (notmuch_directory_t *directory); * When this function returns TRUE, notmuch_filenames_get will return * a valid string. Whereas when this function returns FALSE, * notmuch_filenames_get will return NULL. + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will always return FALSE. */ notmuch_bool_t notmuch_filenames_has_more (notmuch_filenames_t *filenames); @@ -1004,11 +1060,17 @@ notmuch_filenames_has_more (notmuch_filenames_t *filenames); * * Note: The returned string belongs to 'filenames' and has a lifetime * identical to it (and the directory to which it ultimately belongs). + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will always return NULL. */ const char * notmuch_filenames_get (notmuch_filenames_t *filenames); /* Advance the 'filenames' iterator to the next filename. + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will do nothing. */ void notmuch_filenames_advance (notmuch_filenames_t *filenames); @@ -1018,6 +1080,9 @@ notmuch_filenames_advance (notmuch_filenames_t *filenames); * It's not strictly necessary to call this function. All memory from * the notmuch_filenames_t object will be reclaimed when the * containing directory object is destroyed. + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will do nothing. */ void notmuch_filenames_destroy (notmuch_filenames_t *filenames);