X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=85b56bf1e4c34e96fe37e4df7a06eb4b762f2e75;hp=b1f5bfa161f77853b8c4e40a90605c6595e1ab91;hb=727fcd18c6a3897622582e71a2d71081e3ae40ea;hpb=765556c1f159ae0a29137c935c7cbf4106569e7e

diff --git a/lib/notmuch.h b/lib/notmuch.h
index b1f5bfa1..85b56bf1 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -313,7 +313,7 @@ notmuch_database_open_verbose (const char *path,
  *
  */
 const char *
-notmuch_database_status_string (notmuch_database_t *notmuch);
+notmuch_database_status_string (const notmuch_database_t *notmuch);
 
 /**
  * Commit changes and close the given notmuch database.
@@ -467,6 +467,24 @@ notmuch_database_begin_atomic (notmuch_database_t *notmuch);
 notmuch_status_t
 notmuch_database_end_atomic (notmuch_database_t *notmuch);
 
+/**
+ * Return the committed database revision and UUID.
+ *
+ * The database revision number increases monotonically with each
+ * commit to the database.  Hence, all messages and message changes
+ * committed to the database (that is, visible to readers) have a last
+ * modification revision <= the committed database revision.  Any
+ * messages committed in the future will be assigned a modification
+ * revision > the committed database revision.
+ *
+ * The UUID is a NUL-terminated opaque string that uniquely identifies
+ * this database.  Two revision numbers are only comparable if they
+ * have the same database UUID.
+ */
+unsigned long
+notmuch_database_get_revision (notmuch_database_t *notmuch,
+				const char **uuid);
+
 /**
  * Retrieve a directory object from the database for 'path'.
  *
@@ -710,13 +728,13 @@ typedef enum {
  * Return the query_string of this query. See notmuch_query_create.
  */
 const char *
-notmuch_query_get_query_string (notmuch_query_t *query);
+notmuch_query_get_query_string (const notmuch_query_t *query);
 
 /**
  * Return the notmuch database of this query. See notmuch_query_create.
  */
 notmuch_database_t *
-notmuch_query_get_database (notmuch_query_t *query);
+notmuch_query_get_database (const notmuch_query_t *query);
 
 /**
  * Exclude values for notmuch_query_set_omit_excluded. The strange
@@ -773,7 +791,7 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  * notmuch_query_set_sort.
  */
 notmuch_sort_t
-notmuch_query_get_sort (notmuch_query_t *query);
+notmuch_query_get_sort (const notmuch_query_t *query);
 
 /**
  * Add a tag that will be excluded from the query results by default.
@@ -820,6 +838,7 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
  * notmuch_threads_destroy function, but there's no good reason
  * to call it if the query is about to be destroyed).
  *
+ * @since libnotmuch 4.2 (notmuch 0.20)
  */
 notmuch_status_t
 notmuch_query_search_threads_st (notmuch_query_t *query,
@@ -877,6 +896,7 @@ notmuch_query_search_threads (notmuch_query_t *query);
  *
  * If a Xapian exception occurs this function will return NULL.
  *
+ * @since libnotmuch 4.2 (notmuch 0.20)
  */
 notmuch_status_t
 notmuch_query_search_messages_st (notmuch_query_t *query,
@@ -966,10 +986,28 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
  * 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).
+ * @returns
+ *
+ * NOTMUCH_STATUS_SUCCESS: query completed successfully.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
+ *      value of *count is not defined.
+ *
+ * @since libnotmuch 4.3 (notmuch 0.21)
  */
-unsigned
+notmuch_status_t
+notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count);
+
+/**
+ * like notmuch_query_count_messages_st, but without a status return.
+ *
+ * May return 0 in the case of errors.
+ *
+ * @deprecated Deprecated since libnotmuch 4.3 (notmuch 0.21). Please
+ * use notmuch_query_count_messages_st instead.
+ */
+NOTMUCH_DEPRECATED(4,3)
+unsigned int
 notmuch_query_count_messages (notmuch_query_t *query);
 
 /**
@@ -980,11 +1018,33 @@ notmuch_query_count_messages (notmuch_query_t *query);
  * search.
  *
  * Note that this is a significantly heavier operation than
- * notmuch_query_count_messages().
+ * notmuch_query_count_messages{_st}().
+ *
+ * @returns
  *
- * If an error occurs, this function may return 0.
+ * NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value
+ *      of *count is not defined
+
+ * NOTMUCH_STATUS_SUCCESS: query completed successfully.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
+ *      value of *count is not defined.
+ *
+ * @since libnotmuch 4.3 (notmuch 0.21)
  */
-unsigned
+notmuch_status_t
+notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count);
+
+/**
+ * like notmuch_query_count_threads, but without a status return.
+ *
+ * May return 0 in case of errors.
+ *
+ * @deprecated Deprecated as of libnotmuch 4.3 (notmuch 0.21). Please
+ * use notmuch_query_count_threads_st instead.
+ */
+NOTMUCH_DEPRECATED(4,3)
+unsigned int
 notmuch_query_count_threads (notmuch_query_t *query);
 
 /**
@@ -1701,6 +1761,16 @@ notmuch_directory_get_child_files (notmuch_directory_t *directory);
 notmuch_filenames_t *
 notmuch_directory_get_child_directories (notmuch_directory_t *directory);
 
+/**
+ * Delete directory document from the database, and destroy the
+ * notmuch_directory_t object. Assumes any child directories and files
+ * have been deleted by the caller.
+ *
+ * @since libnotmuch 4.3 (notmuch 0.21)
+ */
+notmuch_status_t
+notmuch_directory_delete (notmuch_directory_t *directory);
+
 /**
  * Destroy a notmuch_directory_t object.
  */