X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=0dc89547017a6e5362333e167b0105c9e16c7421;hp=2faa146838c32e48214e50e3649a00c098442779;hb=87d462a20423a25eaf4b54a90bfd538dd93da675;hpb=38f0d44a82d4a6584bd95f611dfb429057a37b62 diff --git a/lib/notmuch.h b/lib/notmuch.h index 2faa1468..0dc89547 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -43,6 +43,8 @@ NOTMUCH_BEGIN_DECLS #include +#pragma GCC visibility push(default) + #ifndef FALSE #define FALSE 0 #endif @@ -55,18 +57,18 @@ 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 3 -#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 @@ -93,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))) @@ -126,15 +128,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, /** @@ -179,6 +181,33 @@ typedef enum _notmuch_status { * 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. + */ + 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. @@ -207,6 +236,7 @@ typedef struct _notmuch_tags notmuch_tags_t; typedef struct _notmuch_directory notmuch_directory_t; typedef struct _notmuch_filenames notmuch_filenames_t; typedef struct _notmuch_config_list notmuch_config_list_t; +typedef struct _notmuch_indexopts notmuch_indexopts_t; #endif /* __DOXYGEN__ */ /** @@ -224,7 +254,7 @@ typedef struct _notmuch_config_list notmuch_config_list_t; * The database will not yet have any data in it * (notmuch_database_create itself is a very cheap function). Messages * contained within 'path' can be added to the database by calling - * notmuch_database_add_message. + * notmuch_database_index_file. * * In case of any failure, this function returns an error status and * sets *database to NULL (after printing an error message on stderr). @@ -375,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); @@ -437,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); /** @@ -495,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'. @@ -521,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, @@ -529,8 +559,10 @@ notmuch_database_get_directory (notmuch_database_t *database, notmuch_directory_t **directory); /** - * Add a new message to the given notmuch database or associate an - * additional filename with an existing message. + * Add a message file to a database, indexing it for retrieval by + * future searches. If a message already exists with the same message + * ID as the specified file, their indexes will be merged, and this + * new filename will also be associated with the existing message. * * Here, 'filename' should be a path relative to the path of * 'database' (see notmuch_database_get_path), or else should be an @@ -543,8 +575,14 @@ notmuch_database_get_directory (notmuch_database_t *database, * entire contents of the file. * * If another message with the same message ID already exists in the - * database, rather than creating a new message, this adds 'filename' - * to the list of the filenames for the existing message. + * database, rather than creating a new message, this adds the search + * terms from the identified file to the existing message's index, and + * adds 'filename' to the list of filenames known for the message. + * + * The 'indexopts' parameter can be NULL (meaning, use the indexing + * defaults from the database), or can be an explicit choice of + * indexing options that should govern the indexing of this specific + * 'filename'. * * If 'message' is not NULL, then, on successful return * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message' @@ -576,8 +614,25 @@ 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) + */ +notmuch_status_t +notmuch_database_index_file (notmuch_database_t *database, + const char *filename, + notmuch_indexopts_t *indexopts, + notmuch_message_t **message); + +/** + * Deprecated alias for notmuch_database_index_file called with + * NULL indexopts. + * + * @deprecated Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please + * use notmuch_database_index_file instead. + * */ +NOTMUCH_DEPRECATED (5, 1) notmuch_status_t notmuch_database_add_message (notmuch_database_t *database, const char *filename, @@ -609,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, @@ -667,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, @@ -807,10 +862,20 @@ notmuch_query_get_sort (const notmuch_query_t *query); /** * 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 occurred. + * 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); /** @@ -824,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)) * { @@ -850,24 +917,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 @@ -908,23 +973,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. @@ -1002,25 +1067,24 @@ 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 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. @@ -1036,28 +1100,26 @@ notmuch_query_count_messages (notmuch_query_t *query); * * 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 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'. @@ -1079,6 +1141,18 @@ notmuch_thread_get_thread_id (notmuch_thread_t *thread); int notmuch_thread_get_total_messages (notmuch_thread_t *thread); +/** + * Get the total number of files in 'thread'. + * + * This sums notmuch_message_count_files over all messages in the + * thread + * @returns Non-negative integer + * @since libnotmuch 5.0 (notmuch 0.25) + */ + +int +notmuch_thread_get_total_files (notmuch_thread_t *thread); + /** * Get a notmuch_messages_t iterator for the top-level messages in * 'thread' in oldest-first order. @@ -1273,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'. * @@ -1281,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); @@ -1320,10 +1401,20 @@ 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); +/** + * Get the total number of files associated with a message. + * @returns Non-negative integer + * @since libnotmuch 5.0 (notmuch 0.25) + */ +int +notmuch_message_count_files (notmuch_message_t *message); + /** * Get a filename for the email corresponding to 'message'. * @@ -1356,6 +1447,20 @@ notmuch_message_get_filename (notmuch_message_t *message); notmuch_filenames_t * notmuch_message_get_filenames (notmuch_message_t *message); +/** + * Re-index the e-mail corresponding to 'message' using the supplied index options + * + * Returns the status of the re-index operation. (see the return + * codes documented in notmuch_database_index_file) + * + * After reindexing, the user should discard the message object passed + * in here by calling notmuch_message_destroy, since it refers to the + * original message, not to the reindexed message. + */ +notmuch_status_t +notmuch_message_reindex (notmuch_message_t *message, + notmuch_indexopts_t *indexopts); + /** * Message flags. */ @@ -1393,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. @@ -1529,13 +1634,21 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * * A client can ensure that notmuch database tags remain synchronized * with maildir flags by calling this function after each call to - * notmuch_database_add_message. See also + * notmuch_database_index_file. See also * notmuch_message_tags_to_maildir_flags for synchronizing tag changes * back to maildir flags. */ notmuch_status_t notmuch_message_maildir_flags_to_tags (notmuch_message_t *message); +/** + * return TRUE if any filename of 'message' has maildir flag 'flag', + * FALSE otherwise. + * + */ +notmuch_bool_t +notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag); + /** * Rename message filename(s) to encode tags as maildir flags. * @@ -1551,11 +1664,11 @@ notmuch_message_maildir_flags_to_tags (notmuch_message_t *message); * its filename ends with the sequence ":2," followed by zero or more * of the following single-character flags (in ASCII order): * - * 'D' iff the message has the "draft" tag - * 'F' iff the message has the "flagged" tag - * 'P' iff the message has the "passed" tag - * 'R' iff the message has the "replied" tag - * 'S' iff the message does not have the "unread" tag + * * flag 'D' iff the message has the "draft" tag + * * flag 'F' iff the message has the "flagged" tag + * * flag 'P' iff the message has the "passed" tag + * * flag 'R' iff the message has the "replied" tag + * * flag 'S' iff the message does not have the "unread" tag * * Any existing flags unmentioned in the list above will be preserved * in the renaming. @@ -1653,6 +1766,218 @@ notmuch_message_thaw (notmuch_message_t *message); void notmuch_message_destroy (notmuch_message_t *message); +/** + * @name Message Properties + * + * This interface provides the ability to attach arbitrary (key,value) + * string pairs to a message, to remove such pairs, and to iterate + * over them. The caller should take some care as to what keys they + * 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. + * + */ +/**@{*/ +/** + * Retrieve the value for a single property key + * + * *value* is set to a string owned by the message or NULL if there is + * no such key. In the case of multiple values for the given key, the + * first one is retrieved. + * + * @returns + * - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL. + * - NOTMUCH_STATUS_SUCCESS: No error occurred. + * @since libnotmuch 4.4 (notmuch 0.23) + */ +notmuch_status_t +notmuch_message_get_property (notmuch_message_t *message, const char *key, const char **value); + +/** + * Add a (key,value) pair to a message + * + * @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 occurred. + * @since libnotmuch 4.4 (notmuch 0.23) + */ +notmuch_status_t +notmuch_message_add_property (notmuch_message_t *message, const char *key, const char *value); + +/** + * Remove a (key,value) pair from a message. + * + * It is not an error to remove a non-existant (key,value) pair + * + * @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 occurred. + * @since libnotmuch 4.4 (notmuch 0.23) + */ +notmuch_status_t +notmuch_message_remove_property (notmuch_message_t *message, const char *key, const char *value); + +/** + * Remove all (key,value) pairs from the given message. + * + * @param[in,out] message message to operate on. + * @param[in] key key to delete properties for. If NULL, delete + * properties for all keys + * @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 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 + */ +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); + +/** + * 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. + * + * 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_get_properties 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); + +/**@}*/ + /** * Is the given 'tags' iterator pointing at a valid tag. * @@ -1714,7 +2039,7 @@ notmuch_tags_destroy (notmuch_tags_t *tags); * * o Read the mtime of a directory from the filesystem * - * o Call add_message for all mail files in the directory + * o Call index_file for all mail files in the directory * * o Call notmuch_directory_set_mtime with the mtime read from the * filesystem. @@ -1845,6 +2170,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); @@ -1857,18 +2183,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); @@ -1878,6 +2210,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); @@ -1887,6 +2221,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); @@ -1894,22 +2230,90 @@ 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); + +/** + * get the current default indexing options for a given database. + * + * This object will survive until the database itself is destroyed, + * but the caller may also release it earlier with + * notmuch_indexopts_destroy. + * + * This object represents a set of options on how a message can be + * added to the index. At the moment it is a featureless stub. + * + * @since libnotmuch 5.1 (notmuch 0.26) + */ +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. + * + * @since libnotmuch 5.1 (notmuch 0.26) + */ +void +notmuch_indexopts_destroy (notmuch_indexopts_t *options); + + /** * 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