X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=669e01b120b3cbbd797389f5f7f2e63e116e5e72;hp=16da8be987fda37a25e6854963ab0637c7fd04e3;hb=a18bbf7f155369f251b0513788eade23be3555d5;hpb=508b5c20fa38b17fa527af075857061f4ed81e2a diff --git a/lib/notmuch.h b/lib/notmuch.h index 16da8be9..669e01b1 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,8 +57,8 @@ 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 4 +#define LIBNOTMUCH_MAJOR_VERSION 5 +#define LIBNOTMUCH_MINOR_VERSION 0 #define LIBNOTMUCH_MICRO_VERSION 0 @@ -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). @@ -534,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 @@ -548,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' @@ -582,8 +615,25 @@ notmuch_database_get_directory (notmuch_database_t *database, * * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the * 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); @@ -812,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 occured. + * 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); /** @@ -855,24 +915,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 +971,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. @@ -1010,22 +1068,21 @@ notmuch_threads_destroy (notmuch_threads_t *threads); * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. 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. @@ -1047,22 +1104,20 @@ notmuch_query_count_messages (notmuch_query_t *query); * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. 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 +1139,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. @@ -1329,6 +1396,14 @@ notmuch_message_get_thread_id (notmuch_message_t *message); 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'. * @@ -1361,6 +1436,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. */ @@ -1534,13 +1623,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. * @@ -1556,11 +1653,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. @@ -1776,7 +1873,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 +1993,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 +2198,31 @@ 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); + +/** + * 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 * @@ -2110,6 +2232,8 @@ notmuch_bool_t notmuch_built_with (const char *name); /* @} */ +#pragma GCC visibility pop + NOTMUCH_END_DECLS #endif