X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=50d804fa99f935fcbf00d5454b3639675aa687ef;hp=89afb6d9b0b1ff14b20e5e1bdbf9ed1cd75b1895;hb=6eaadb43adae2cca2f8023830d498ef3164f7fe9;hpb=0b9e1a2472e50bd56a5e269d51aa729a4290a92a diff --git a/lib/notmuch.h b/lib/notmuch.h index 89afb6d9..50d804fa 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 0 -#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, @@ -869,7 +869,7 @@ notmuch_query_get_sort (const notmuch_query_t *query); * * NOTMUCH_STATUS_SUCCESS: excluded was added successfully. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. + * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. * Most likely a problem lazily parsing the query string. * * NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so @@ -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); @@ -1065,7 +1067,7 @@ notmuch_threads_destroy (notmuch_threads_t *threads); * * NOTMUCH_STATUS_SUCCESS: query completed successfully. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The + * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The * value of *count is not defined. * * @since libnotmuch 5 (notmuch 0.25) @@ -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,10 +1100,10 @@ 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 occured. The + * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The * value of *count is not defined. * * @since libnotmuch 5 (notmuch 0.25) @@ -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); @@ -1345,6 +1347,14 @@ notmuch_messages_destroy (notmuch_messages_t *messages); notmuch_tags_t * notmuch_messages_collect_tags (notmuch_messages_t *messages); +/** + * Get the database associated with this message. + * + * @since libnotmuch 5.2 (notmuch 0.27) + */ +notmuch_database_t * +notmuch_message_get_database (const notmuch_message_t *message); + /** * Get the message ID of 'message'. * @@ -1353,9 +1363,8 @@ notmuch_messages_collect_tags (notmuch_messages_t *messages); * 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); @@ -1392,6 +1401,11 @@ 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.) + * + * This function also returns NULL if it triggers a Xapian exception. + * + * The returned list will be destroyed when the thread is + * destroyed. */ notmuch_messages_t * notmuch_message_get_replies (notmuch_message_t *message); @@ -1419,6 +1433,8 @@ notmuch_message_count_files (notmuch_message_t *message); * this function will arbitrarily return a single one of those * filenames. See notmuch_message_get_filenames for returning the * complete list of filenames. + * + * This function returns NULL if it triggers a Xapian exception. */ const char * notmuch_message_get_filename (notmuch_message_t *message); @@ -1432,6 +1448,8 @@ notmuch_message_get_filename (notmuch_message_t *message); * * Each filename in the iterator is an absolute filename, (the initial * component will match notmuch_database_get_path() ). + * + * This function returns NULL if it triggers a Xapian exception. */ notmuch_filenames_t * notmuch_message_get_filenames (notmuch_message_t *message); @@ -1485,9 +1503,11 @@ notmuch_message_set_flag (notmuch_message_t *message, * For the original textual representation of the Date header from the * message call notmuch_message_get_header() with a header value of * "date". + * + * Returns 0 in case of error. */ 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. @@ -1764,6 +1784,9 @@ notmuch_message_destroy (notmuch_message_t *message); * add or delete values for, as other subsystems or extensions may * depend on these properties. * + * Please see notmuch-properties(7) for more details about specific + * properties and conventions around their use. + * */ /**@{*/ /** @@ -1775,7 +1798,7 @@ notmuch_message_destroy (notmuch_message_t *message); * * @returns * - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL. - * - NOTMUCH_STATUS_SUCCESS: No error occured. + * - NOTMUCH_STATUS_SUCCESS: No error occurred. * @since libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t @@ -1787,7 +1810,7 @@ notmuch_message_get_property (notmuch_message_t *message, const char *key, const * @returns * - 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. + * - NOTMUCH_STATUS_SUCCESS: No error occurred. * @since libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t @@ -1801,7 +1824,7 @@ notmuch_message_add_property (notmuch_message_t *message, const char *key, const * @returns * - 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. + * - NOTMUCH_STATUS_SUCCESS: No error occurred. * @since libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t @@ -1816,7 +1839,7 @@ notmuch_message_remove_property (notmuch_message_t *message, const char *key, co * @returns * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in * read-only mode so message cannot be modified. - * - NOTMUCH_STATUS_SUCCESS: No error occured. + * - NOTMUCH_STATUS_SUCCESS: No error occurred. * * @since libnotmuch 4.4 (notmuch 0.23) */ @@ -1832,7 +1855,7 @@ notmuch_message_remove_all_properties (notmuch_message_t *message, const char *k * @returns * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in * read-only mode so message cannot be modified. - * - NOTMUCH_STATUS_SUCCESS: No error occured. + * - NOTMUCH_STATUS_SUCCESS: No error occurred. * * @since libnotmuch 5.1 (notmuch 0.26) */ @@ -1879,6 +1902,22 @@ typedef struct _notmuch_string_map_iterator notmuch_message_properties_t; notmuch_message_properties_t * notmuch_message_get_properties (notmuch_message_t *message, const char *key, notmuch_bool_t exact); +/** + * Return the number of properties named "key" belonging to the specific message. + * + * @param[in] message The message to examine + * @param[in] key key to count + * @param[out] count The number of matching properties associated with this message. + * + * @returns + * + * NOTMUCH_STATUS_SUCCESS: successful count, possibly some other error. + * + * @since libnotmuch 5.2 (notmuch 0.27) + */ +notmuch_status_t +notmuch_message_count_properties (notmuch_message_t *message, const char *key, unsigned int *count); + /** * Is the given *properties* iterator pointing at a valid (key,value) * pair. @@ -2230,6 +2269,41 @@ notmuch_config_list_destroy (notmuch_config_list_t *config_list); notmuch_indexopts_t * notmuch_database_get_default_indexopts (notmuch_database_t *db); +/** + * Stating a policy about how to decrypt messages. + * + * See index.decrypt in notmuch-config(1) for more details. + */ +typedef enum { + NOTMUCH_DECRYPT_FALSE, + NOTMUCH_DECRYPT_TRUE, + NOTMUCH_DECRYPT_AUTO, + NOTMUCH_DECRYPT_NOSTASH, +} notmuch_decryption_policy_t; + +/** + * Specify whether to decrypt encrypted parts while indexing. + * + * Be aware that the index is likely sufficient to reconstruct the + * cleartext of the message itself, so please ensure that the notmuch + * message index is adequately protected. DO NOT SET THIS FLAG TO TRUE + * without considering the security of your index. + * + * @since libnotmuch 5.1 (notmuch 0.26) + */ +notmuch_status_t +notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts, + notmuch_decryption_policy_t decrypt_policy); + +/** + * Return whether to decrypt encrypted parts while indexing. + * see notmuch_indexopts_set_decrypt_policy. + * + * @since libnotmuch 5.1 (notmuch 0.26) + */ +notmuch_decryption_policy_t +notmuch_indexopts_get_decrypt_policy (const notmuch_indexopts_t *indexopts); + /** * Destroy a notmuch_indexopts_t object. * @@ -2246,7 +2320,7 @@ notmuch_indexopts_destroy (notmuch_indexopts_t *options); */ notmuch_bool_t notmuch_built_with (const char *name); -/* @} */ +/**@}*/ #pragma GCC visibility pop