* 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
*
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,
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 'progress' as a floating-point value in
+ * the range of [0.0 .. 1.0] indicating the progress made so far in
+ * the upgrade process.
+ */
+notmuch_status_t
+notmuch_database_upgrade (notmuch_database_t *database,
+ void (*progress_notify) (void *closure,
+ double progress),
+ 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,
* 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
* 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
* 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
* 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
* 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
* notmuch_message_remove_all_tags), will not be committed to the
* database until the message is thawed with notmuch_message_thaw.
*
- * Multiple calls to freeze/thaw are valid and these calls with
+ * Multiple calls to freeze/thaw are valid and these calls will
* "stack". That is there must be as many calls to thaw as to freeze
* before a message is actually thawed.
*
* notmuch_message_thaw (message);
*
* With freeze/thaw used like this, the message in the database is
- * guaranteed to have either the full set of original tag value, or
+ * guaranteed to have either the full set of original tag values, or
* the full set of new tag values, but nothing in between.
*
* Imagine the example above without freeze/thaw and the operation
*
* 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
* 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
/* 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);
projects / notmuch / blobdiff