* 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
* #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)))
* 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.
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__ */
/**
* 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).
* '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);
*/
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);
/**
*/
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'.
* 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,
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
* 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'
* 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);
* 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,
* 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,
*
* 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
* 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))
* {
* 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);
*
*/
-NOTMUCH_DEPRECATED(5,0)
+NOTMUCH_DEPRECATED (5, 0)
notmuch_status_t
notmuch_query_search_messages_st (notmuch_query_t *query,
notmuch_messages_t **out);
*
* 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)
* @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);
*
* 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)
* @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);
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.
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'.
*
* 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);
* 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'.
*
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.
*/
* "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.
*
* 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.
*
* 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.
* 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.
+ *
*/
/**@{*/
/**
*
* @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
* @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
* @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
* @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
*/
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.
* 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.
*
*
* 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.
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
*
*/
notmuch_bool_t
notmuch_built_with (const char *name);
-/* @} */
+/**@}*/
#pragma GCC visibility pop
projects / notmuch / blobdiff