X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=247f6ad71ebf1223b32f1c2b5e226261a309ffc1;hp=f26565f356d49e3c5906d1f833562ff9f866c510;hb=e49398dcada520c03ccd95d6b26900f5aa2d857e;hpb=3445385f95c4e28312466f07d25c51c2b7273d3e diff --git a/lib/notmuch.h b/lib/notmuch.h index f26565f3..247f6ad7 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -58,7 +58,7 @@ NOTMUCH_BEGIN_DECLS * version in Makefile.local. */ #define LIBNOTMUCH_MAJOR_VERSION 5 -#define LIBNOTMUCH_MINOR_VERSION 0 +#define LIBNOTMUCH_MINOR_VERSION 2 #define LIBNOTMUCH_MICRO_VERSION 0 @@ -191,6 +191,23 @@ typedef enum _notmuch_status { * function, in a way not covered by a more specific argument. */ NOTMUCH_STATUS_ILLEGAL_ARGUMENT, + /** + * A MIME object claimed to have cryptographic protection which + * notmuch tried to handle, but the protocol was not specified in + * an intelligible way. + */ + NOTMUCH_STATUS_MALFORMED_CRYPTO_PROTOCOL, + /** + * Notmuch attempted to do crypto processing, but could not + * initialize the engine needed to do so. + */ + NOTMUCH_STATUS_FAILED_CRYPTO_CONTEXT_CREATION, + /** + * A MIME object claimed to have cryptographic protection, and + * notmuch attempted to process it, but the specific protocol was + * something that notmuch doesn't know how to handle. + */ + NOTMUCH_STATUS_UNKNOWN_CRYPTO_PROTOCOL, /** * Not an actual status value. Just a way to find out how many * valid status values there are. @@ -852,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 @@ -1048,7 +1065,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) @@ -1084,7 +1101,7 @@ notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count); * 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) @@ -1328,6 +1345,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'. * @@ -1747,6 +1772,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. + * */ /**@{*/ /** @@ -1758,7 +1786,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 @@ -1770,7 +1798,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 @@ -1784,7 +1812,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 @@ -1799,13 +1827,29 @@ 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) */ notmuch_status_t notmuch_message_remove_all_properties (notmuch_message_t *message, const char *key); +/** + * Remove all (prefix*,value) pairs from the given message + * + * @param[in,out] message message to operate on. + * @param[in] prefix delete properties with keys that start with prefix. + * If NULL, delete all properties + * @returns + * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in + * read-only mode so message cannot be modified. + * - NOTMUCH_STATUS_SUCCESS: No error occurred. + * + * @since libnotmuch 5.1 (notmuch 0.26) + */ +notmuch_status_t +notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, const char *prefix); + /** * Opaque message property iterator */ @@ -1846,6 +1890,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. @@ -1856,7 +1916,7 @@ notmuch_message_get_properties (notmuch_message_t *message, const char *key, not * 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 + * See the documentation of notmuch_message_get_properties for example * code showing how to iterate over a notmuch_message_properties_t * object. * @@ -2197,6 +2257,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. *