#include <time.h>
+#pragma GCC visibility push(default)
+
#ifndef FALSE
#define FALSE 0
#endif
* 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
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,
/**
* 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.
/**
* 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);
/**
* 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.
- *
- * If a Xapian exception occurs this function will return NULL.
+ * Deprecated alias for notmuch_query_search_threads.
*
- * @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
*
* 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.
+ * Deprecated alias for notmuch_query_search_messages
*
- * 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_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.
* 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.
* 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.
- *
- * May return 0 in case of errors.
+ * Deprecated alias for notmuch_query_count_threads
*
- * @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'.
* @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);
* - 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);
* - 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);
* 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);
+/**
+ * Opaque message property iterator
+ */
+typedef struct _notmuch_string_map_iterator notmuch_message_properties_t;
+
+/**
+ * Get the properties for *message*, returning a
+ * notmuch_message_properties_t object which can be used to iterate
+ * over all properties.
+ *
+ * The notmuch_message_properties_t object is owned by the message and
+ * as such, will only be valid for as long as the message is valid,
+ * (which is until the query from which it derived is destroyed).
+ *
+ * @param[in] message The message to examine
+ * @param[in] key key or key prefix
+ * @param[in] exact if TRUE, require exact match with key. Otherwise
+ * treat as prefix.
+ *
+ * Typical usage might be:
+ *
+ * notmuch_message_properties_t *list;
+ *
+ * for (list = notmuch_message_get_properties (message, "testkey1", TRUE);
+ * notmuch_message_properties_valid (list); notmuch_message_properties_move_to_next (list)) {
+ * printf("%s\n", notmuch_message_properties_value(list));
+ * }
+ *
+ * notmuch_message_properties_destroy (list);
+ *
+ * Note that there's no explicit destructor needed for the
+ * 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);
+
+/**
+ * Is the given *properties* iterator pointing at a valid (key,value)
+ * pair.
+ *
+ * When this function returns TRUE,
+ * notmuch_message_properties_{key,value} will return a valid string,
+ * and notmuch_message_properties_move_to_next will do what it
+ * says. Whereas when this function returns FALSE, calling any of
+ * these functions results in undefined behaviour.
+ *
+ * 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);
+
+/**
+ * Move the *properties* iterator to the next (key,value) pair
+ *
+ * If *properties* is already pointing at the last pair then the iterator
+ * will be moved to a point just beyond that last pair, (where
+ * notmuch_message_properties_valid will return FALSE).
+ *
+ * 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);
+
+/**
+ * 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 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);
+
+
+/**
+ * Destroy a notmuch_message_properties_t object.
+ *
+ * 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);
+
/**@}*/
/**
/**
* 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);
*
* 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);
*
* 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);
*
* 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);
/**
* 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
projects / notmuch / blobdiff