* 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
* #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)))
* '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);
/**
* Return the database format version of the given database.
+ *
+ * @retval 0 on error
*/
unsigned int
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);
*/
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,
* 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)
*/
* use notmuch_database_index_file instead.
*
*/
-NOTMUCH_DEPRECATED(5,1)
+NOTMUCH_DEPRECATED (5, 1)
notmuch_status_t
notmuch_database_add_message (notmuch_database_t *database,
const char *filename,
* 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 explicitly present in the query, so
* 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);
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);
* 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);
* 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
+ * @returns Non-negative integer for file count.
+ * @returns Negative integer for error.
* @since libnotmuch 5.0 (notmuch 0.25)
*/
int
* 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);
*
* 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);
/**
* 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'.
*/
* 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.
* 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);
* 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.
*
*
* @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)
*/
* @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 5.1 (notmuch 0.26)
*/
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.
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.
*
*/
notmuch_status_t
notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts,
- notmuch_bool_t decrypt_policy);
+ notmuch_decryption_policy_t decrypt_policy);
/**
* Return whether to decrypt encrypted parts while indexing.
*
* @since libnotmuch 5.1 (notmuch 0.26)
*/
-notmuch_bool_t
+notmuch_decryption_policy_t
notmuch_indexopts_get_decrypt_policy (const notmuch_indexopts_t *indexopts);
/**
*/
notmuch_bool_t
notmuch_built_with (const char *name);
-/* @} */
+/**@}*/
#pragma GCC visibility pop
projects / notmuch / blobdiff