X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=4b01e3ad88cf0dfacc71023c22fb60816c534081;hp=251c29b58428155183fcb506fc1b880859d96c49;hb=86cbd215eb67d7b996c977352a50e70c101cb641;hpb=c2e74662bbbbf9be1fde0ae416dc2664ba3da3cd diff --git a/lib/notmuch.h b/lib/notmuch.h index 251c29b5..4b01e3ad 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 4 -#define LIBNOTMUCH_MINOR_VERSION 4 +#define LIBNOTMUCH_MAJOR_VERSION 5 +#define LIBNOTMUCH_MINOR_VERSION 0 #define LIBNOTMUCH_MICRO_VERSION 0 @@ -126,15 +126,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, /** @@ -855,24 +855,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. - * - * 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 @@ -913,23 +911,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. + * 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. @@ -1679,7 +1677,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 +1689,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 +1703,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 +1719,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 +1758,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 +1777,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 +1792,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 +1802,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 +1825,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 +2025,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 +2038,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 +2065,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 +2076,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,18 +2085,24 @@ 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);