* The operation is not supported.
*/
NOTMUCH_STATUS_UNSUPPORTED_OPERATION,
+ /**
+ * The operation requires a database upgrade.
+ */
+ NOTMUCH_STATUS_UPGRADE_REQUIRED,
/**
* Not an actual status value. Just a way to find out how many
* valid status values there are.
*
* notmuch_database_close can be called multiple times. Later calls
* have no effect.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Successfully closed the database.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; the
+ * database has been closed but there are no guarantees the
+ * changes to the database, if any, have been flushed to disk.
*/
-void
+notmuch_status_t
notmuch_database_close (notmuch_database_t *database);
/**
/**
* Destroy the notmuch database, closing it if necessary and freeing
* all associated resources.
+ *
+ * Return value as in notmuch_database_close if the database was open;
+ * notmuch_database_destroy itself has no failure modes.
*/
-void
+notmuch_status_t
notmuch_database_destroy (notmuch_database_t *database);
/**
* If this directory object does not exist in the database, this
* returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL.
*
+ * Otherwise the returned directory object is owned by the database
+ * and as such, will only be valid until notmuch_database_destroy is
+ * called.
+ *
* Return value:
*
* NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory.
*
* NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
* directory not retrieved.
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ * database to use this function.
*/
notmuch_status_t
notmuch_database_get_directory (notmuch_database_t *database,
*
* NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
* mode so no message can be added.
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ * database to use this function.
*/
notmuch_status_t
notmuch_database_add_message (notmuch_database_t *database,
*
* NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
* mode so no message can be removed.
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ * database to use this function.
*/
notmuch_status_t
notmuch_database_remove_message (notmuch_database_t *database,
* NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message object
*
* NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ * database to use this function.
*/
notmuch_status_t
notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
* valid object. Whereas when this function returns FALSE,
* notmuch_threads_get will return NULL.
*
+ * If passed a NULL pointer, this function returns FALSE
+ *
* See the documentation of notmuch_query_search_threads for example
* code showing how to iterate over a notmuch_threads_t object.
*/
*
* for (tags = notmuch_thread_get_tags (thread);
* notmuch_tags_valid (tags);
- * notmuch_result_move_to_next (tags))
+ * notmuch_tags_move_to_next (tags))
* {
* tag = notmuch_tags_get (tags);
* ....
*
* for (tags = notmuch_message_get_tags (message);
* notmuch_tags_valid (tags);
- * notmuch_result_move_to_next (tags))
+ * notmuch_tags_move_to_next (tags))
* {
* tag = notmuch_tags_get (tags);
* ....