X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=f9e9cc413bcbe3daddde0431cbc07dc6f590a149;hp=af4efbc8a18fe030d1652a69807b9024ce75de6f;hb=f25fc8e2115fc0fa6fa2a6d1cf3ed2747e163886;hpb=fc63c1583335d3f09392a37f65edf0b795af2782 diff --git a/lib/notmuch.h b/lib/notmuch.h index af4efbc8..f9e9cc41 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 5 -#define LIBNOTMUCH_MINOR_VERSION 0 -#define LIBNOTMUCH_MICRO_VERSION 0 +#define LIBNOTMUCH_MAJOR_VERSION 5 +#define LIBNOTMUCH_MINOR_VERSION 3 +#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))) @@ -179,11 +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. @@ -212,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__ */ /** @@ -229,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). @@ -380,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); @@ -406,6 +431,8 @@ notmuch_database_get_path (notmuch_database_t *database); /** * Return the database format version of the given database. + * + * @retval 0 on error */ unsigned int notmuch_database_get_version (notmuch_database_t *database); @@ -419,6 +446,9 @@ notmuch_database_get_version (notmuch_database_t *database); * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED. This always returns * FALSE for a read-only database because there's no way to upgrade a * read-only database. + * + * Also returns FALSE if an error occurs accessing the database. + * */ notmuch_bool_t notmuch_database_needs_upgrade (notmuch_database_t *database); @@ -442,8 +472,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); /** @@ -500,7 +530,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'. @@ -526,7 +556,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, @@ -534,8 +564,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 @@ -548,8 +580,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' @@ -581,8 +619,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, @@ -614,7 +669,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, @@ -672,7 +727,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, @@ -812,10 +867,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); /** @@ -829,10 +894,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)) * { @@ -855,24 +922,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. + * Deprecated alias for notmuch_query_search_threads. * - * 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_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 +978,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. @@ -1007,25 +1072,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. @@ -1041,28 +1105,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'. @@ -1084,6 +1146,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. @@ -1278,6 +1352,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'. * @@ -1286,9 +1368,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); @@ -1302,8 +1383,8 @@ notmuch_message_get_message_id (notmuch_message_t *message); * notmuch_message_destroy on 'message' or until a query from which it * derived is destroyed). * - * This function will not return NULL since Notmuch ensures that every - * message belongs to a single thread. + * This function will return NULL if triggers an unhandled Xapian + * exception. */ const char * notmuch_message_get_thread_id (notmuch_message_t *message); @@ -1325,10 +1406,24 @@ 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); +/** + * Get the total number of files associated with a message. + * @returns Non-negative integer for file count. + * @returns Negative integer for error. + * @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'. * @@ -1344,6 +1439,8 @@ notmuch_message_get_replies (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); @@ -1357,10 +1454,26 @@ 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); +/** + * 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. */ @@ -1378,11 +1491,36 @@ typedef enum _notmuch_message_flag { /** * Get a value of a flag for the email corresponding to 'message'. + * + * returns FALSE in case of errors. + * + * @deprecated Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please + * use notmuch_message_get_flag_st instead. */ +NOTMUCH_DEPRECATED(5,3) notmuch_bool_t notmuch_message_get_flag (notmuch_message_t *message, notmuch_message_flag_t flag); +/** + * Get a value of a flag for the email corresponding to 'message'. + * + * @param message a message object + * @param flag flag to check + * @param is_set pointer to boolean to store flag value. + * + * @retval #NOTMUCH_STATUS_SUCCESS + * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL + * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database + * triggered an exception. + * + * @since libnotmuch 5.3 (notmuch 0.31) + */ +notmuch_status_t +notmuch_message_get_flag_st (notmuch_message_t *message, + notmuch_message_flag_t flag, + notmuch_bool_t *is_set); + /** * Set a value of a flag for the email corresponding to 'message'. */ @@ -1396,9 +1534,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. @@ -1500,8 +1640,10 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); * See notmuch_message_freeze for an example showing how to safely * replace tag values. * - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only - * mode so message cannot be modified. + * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in + * read-only mode so message cannot be modified. + * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an execption was thrown + * accessing the database. */ notmuch_status_t notmuch_message_remove_all_tags (notmuch_message_t *message); @@ -1534,13 +1676,43 @@ 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. + * + * Deprecated wrapper for notmuch_message_has_maildir_flag_st + * + * @returns FALSE in case of error + * @deprecated libnotmuch 5.3 (notmuch 0.31) + */ +NOTMUCH_DEPRECATED(5, 3) +notmuch_bool_t +notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag); + +/** + * check message for maildir flag + * + * @param [in,out] message message to check + * @param [in] flag flag to check for + * @param [out] is_set pointer to boolean + * + * @retval #NOTMUCH_STATUS_SUCCESS + * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL + * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database + * triggered an exception. + */ +notmuch_status_t +notmuch_message_has_maildir_flag_st (notmuch_message_t *message, + char flag, + notmuch_bool_t *is_set); + /** * Rename message filename(s) to encode tags as maildir flags. * @@ -1556,11 +1728,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. @@ -1667,6 +1839,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. + * */ /**@{*/ /** @@ -1678,7 +1853,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 @@ -1690,7 +1865,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 @@ -1704,7 +1879,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 @@ -1719,13 +1894,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 */ @@ -1766,6 +1957,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. @@ -1776,7 +1983,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. * @@ -1896,7 +2103,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. @@ -2101,6 +2308,66 @@ notmuch_config_list_move_to_next (notmuch_config_list_t *config_list); 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 * @@ -2108,7 +2375,9 @@ notmuch_config_list_destroy (notmuch_config_list_t *config_list); */ notmuch_bool_t notmuch_built_with (const char *name); -/* @} */ +/**@}*/ + +#pragma GCC visibility pop NOTMUCH_END_DECLS