X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=24944f0b84f201e9b811aff6f419aeca1e6e53bd;hp=87756838d0727f77836e419a2e7f9d5384bb1033;hb=ff9284db6ebec1e4cbd7528d63da3cdf4ea9ddff;hpb=93ee4faa4d60e78c8cfeb95580919cac07ac0eca

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 87756838..24944f0b 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -59,8 +59,17 @@ NOTMUCH_BEGIN_DECLS
 #define LIBNOTMUCH_MINOR_VERSION	3
 #define LIBNOTMUCH_MICRO_VERSION	0
 
+
+#if defined (__clang_major__) && __clang_major__ >= 3 \
+    || defined (__GNUC__) && __GNUC__ >= 5 \
+    || defined (__GNUC__) && __GNUC__ == 4 && __GNUC_MINOR__ >= 5
 #define NOTMUCH_DEPRECATED(major,minor) \
     __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor)))
+#else
+#define NOTMUCH_DEPRECATED(major,minor) __attribute__ ((deprecated))
+#endif
+
+
 #endif /* __DOXYGEN__ */
 
 /**
@@ -84,7 +93,7 @@ NOTMUCH_BEGIN_DECLS
  * #endif
  * @endcode
  */
-#define LIBNOTMUCH_CHECK_VERSION (major, minor, micro)			\
+#define LIBNOTMUCH_CHECK_VERSION(major, minor, micro)			\
     (LIBNOTMUCH_MAJOR_VERSION > (major) ||					\
      (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION > (minor)) || \
      (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION == (minor) && \
@@ -322,7 +331,9 @@ notmuch_database_status_string (const notmuch_database_t *notmuch);
  * functions on objects derived from this database may either behave
  * as if the database had not been closed (e.g., if the required data
  * has been cached) or may fail with a
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION.
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION. The only further operation
+ * permitted on the database itself is to call
+ * notmuch_database_destroy.
  *
  * notmuch_database_close can be called multiple times.  Later calls
  * have no effect.
@@ -838,6 +849,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,
@@ -895,6 +907,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,
@@ -984,10 +997,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)
+ */
+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.
  */
-unsigned
+NOTMUCH_DEPRECATED(4,3)
+unsigned int
 notmuch_query_count_messages (notmuch_query_t *query);
 
 /**
@@ -998,11 +1029,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}().
  *
- * If an error occurs, this function may return 0.
+ * @returns
+ *
+ * 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)
+ */
+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.
  */
-unsigned
+NOTMUCH_DEPRECATED(4,3)
+unsigned int
 notmuch_query_count_threads (notmuch_query_t *query);
 
 /**
@@ -1710,7 +1763,7 @@ notmuch_filenames_t *
 notmuch_directory_get_child_files (notmuch_directory_t *directory);
 
 /**
- * Get a notmuch_filenams_t iterator listing all the filenames of
+ * Get a notmuch_filenames_t iterator listing all the filenames of
  * sub-directories in the database within the given directory.
  *
  * The returned filenames will be the basename-entries only (not
@@ -1719,6 +1772,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.
  */