* 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_t **database);
/**
- * Close the given notmuch database.
+ * Commit changes and close the given notmuch database.
*
* After notmuch_database_close has been called, calls to other
* functions on objects derived from this database may either behave
* notmuch_database_close can be called multiple times. Later calls
* have no effect.
*
+ * For writable databases, notmuch_database_close commits all changes
+ * to disk before closing the database. If the caller is currently in
+ * an atomic section (there was a notmuch_database_begin_atomic
+ * without a matching notmuch_database_end_atomic), this will discard
+ * changes made in that atomic section (but still commit changes made
+ * prior to entering the atomic section).
+ *
* Return value:
*
* NOTMUCH_STATUS_SUCCESS: Successfully closed the 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
- * 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.
+ * If this function returns TRUE, then the caller may call
+ * notmuch_database_upgrade to upgrade the database. If the caller
+ * does not upgrade an out-of-date database, then some functions may
+ * 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_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
- * check if an upgrade is needed (notmuch_database_needs_upgrade) and
- * if so, upgrade with this function before making any modifications.
+ * This ensures that all current notmuch functionality will be
+ * available on the database. After opening a database in read-write
+ * 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
* provide progress indication to the user. If non-NULL it will be
*
* 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,
* authors of mail messages in the query results that belong to this
* thread.
*
+ * The string contains authors of messages matching the query first, then
+ * non-matched authors (with the two groups separated by '|'). Within
+ * each group, authors are ordered by date.
+ *
* The returned string belongs to 'thread' and as such, should not be
* modified by the caller and will only be valid for as long as the
* thread is valid, (which is until notmuch_thread_destroy or until
*/
typedef enum _notmuch_message_flag {
NOTMUCH_MESSAGE_FLAG_MATCH,
- NOTMUCH_MESSAGE_FLAG_EXCLUDED
+ NOTMUCH_MESSAGE_FLAG_EXCLUDED,
+
+ /* This message is a "ghost message", meaning it has no filenames
+ * or content, but we know it exists because it was referenced by
+ * some other message. A ghost message has only a message ID and
+ * thread ID.
+ */
+ NOTMUCH_MESSAGE_FLAG_GHOST,
} notmuch_message_flag_t;
/**