X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=d813612b7e8973e04db0abaa7bf66daba44968a5;hp=e03a05ddba34db67b1cb428caa9da21e9192da3c;hb=87bdfbc91f65cb1031ef0ac8a804759f2061ac10;hpb=58fe8fce1d1b7b86b4914a5a476ff21411c84082

diff --git a/lib/notmuch.h b/lib/notmuch.h
index e03a05dd..d813612b 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -43,6 +43,8 @@ NOTMUCH_BEGIN_DECLS
 
 #include <time.h>
 
+#pragma GCC visibility push(default)
+
 #ifndef FALSE
 #define FALSE 0
 #endif
@@ -55,8 +57,8 @@ NOTMUCH_BEGIN_DECLS
  * The library version number.  This must agree with the soname
  * version in Makefile.local.
  */
-#define LIBNOTMUCH_MAJOR_VERSION	4
-#define LIBNOTMUCH_MINOR_VERSION	3
+#define LIBNOTMUCH_MAJOR_VERSION	5
+#define LIBNOTMUCH_MINOR_VERSION	0
 #define LIBNOTMUCH_MICRO_VERSION	0
 
 
@@ -126,15 +128,15 @@ typedef enum _notmuch_status {
     NOTMUCH_STATUS_READ_ONLY_DATABASE,
     /**
      * A Xapian exception occurred.
+     *
+     * @todo We don't really want to expose this lame XAPIAN_EXCEPTION
+     * value. Instead we should map to things like DATABASE_LOCKED or
+     * whatever.
      */
     NOTMUCH_STATUS_XAPIAN_EXCEPTION,
     /**
      * An error occurred trying to read or write to a file (this could
      * be file not found, permission denied, etc.)
-     *
-     * @todo We don't really want to expose this lame XAPIAN_EXCEPTION
-     * value. Instead we should map to things like DATABASE_LOCKED or
-     * whatever.
      */
     NOTMUCH_STATUS_FILE_ERROR,
     /**
@@ -179,6 +181,11 @@ typedef enum _notmuch_status {
      * passed to a function expecting an absolute path.
      */
     NOTMUCH_STATUS_PATH_ERROR,
+    /**
+     * The requested operation was ignored. Depending on the function,
+     * this may not be an actual error.
+     */
+    NOTMUCH_STATUS_IGNORED,
     /**
      * One of the arguments violates the preconditions for the
      * function, in a way not covered by a more specific argument.
@@ -812,10 +819,20 @@ notmuch_query_get_sort (const notmuch_query_t *query);
 
 /**
  * Add a tag that will be excluded from the query results by default.
- * This exclusion will be overridden if this tag appears explicitly in
+ * This exclusion will be ignored if this tag appears explicitly in
  * the query.
+ *
+ * @returns
+ *
+ * NOTMUCH_STATUS_SUCCESS: excluded was added successfully.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured.
+ *      Most likely a problem lazily parsing the query string.
+ *
+ * NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so
+ *		not excluded.
  */
-void
+notmuch_status_t
 notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
 
 /**
@@ -855,24 +872,22 @@ 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)
+ * @since libnotmuch 5.0 (notmuch 0.25)
  */
 notmuch_status_t
-notmuch_query_search_threads_st (notmuch_query_t *query,
-				 notmuch_threads_t **out);
+notmuch_query_search_threads (notmuch_query_t *query,
+			      notmuch_threads_t **out);
 
 /**
- * Like notmuch_query_search_threads_st, but without a status return.
+ * Deprecated alias for notmuch_query_search_threads.
  *
- * If a Xapian exception occurs this function will return NULL.
- *
- * @deprecated Deprecated as of libnotmuch 4.3 (notmuch 0.21). Please
- * use notmuch_query_search_threads_st instead.
+ * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please
+ * use notmuch_query_search_threads instead.
  *
  */
-NOTMUCH_DEPRECATED(4,3)
-notmuch_threads_t *
-notmuch_query_search_threads (notmuch_query_t *query);
+NOTMUCH_DEPRECATED(5,0)
+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
@@ -913,23 +928,23 @@ 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)
+ * @since libnotmuch 5 (notmuch 0.25)
  */
 notmuch_status_t
