X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=0dc89547017a6e5362333e167b0105c9e16c7421;hp=d374dc960fe67b4ccc1b096dc41c240d0779d808;hb=87d462a20423a25eaf4b54a90bfd538dd93da675;hpb=d877240f4e097eb3dd477409a24155c10e0b3c17 diff --git a/lib/notmuch.h b/lib/notmuch.h index d374dc96..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 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 @@ -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))) @@ -189,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. @@ -217,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__ */ /** @@ -234,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). @@ -385,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); @@ -447,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); /** @@ -505,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'. @@ -531,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, @@ -539,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 @@ -553,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' @@ -586,9 +614,26 @@ 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, notmuch_message_t **message); @@ -619,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, @@ -677,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, @@ -824,10 +869,10 @@ 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 explicitely present in the query, so + * NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so * not excluded. */ notmuch_status_t @@ -844,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)) * { @@ -883,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); @@ -939,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); @@ -1020,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) @@ -1035,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); @@ -1053,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) @@ -1070,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); @@ -1094,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. @@ -1288,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'. * @@ -1296,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); @@ -1335,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'. * @@ -1371,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. */ @@ -1408,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. @@ -1544,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. * @@ -1566,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. @@ -1677,6 +1775,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. + * */ /**@{*/ /** @@ -1688,7 +1789,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 @@ -1700,7 +1801,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 @@ -1714,7 +1815,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 @@ -1729,13 +1830,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 */ @@ -1776,6 +1893,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. @@ -1786,7 +1919,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. * @@ -1906,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. @@ -2111,6 +2244,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 * @@ -2118,7 +2311,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