diff options
author | Carl Worth <cworth@cworth.org> | 2010-01-07 18:26:31 -0800 |
---|---|---|
committer | Carl Worth <cworth@cworth.org> | 2010-01-07 18:26:31 -0800 |
commit | 909f52bd8c4bdfa11cd3e75e3d0959e0293689bd (patch) | |
tree | 888ebc24e2b975d6c390e610c108a9e9fb4ecce9 /lib/notmuch.h | |
parent | 21f8fd6967c3ef8e726652bbd6944e29975508b5 (diff) |
lib: Implement versioning in the database and provide upgrade function.
The recent support for renames in the database is our first time
(since notmuch has had more than a single user) that we have a
database format change. To support smooth upgrades we now encode a
database format version number in the Xapian metadata.
Going forward notmuch will emit a warning if used to read from a
database with a newer version than it natively supports, and will
refuse to write to a database with a newer version.
The library also provides functions to query the database format
version:
notmuch_database_get_version
to ask if notmuch wants a newer version than that:
notmuch_database_needs_upgrade
and a function to actually perform that upgrade:
notmuch_database_upgrade
Diffstat (limited to 'lib/notmuch.h')
-rw-r--r-- | lib/notmuch.h | 38 |
1 files changed, 33 insertions, 5 deletions
diff --git a/lib/notmuch.h b/lib/notmuch.h index eae0fb5..d8508df 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -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, @@ -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); |