-notmuch_query_search_messages_st (notmuch_query_t *query,
-				  notmuch_messages_t **out);
+notmuch_query_search_messages (notmuch_query_t *query,
+			       notmuch_messages_t **out);
 /**
- * Like notmuch_query_search_messages, but without a status return.
- *
- * If a Xapian exception occurs this function will return NULL.
+ * Deprecated alias for notmuch_query_search_messages
  *
- * @deprecated Deprecated as of libnotmuch 4.3 (notmuch 0.21). Please use
- * notmuch_query_search_messages_st instead.
+ * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please use
+ * notmuch_query_search_messages instead.
  *
  */
-NOTMUCH_DEPRECATED(4,3)
-notmuch_messages_t *
-notmuch_query_search_messages (notmuch_query_t *query);
+
+NOTMUCH_DEPRECATED(5,0)
+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.
@@ -1010,22 +1025,21 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
  *      value of *count is not defined.
  *
- * @since libnotmuch 4.3 (notmuch 0.21)
+ * @since libnotmuch 5 (notmuch 0.25)
  */
 notmuch_status_t
-notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count);
+notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count);
 
 /**
- * like notmuch_query_count_messages_st, but without a status return.
+ * Deprecated alias for notmuch_query_count_messages
  *
- * 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.
+ * @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please
+ * use notmuch_query_count_messages instead.
  */
-NOTMUCH_DEPRECATED(4,3)
-unsigned int
-notmuch_query_count_messages (notmuch_query_t *query);
+NOTMUCH_DEPRECATED(5,0)
+notmuch_status_t
+notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count);
 
 /**
  * Return the number of threads matching a search.
@@ -1047,22 +1061,20 @@ notmuch_query_count_messages (notmuch_query_t *query);
  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
  *      value of *count is not defined.
  *
- * @since libnotmuch 4.3 (notmuch 0.21)
+ * @since libnotmuch 5 (notmuch 0.25)
  */
 notmuch_status_t
-notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count);
+notmuch_query_count_threads (notmuch_query_t *query, unsigned *count);
 
 /**
- * like notmuch_query_count_threads, but without a status return.
+ * Deprecated alias for notmuch_query_count_threads
  *
- * May return 0 in case of errors.
- *
- * @deprecated Deprecated as of libnotmuch 4.3 (notmuch 0.21). Please
+ * @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please
  * use notmuch_query_count_threads_st instead.
  */
