X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=lib%2Fnotmuch.h;h=20c4e0190c5cdc2f9e5d5464e9ab67192d424534;hb=ee1f573204f87a0b2c20a193abf5c4d71e91f049;hp=fe2340bbcbf62470307138aee548427c65a47d3b;hpb=2c9e120e0a2efef63dbd4ec9c4f24beb30ae9167;p=notmuch

diff --git a/lib/notmuch.h b/lib/notmuch.h
index fe2340bb..20c4e019 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -55,8 +55,8 @@ NOTMUCH_BEGIN_DECLS
  * The library version number.  This must agree with the soname
  * version in Makefile.local.
  */
-#define LIBNOTMUCH_MAJOR_VERSION	3
-#define LIBNOTMUCH_MINOR_VERSION	1
+#define LIBNOTMUCH_MAJOR_VERSION	4
+#define LIBNOTMUCH_MINOR_VERSION	2
 #define LIBNOTMUCH_MICRO_VERSION	0
 
 #endif /* __DOXYGEN__ */
@@ -229,6 +229,16 @@ typedef struct _notmuch_filenames notmuch_filenames_t;
 notmuch_status_t
 notmuch_database_create (const char *path, notmuch_database_t **database);
 
+/**
+ * Like notmuch_database_create, except optionally return an error
+ * message. This message is allocated by malloc and should be freed by
+ * the caller.
+ */
+notmuch_status_t
+notmuch_database_create_verbose (const char *path,
+				 notmuch_database_t **database,
+				 char **error_message);
+
 /**
  * Database open mode for notmuch_database_open.
  */
@@ -279,9 +289,27 @@ notmuch_status_t
 notmuch_database_open (const char *path,
 		       notmuch_database_mode_t mode,
 		       notmuch_database_t **database);
+/**
+ * Like notmuch_database_open, except optionally return an error
+ * message. This message is allocated by malloc and should be freed by
+ * the caller.
+ */
+
+notmuch_status_t
+notmuch_database_open_verbose (const char *path,
+			       notmuch_database_mode_t mode,
+			       notmuch_database_t **database,
+			       char **error_message);
+
+/**
+ * Retrieve last status string for given database.
+ *
+ */
+const char *
+notmuch_database_status_string (notmuch_database_t *notmuch);
 
 /**
- * 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 +320,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.
@@ -773,10 +808,18 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
  * to call it if the query is about to be destroyed).
  *
  * If a Xapian exception occurs this function will return NULL.
+ * For better error reporting, use the _st variant.
  */
 notmuch_threads_t *
 notmuch_query_search_threads (notmuch_query_t *query);
 
+/**
+ * Like notmuch_query_search_threads, but with a status return.
+ */
+notmuch_status_t
+notmuch_query_search_threads_st (notmuch_query_t *query,
+				 notmuch_threads_t **out);
+
 /**
  * Execute a query for messages, returning a notmuch_messages_t object
  * which can be used to iterate over the results. The returned
@@ -815,10 +858,18 @@ notmuch_query_search_threads (notmuch_query_t *query);
  * reason to call it if the query is about to be destroyed).
  *
  * If a Xapian exception occurs this function will return NULL.
+ * For better error reporting, use the _st variant.
  */
 notmuch_messages_t *
 notmuch_query_search_messages (notmuch_query_t *query);
 
+/**
+ * Like notmuch_query_search_messages, but with a status return.
+ */
+notmuch_status_t
+notmuch_query_search_messages_st (notmuch_query_t *query,
+				  notmuch_messages_t **out);
+
 /**
  * Destroy a notmuch_query_t along with any associated resources.
  *
@@ -886,10 +937,10 @@ void
 notmuch_threads_destroy (notmuch_threads_t *threads);
 
 /**
- * Return an estimate of the number of messages matching a search.
+ * Return the number of messages matching a search.
  *
- * This function performs a search and returns Xapian's best
- * guess as to number of matching messages.
+ * This function performs a search and returns the number of matching
+ * messages.
  *
  * If a Xapian exception occurs, this function may return 0 (after
  * printing a message).
@@ -1214,7 +1265,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;
 
 /**