debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-25 04:18:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

lib: Update doc of notmuch_database_{needs_upgrade,upgrade}

Browse source 
Clients are no longer required to call these functions after opening a
database in read/write mode (which is good, because almost none of
them do!).
This commit is contained in:
Austin Clements 2014-08-25 13:26:09 -04:00 committed by David Bremner
parent ec573cd54f
commit 658a00e7c8
1 changed files with 14 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
lib/notmuch.h
View file

@ -352,22 +352,27 @@ unsigned int
notmuch_database_get_version (notmuch_database_t *database); notmuch_database_get_version (notmuch_database_t *database);
/** /**
* Does this database need to be upgraded before writing to it? * Can the database be upgraded to a newer database version?
* *
* If this function returns TRUE then no functions that modify the * If this function returns TRUE, then the caller may call
* database (notmuch_database_add_message, notmuch_message_add_tag, * notmuch_database_upgrade to upgrade the database. If the caller
* notmuch_directory_set_mtime, etc.) will work unless the function * does not upgrade an out-of-date database, then some functions may
* notmuch_database_upgrade is called successfully first. * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED. This always returns
* FALSE for a read-only database because there's no way to upgrade a
* read-only database.
*/ */
notmuch_bool_t notmuch_bool_t
notmuch_database_needs_upgrade (notmuch_database_t *database); notmuch_database_needs_upgrade (notmuch_database_t *database);
/** /**
* Upgrade the current database. * Upgrade the current database to the latest supported version.
* *
* After opening a database in read-write mode, the client should * This ensures that all current notmuch functionality will be
* check if an upgrade is needed (notmuch_database_needs_upgrade) and * available on the database. After opening a database in read-write
* if so, upgrade with this function before making any modifications. * mode, it is recommended that clients check if an upgrade is needed
* (notmuch_database_needs_upgrade) and if so, upgrade with this
* function before making any modifications. If
* notmuch_database_needs_upgrade returns FALSE, this will be a no-op.
* *
* The optional progress_notify callback can be used by the caller to * The optional progress_notify callback can be used by the caller to
* provide progress indication to the user. If non-NULL it will be * provide progress indication to the user. If non-NULL it will be