X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=0dc89547017a6e5362333e167b0105c9e16c7421;hp=247f6ad71ebf1223b32f1c2b5e226261a309ffc1;hb=87d462a20423a25eaf4b54a90bfd538dd93da675;hpb=6a9f26b4a04e20529203938a99658516876c67f3 diff --git a/lib/notmuch.h b/lib/notmuch.h index 247f6ad7..0dc89547 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -57,18 +57,18 @@ NOTMUCH_BEGIN_DECLS * The library version number. This must agree with the soname * version in Makefile.local. */ -#define LIBNOTMUCH_MAJOR_VERSION 5 -#define LIBNOTMUCH_MINOR_VERSION 2 -#define LIBNOTMUCH_MICRO_VERSION 0 +#define LIBNOTMUCH_MAJOR_VERSION 5 +#define LIBNOTMUCH_MINOR_VERSION 2 +#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) \ +#define NOTMUCH_DEPRECATED(major, minor) \ __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor))) #else -#define NOTMUCH_DEPRECATED(major,minor) __attribute__ ((deprecated)) +#define NOTMUCH_DEPRECATED(major, minor) __attribute__ ((deprecated)) #endif @@ -95,8 +95,8 @@ NOTMUCH_BEGIN_DECLS * #endif * @endcode */ -#define LIBNOTMUCH_CHECK_VERSION(major, minor, micro) \ - (LIBNOTMUCH_MAJOR_VERSION > (major) || \ +#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) && \ LIBNOTMUCH_MICRO_VERSION >= (micro))) @@ -405,8 +405,8 @@ typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure); * 'closure' is passed verbatim to any callback invoked. */ notmuch_status_t -notmuch_database_compact (const char* path, - const char* backup_path, +notmuch_database_compact (const char *path, + const char *backup_path, notmuch_compact_status_cb_t status_cb, void *closure); @@ -467,8 +467,8 @@ notmuch_database_needs_upgrade (notmuch_database_t *database); */ notmuch_status_t notmuch_database_upgrade (notmuch_database_t *database, - void (*progress_notify) (void *closure, - double progress), + void (*progress_notify)(void *closure, + double progress), void *closure); /** @@ -525,7 +525,7 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch); */ unsigned long notmuch_database_get_revision (notmuch_database_t *notmuch, - const char **uuid); + const char **uuid); /** * Retrieve a directory object from the database for 'path'. @@ -551,7 +551,7 @@ notmuch_database_get_revision (notmuch_database_t *notmuch, * directory not retrieved. * * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * database to use this function. */ notmuch_status_t notmuch_database_get_directory (notmuch_database_t *database, @@ -614,7 +614,7 @@ notmuch_database_get_directory (notmuch_database_t *database, * mode so no message can be added. * * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * database to use this function. * * @since libnotmuch 5.1 (notmuch 0.26) */ @@ -632,7 +632,7 @@ notmuch_database_index_file (notmuch_database_t *database, * use notmuch_database_index_file instead. * */ -NOTMUCH_DEPRECATED(5,1) +NOTMUCH_DEPRECATED (5, 1) notmuch_status_t notmuch_database_add_message (notmuch_database_t *database, const char *filename, @@ -664,7 +664,7 @@ notmuch_database_add_message (notmuch_database_t *database, * mode so no message can be removed. * * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * database to use this function. */ notmuch_status_t notmuch_database_remove_message (notmuch_database_t *database, @@ -722,7 +722,7 @@ notmuch_database_find_message (notmuch_database_t *database, * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred * * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * database to use this function. */ notmuch_status_t notmuch_database_find_message_by_filename (notmuch_database_t *notmuch, @@ -889,10 +889,12 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag); * notmuch_query_t *query; * notmuch_threads_t *threads; * notmuch_thread_t *thread; + * notmuch_status_t stat; * * query = notmuch_query_create (database, query_string); * - * for (threads = notmuch_query_search_threads (query); + * for (stat = notmuch_query_search_threads (query, &threads); + * stat == NOTMUCH_STATUS_SUCCESS && * notmuch_threads_valid (threads); * notmuch_threads_move_to_next (threads)) * { @@ -928,7 +930,7 @@ notmuch_query_search_threads (notmuch_query_t *query, * use notmuch_query_search_threads instead. * */ -NOTMUCH_DEPRECATED(5,0) +NOTMUCH_DEPRECATED (5, 0) notmuch_status_t notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out); @@ -984,7 +986,7 @@ notmuch_query_search_messages (notmuch_query_t *query, * */ -NOTMUCH_DEPRECATED(5,0) +NOTMUCH_DEPRECATED (5, 0) notmuch_status_t notmuch_query_search_messages_st (notmuch_query_t *query, notmuch_messages_t **out); @@ -1080,7 +1082,7 @@ notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count); * @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please * use notmuch_query_count_messages instead. */ -NOTMUCH_DEPRECATED(5,0) +NOTMUCH_DEPRECATED (5, 0) notmuch_status_t notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count); @@ -1098,7 +1100,7 @@ notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count); * * 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 occurred. The @@ -1115,7 +1117,7 @@ notmuch_query_count_threads (notmuch_query_t *query, unsigned *count); * @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please * use notmuch_query_count_threads_st instead. */ -NOTMUCH_DEPRECATED(5,0) +NOTMUCH_DEPRECATED (5, 0) notmuch_status_t notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count); @@ -1361,9 +1363,8 @@ notmuch_message_get_database (const notmuch_message_t *message); * message is valid, (which is until the query from which it derived * is destroyed). * - * This function will not return NULL since Notmuch ensures that every - * message has a unique message ID, (Notmuch will generate an ID for a - * message if the original file does not contain one). + * This function will return NULL if triggers an unhandled Xapian + * exception. */ const char * notmuch_message_get_message_id (notmuch_message_t *message); @@ -1400,6 +1401,8 @@ notmuch_message_get_thread_id (notmuch_message_t *message); * If there are no replies to 'message', this function will return * NULL. (Note that notmuch_messages_valid will accept that NULL * value as legitimate, and simply return FALSE for it.) + * + * The returned list will be destroyed when the thread is destroyed. */ notmuch_messages_t * notmuch_message_get_replies (notmuch_message_t *message); @@ -1495,7 +1498,7 @@ notmuch_message_set_flag (notmuch_message_t *message, * "date". */ time_t -notmuch_message_get_date (notmuch_message_t *message); +notmuch_message_get_date (notmuch_message_t *message); /** * Get the value of the specified header from 'message' as a UTF-8 string. @@ -2308,7 +2311,7 @@ notmuch_indexopts_destroy (notmuch_indexopts_t *options); */ notmuch_bool_t notmuch_built_with (const char *name); -/* @} */ +/**@}*/ #pragma GCC visibility pop