X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=lib%2Fnotmuch.h;h=220839b732a94ee95a37e3958d8acffb9d59162e;hb=0d8251dbe236975e69b07de2aeb9b60df44d6929;hp=cbf2ba5cd46d192b046b3c651f63df4d16d61fa8;hpb=ec573cd54fb3ea98f37a3c3612b00fb16e34578b;p=notmuch

diff --git a/lib/notmuch.h b/lib/notmuch.h
index cbf2ba5c..220839b7 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -55,7 +55,7 @@ NOTMUCH_BEGIN_DECLS
  * The library version number.  This must agree with the soname
  * version in Makefile.local.
  */
-#define LIBNOTMUCH_MAJOR_VERSION	3
+#define LIBNOTMUCH_MAJOR_VERSION	4
 #define LIBNOTMUCH_MINOR_VERSION	1
 #define LIBNOTMUCH_MICRO_VERSION	0
 
@@ -281,7 +281,7 @@ notmuch_database_open (const char *path,
 		       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
@@ -292,6 +292,13 @@ notmuch_database_open (const char *path,
  * 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.
@@ -352,22 +359,27 @@ unsigned int
 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
@@ -968,6 +980,10 @@ notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
  * 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
@@ -1205,7 +1221,14 @@ notmuch_message_get_filenames (notmuch_message_t *message);
  */
 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;
 
 /**