X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=d8508dfd682821bdeaed809e622a71db1635086f;hp=d03373044a2b800e6ac03d7922cd1355c8ebe75e;hb=909f52bd8c4bdfa11cd3e75e3d0959e0293689bd;hpb=f93b7218c3e2d11c5b3cdd4c367a42ca7a7ede77 diff --git a/lib/notmuch.h b/lib/notmuch.h index d0337304..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, @@ -230,7 +258,7 @@ 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_READONLY_DATABASE: Database was opened in read-only + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only * mode so no message can be added. */ notmuch_status_t @@ -256,7 +284,7 @@ notmuch_database_add_message (notmuch_database_t *database, * the message persists in the database with at least one other * filename. * - * NOTMUCH_STATUS_READONLY_DATABASE: Database was opened in read-only + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only * mode so no message can be removed. */ notmuch_status_t @@ -796,7 +824,7 @@ 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_READONLY_DATABASE: Database was opened in read-only + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only * mode so message cannot be modified. */ notmuch_status_t @@ -813,7 +841,7 @@ 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_READONLY_DATABASE: Database was opened in read-only + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only * mode so message cannot be modified. */ notmuch_status_t @@ -824,7 +852,7 @@ 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_READONLY_DATABASE: Database was opened in read-only + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only * mode so message cannot be modified. */ notmuch_status_t @@ -867,7 +895,7 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * * NOTMUCH_STATUS_SUCCESS: Message successfully frozen. * - * NOTMUCH_STATUS_READONLY_DATABASE: Database was opened in read-only + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only * mode so message cannot be modified. */ notmuch_status_t @@ -980,7 +1008,7 @@ notmuch_tags_destroy (notmuch_tags_t *tags); * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception * occurred, mtime not stored. * - * NOTMUCH_STATUS_READONLY_DATABASE: Database was opened in read-only + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only * mode so directory mtime cannot be modified. */ notmuch_status_t @@ -990,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);