-NOTMUCH_DEPRECATED(4,3)
-unsigned int
-notmuch_query_count_threads (notmuch_query_t *query);
+NOTMUCH_DEPRECATED(5,0)
+notmuch_status_t
+notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count);
 
 /**
  * Get the thread ID of 'thread'.
@@ -1679,7 +1691,7 @@ notmuch_message_destroy (notmuch_message_t *message);
  * @returns
  * - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL.
  * - NOTMUCH_STATUS_SUCCESS: No error occured.
-
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_status_t
 notmuch_message_get_property (notmuch_message_t *message, const char *key, const char **value);
@@ -1691,6 +1703,7 @@ notmuch_message_get_property (notmuch_message_t *message, const char *key, const
  * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
  * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
  * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_status_t
 notmuch_message_add_property (notmuch_message_t *message, const char *key, const char *value);
@@ -1704,6 +1717,7 @@ notmuch_message_add_property (notmuch_message_t *message, const char *key, const
  * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
  * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
  * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_status_t
 notmuch_message_remove_property (notmuch_message_t *message, const char *key, const char *value);
@@ -1719,6 +1733,7 @@ notmuch_message_remove_property (notmuch_message_t *message, const char *key, co
  *   read-only mode so message cannot be modified.
  * - NOTMUCH_STATUS_SUCCESS: No error occured.
  *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_status_t
 notmuch_message_remove_all_properties (notmuch_message_t *message, const char *key);
@@ -1757,6 +1772,8 @@ typedef struct _notmuch_string_map_iterator notmuch_message_properties_t;
  * notmuch_message_properties_t object. (For consistency, we do
  * provide a notmuch_message_properities_destroy function, but there's
  * no good reason to call it if the message is about to be destroyed).
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_message_properties_t *
 notmuch_message_get_properties (notmuch_message_t *message, const char *key, notmuch_bool_t exact);
@@ -1774,6 +1791,8 @@ notmuch_message_get_properties (notmuch_message_t *message, const char *key, not
  * See the documentation of notmuch_message_properties_get for example
  * code showing how to iterate over a notmuch_message_properties_t
  * object.
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_bool_t
 notmuch_message_properties_valid (notmuch_message_properties_t *properties);
@@ -1787,6 +1806,8 @@ notmuch_message_properties_valid (notmuch_message_properties_t *properties);
  *
  * See the documentation of notmuch_message_get_properties for example
  * code showing how to iterate over a notmuch_message_properties_t object.
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 void
 notmuch_message_properties_move_to_next (notmuch_message_properties_t *properties);
@@ -1795,14 +1816,18 @@ notmuch_message_properties_move_to_next (notmuch_message_properties_t *propertie
  * Return the key from the current (key,value) pair.
  *
  * this could be useful if iterating for a prefix
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 const char *
 notmuch_message_properties_key (notmuch_message_properties_t *properties);
 
 /**
- * Return the key from the current (key,value) pair.
+ * Return the value from the current (key,value) pair.
  *
  * This could be useful if iterating for a prefix.
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 const char *
 notmuch_message_properties_value (notmuch_message_properties_t *properties);
@@ -1814,6 +1839,8 @@ notmuch_message_properties_value (notmuch_message_properties_t *properties);
  * It's not strictly necessary to call this function. All memory from
  * the notmuch_message_properties_t object will be reclaimed when the
  * containing message object is destroyed.
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 void
 notmuch_message_properties_destroy (notmuch_message_properties_t *properties);
@@ -2012,6 +2039,7 @@ notmuch_filenames_destroy (notmuch_filenames_t *filenames);
 /**
  * set config 'key' to 'value'
  *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_status_t
 notmuch_database_set_config (notmuch_database_t *db, const char *key, const char *value);
@@ -2024,18 +2052,24 @@ notmuch_database_set_config (notmuch_database_t *db, const char *key, const char
  *
  * return value is allocated by malloc and should be freed by the
  * caller.
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_status_t
 notmuch_database_get_config (notmuch_database_t *db, const char *key, char **value);
 
 /**
  * Create an iterator for all config items with keys matching a given prefix
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_status_t
 notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix, notmuch_config_list_t **out);
 
 /**
  * Is 'config_list' iterator valid (i.e. _key, _value, _move_to_next can be called).
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_bool_t
 notmuch_config_list_valid (notmuch_config_list_t *config_list);
@@ -2045,6 +2079,8 @@ notmuch_config_list_valid (notmuch_config_list_t *config_list);
  *
  * return value is owned by the iterator, and will be destroyed by the
  * next call to notmuch_config_list_key or notmuch_config_list_destroy.
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 const char *
 notmuch_config_list_key (notmuch_config_list_t *config_list);
@@ -2054,6 +2090,8 @@ notmuch_config_list_key (notmuch_config_list_t *config_list);
  *
  * return value is owned by the iterator, and will be destroyed by the
  * next call to notmuch_config_list_value or notmuch config_list_destroy
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 const char *
 notmuch_config_list_value (notmuch_config_list_t *config_list);
@@ -2061,23 +2099,31 @@ notmuch_config_list_value (notmuch_config_list_t *config_list);
 
 /**
  * move 'config_list' iterator to the next pair
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 void
 notmuch_config_list_move_to_next (notmuch_config_list_t *config_list);
 
 /**
  * free any resources held by 'config_list'
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 void
 notmuch_config_list_destroy (notmuch_config_list_t *config_list);
 
 /**
  * interrogate the library for compile time features
+ *
+ * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_bool_t
 notmuch_built_with (const char *name);
 /* @} */
 
+#pragma GCC visibility pop
+
 NOTMUCH_END_DECLS
 
 #endif