X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=lib%2Fnotmuch.h;h=44263a6663262c6a65ef556658aba26cd8ec69f9;hb=e70df920851c6c00000b7707e3b61650548fbce7;hp=4b0539323da826d99aea2875cd0fd1583b60fb33;hpb=f5d4349921ded021756d6754d347420e68b23111;p=notmuch diff --git a/lib/notmuch.h b/lib/notmuch.h index 4b053932..44263a66 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 3 +#define LIBNOTMUCH_MINOR_VERSION 6 #define LIBNOTMUCH_MICRO_VERSION 0 @@ -112,7 +112,7 @@ typedef int notmuch_bool_t; * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function * completed without error. Any other value indicates an error. */ -typedef enum _notmuch_status { +typedef enum { /** * No error occurred. */ @@ -220,6 +220,14 @@ typedef enum _notmuch_status { * Database exists, so not (re)-created */ NOTMUCH_STATUS_DATABASE_EXISTS, + /** + * Syntax error in query + */ + NOTMUCH_STATUS_BAD_QUERY_SYNTAX, + /** + * No mail root could be deduced from parameters and environment + */ + NOTMUCH_STATUS_NO_MAIL_ROOT, /** * Not an actual status value. Just a way to find out how many * valid status values there are. @@ -316,22 +324,22 @@ typedef enum { /** * Deprecated alias for notmuch_database_open_with_config with - * config_path=error_message=NULL + * config_path="" and error_message=NULL * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) */ -/* NOTMUCH_DEPRECATED(5, 4) */ +NOTMUCH_DEPRECATED(5, 4) notmuch_status_t notmuch_database_open (const char *path, notmuch_database_mode_t mode, notmuch_database_t **database); /** * Deprecated alias for notmuch_database_open_with_config with - * config_path=NULL + * config_path="" * * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) * */ -/* NOTMUCH_DEPRECATED(5, 4) */ +NOTMUCH_DEPRECATED(5, 4) notmuch_status_t notmuch_database_open_verbose (const char *path, notmuch_database_mode_t mode, @@ -429,6 +437,8 @@ notmuch_database_open_verbose (const char *path, * @retval NOTMUCH_STATUS_NULL_POINTER: The given \a database * argument is NULL. * + * @retval NOTMUCH_STATUS_NO_CONFIG: No config file was found. Fatal. + * * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. * * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the @@ -454,6 +464,9 @@ notmuch_database_open_with_config (const char *database_path, * * For description of arguments, @see notmuch_database_open_with_config * + * For errors other then NO_DATABASE and NO_CONFIG, *database is set to + * NULL. + * * @retval NOTMUCH_STATUS_SUCCESS: Successfully loaded configuration. * * @retval NOTMUCH_STATUS_NO_CONFIG: No config file was loaded. Not fatal. @@ -485,6 +498,9 @@ notmuch_database_load_config (const char *database_path, * * For description of arguments, @see notmuch_database_open_with_config * + * In case of any failure, this function returns an error status and + * sets *database to NULL. + * * @retval NOTMUCH_STATUS_SUCCESS: Successfully created the database. * * @retval NOTMUCH_STATUS_DATABASE_EXISTS: Database already exists, not created @@ -529,11 +545,11 @@ notmuch_database_status_string (const notmuch_database_t *notmuch); * have no effect. * * For writable databases, notmuch_database_close commits all changes - * to disk before closing the database. If the caller is currently in - * an atomic section (there was a notmuch_database_begin_atomic - * without a matching notmuch_database_end_atomic), this will discard - * changes made in that atomic section (but still commit changes made - * prior to entering the atomic section). + * to disk before closing the database, unless the caller is currently + * in an atomic section (there was a notmuch_database_begin_atomic + * without a matching notmuch_database_end_atomic). In this case + * changes since the last commit are discarded. @see + * notmuch_database_end_atomic for more information. * * Return value: * @@ -670,7 +686,10 @@ notmuch_status_t notmuch_database_begin_atomic (notmuch_database_t *notmuch); /** - * Indicate the end of an atomic database operation. + * Indicate the end of an atomic database operation. If repeated + * (with matching notmuch_database_begin_atomic) "database.autocommit" + * times, commit the the transaction and all previous (non-cancelled) + * transactions to the database. * * Return value: * @@ -958,6 +977,16 @@ notmuch_query_t * notmuch_query_create (notmuch_database_t *database, const char *query_string); +typedef enum { + NOTMUCH_QUERY_SYNTAX_XAPIAN, + NOTMUCH_QUERY_SYNTAX_SEXP +} notmuch_query_syntax_t; + +notmuch_status_t +notmuch_query_create_with_syntax (notmuch_database_t *database, + const char *query_string, + notmuch_query_syntax_t syntax, + notmuch_query_t **output); /** * Sort values for notmuch_query_set_sort. */ @@ -1661,7 +1690,7 @@ notmuch_message_reindex (notmuch_message_t *message, /** * Message flags. */ -typedef enum _notmuch_message_flag { +typedef enum { NOTMUCH_MESSAGE_FLAG_MATCH, NOTMUCH_MESSAGE_FLAG_EXCLUDED, @@ -2233,6 +2262,9 @@ notmuch_message_properties_destroy (notmuch_message_properties_t *properties); * valid string. Whereas when this function returns FALSE, * notmuch_tags_get will return NULL. * + * It is acceptable to pass NULL for 'tags', in which case this + * function will always return FALSE. + * See the documentation of notmuch_message_get_tags for example code * showing how to iterate over a notmuch_tags_t object. */ @@ -2507,7 +2539,7 @@ notmuch_config_list_destroy (notmuch_config_list_t *config_list); /** * Configuration keys known to libnotmuch */ -typedef enum _notmuch_config_key { +typedef enum { NOTMUCH_CONFIG_FIRST, NOTMUCH_CONFIG_DATABASE_PATH = NOTMUCH_CONFIG_FIRST, NOTMUCH_CONFIG_MAIL_ROOT, @@ -2520,6 +2552,8 @@ typedef enum _notmuch_config_key { NOTMUCH_CONFIG_PRIMARY_EMAIL, NOTMUCH_CONFIG_OTHER_EMAIL, NOTMUCH_CONFIG_USER_NAME, + NOTMUCH_CONFIG_AUTOCOMMIT, + NOTMUCH_CONFIG_EXTRA_HEADERS, NOTMUCH_CONFIG_LAST } notmuch_config_key_t;