X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=c66e78b1941226617285537338efe4ef7d90f293;hp=693e507602942ce88dde01b5ba598552e193ec24;hb=6c84dee53193a78cf797b44d3febcc14488ea6b1;hpb=96befd0dd075c5d3a63902d72eff7fc1928ba541 diff --git a/lib/notmuch.h b/lib/notmuch.h index 693e5076..c66e78b1 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -58,7 +58,7 @@ NOTMUCH_BEGIN_DECLS * version in Makefile.local. */ #define LIBNOTMUCH_MAJOR_VERSION 5 -#define LIBNOTMUCH_MINOR_VERSION 2 +#define LIBNOTMUCH_MINOR_VERSION 3 #define LIBNOTMUCH_MICRO_VERSION 0 @@ -431,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); @@ -444,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); @@ -1378,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); @@ -1486,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'. */ @@ -1610,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 exception was thrown + * accessing the database. */ notmuch_status_t notmuch_message_remove_all_tags (notmuch_message_t *message); @@ -1655,10 +1687,32 @@ 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. * @@ -1820,7 +1874,7 @@ notmuch_message_add_property (notmuch_message_t *message, const char *key, const /** * Remove a (key,value) pair from a message. * - * It is not an error to remove a non-existant (key,value) pair + * It is not an error to remove a non-existent (key,value) pair * * @returns * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character. @@ -2094,6 +2148,8 @@ notmuch_directory_get_mtime (notmuch_directory_t *directory); * * The returned filenames will be the basename-entries only (not * complete paths). + * + * Returns NULL if it triggers a Xapian exception */ notmuch_filenames_t * notmuch_directory_get_child_files (notmuch_directory_t *directory); @@ -2104,6 +2160,8 @@ notmuch_directory_get_child_files (notmuch_directory_t *directory); * * The returned filenames will be the basename-entries only (not * complete paths). + * + * Returns NULL if it triggers a Xapian exception */ notmuch_filenames_t * notmuch_directory_get_child_directories (notmuch_directory_t *directory); @@ -2233,6 +2291,7 @@ notmuch_config_list_key (notmuch_config_list_t *config_list); * next call to notmuch_config_list_value or notmuch config_list_destroy * * @since libnotmuch 4.4 (notmuch 0.23) + * @retval NULL for errors */ const char * notmuch_config_list_value (notmuch_config_list_t *config_list); @@ -2266,6 +2325,7 @@ notmuch_config_list_destroy (notmuch_config_list_t *config_list); * added to the index. At the moment it is a featureless stub. * * @since libnotmuch 5.1 (notmuch 0.26) + * @retval NULL in case of error */ notmuch_indexopts_t * notmuch_database_get_default_indexopts (notmuch_database_t *db);