X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=lib%2Fnotmuch.h;h=546643e80cbb66364b2502f6b8046291959d9d8b;hb=9ae4188610dc21101fe9bdeb158854fc7c63463e;hp=6d22d328ce1b57f1b04ee445aaa2e44d9efb54e6;hpb=55f5e87096fda96280ccc4b191393c7e59b4df57;p=notmuch diff --git a/lib/notmuch.h b/lib/notmuch.h index 6d22d328..546643e8 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 4 #define LIBNOTMUCH_MICRO_VERSION 0 @@ -212,10 +212,18 @@ typedef enum _notmuch_status { * Unable to load a config file */ NOTMUCH_STATUS_NO_CONFIG, + /** + * Unable to load a database + */ + NOTMUCH_STATUS_NO_DATABASE, /** * Database exists, so not (re)-created */ NOTMUCH_STATUS_DATABASE_EXISTS, + /** + * Syntax error in query + */ + NOTMUCH_STATUS_BAD_QUERY_SYNTAX, /** * Not an actual status value. Just a way to find out how many * valid status values there are. @@ -245,6 +253,7 @@ 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_config_values notmuch_config_values_t; +typedef struct _notmuch_config_pairs notmuch_config_pairs_t; typedef struct _notmuch_indexopts notmuch_indexopts_t; #endif /* __DOXYGEN__ */ @@ -311,7 +320,7 @@ 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) */ @@ -321,7 +330,7 @@ notmuch_database_open (const char *path, 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) * @@ -443,6 +452,65 @@ notmuch_database_open_with_config (const char *database_path, notmuch_database_t **database, char **error_message); + +/** + * Loads configuration from config file, database, and/or defaults + * + * For description of arguments, @see notmuch_database_open_with_config + * + * @retval NOTMUCH_STATUS_SUCCESS: Successfully loaded configuration. + * + * @retval NOTMUCH_STATUS_NO_CONFIG: No config file was loaded. Not fatal. + * + * @retval NOTMUCH_STATUS_NO_DATABASE: No config information was + * loaded from a database. Not fatal. + * + * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * + * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the + * database or config file (such as permission denied, or file not found, + * etc.) + * + * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * + * @since libnotmuch 5.4 (notmuch 0.32) + */ + +notmuch_status_t +notmuch_database_load_config (const char *database_path, + const char *config_path, + const char *profile, + notmuch_database_t **database, + char **error_message); + +/** + * Create a new notmuch database located at 'database_path', using + * configuration in 'config_path'. + * + * For description of arguments, @see notmuch_database_open_with_config + * + * @retval NOTMUCH_STATUS_SUCCESS: Successfully created the database. + * + * @retval NOTMUCH_STATUS_DATABASE_EXISTS: Database already exists, not created + * + * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * + * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the + * database or config file (such as permission denied, or file not found, + * etc.) + * + * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * + * @since libnotmuch 5.4 (notmuch 0.32) + */ + +notmuch_status_t +notmuch_database_create_with_config (const char *database_path, + const char *config_path, + const char *profile, + notmuch_database_t **database, + char **error_message); + /** * Retrieve last status string for given database. * @@ -465,11 +533,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: * @@ -606,7 +674,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: * @@ -852,6 +923,19 @@ notmuch_database_find_message_by_filename (notmuch_database_t *notmuch, notmuch_tags_t * notmuch_database_get_all_tags (notmuch_database_t *db); +/** + * Reopen an open notmuch database. + * + * @param [in] db open notmuch database + * @param [in] mode mode (read only or read-write) for reopened database. + * + * @retval #NOTMUCH_STATUS_SUCCESS + * @retval #NOTMUCH_STATUS_ILLEGAL_ARGUMENT The passed database was not open. + * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION A Xapian exception occured + */ +notmuch_status_t +notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode); + /** * Create a new query for 'database'. * @@ -881,6 +965,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. */ @@ -1604,7 +1698,7 @@ typedef enum _notmuch_message_flag { * @deprecated Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please * use notmuch_message_get_flag_st instead. */ -NOTMUCH_DEPRECATED(5,3) +NOTMUCH_DEPRECATED (5, 3) notmuch_bool_t notmuch_message_get_flag (notmuch_message_t *message, notmuch_message_flag_t flag); @@ -1799,7 +1893,7 @@ notmuch_message_maildir_flags_to_tags (notmuch_message_t *message); * @returns FALSE in case of error * @deprecated libnotmuch 5.3 (notmuch 0.31) */ -NOTMUCH_DEPRECATED(5, 3) +NOTMUCH_DEPRECATED (5, 3) notmuch_bool_t notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag); @@ -2376,7 +2470,8 @@ notmuch_database_get_config (notmuch_database_t *db, const char *key, char **val * @since libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t -notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix, notmuch_config_list_t **out); +notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix, + notmuch_config_list_t **out); /** * Is 'config_list' iterator valid (i.e. _key, _value, _move_to_next can be called). @@ -2426,13 +2521,15 @@ notmuch_config_list_move_to_next (notmuch_config_list_t *config_list); void notmuch_config_list_destroy (notmuch_config_list_t *config_list); - /** * Configuration keys known to libnotmuch */ typedef enum _notmuch_config_key { NOTMUCH_CONFIG_FIRST, NOTMUCH_CONFIG_DATABASE_PATH = NOTMUCH_CONFIG_FIRST, + NOTMUCH_CONFIG_MAIL_ROOT, + NOTMUCH_CONFIG_HOOK_DIR, + NOTMUCH_CONFIG_BACKUP_DIR, NOTMUCH_CONFIG_EXCLUDE_TAGS, NOTMUCH_CONFIG_NEW_TAGS, NOTMUCH_CONFIG_NEW_IGNORE, @@ -2440,6 +2537,7 @@ typedef enum _notmuch_config_key { NOTMUCH_CONFIG_PRIMARY_EMAIL, NOTMUCH_CONFIG_OTHER_EMAIL, NOTMUCH_CONFIG_USER_NAME, + NOTMUCH_CONFIG_AUTOCOMMIT, NOTMUCH_CONFIG_LAST } notmuch_config_key_t; @@ -2494,6 +2592,22 @@ notmuch_config_set (notmuch_database_t *notmuch, notmuch_config_key_t key, const notmuch_config_values_t * notmuch_config_get_values (notmuch_database_t *notmuch, notmuch_config_key_t key); +/** + * Returns an iterator for a ';'-delimited list of configuration values + * + * These values reflect all configuration information given at the + * time the database was opened. + * + * @param[in] notmuch database + * @param[in] key configuration key + * + * @since libnotmuch 5.4 (notmuch 0.32) + * + * @retval NULL in case of error. + */ +notmuch_config_values_t * +notmuch_config_get_values_string (notmuch_database_t *notmuch, const char *key); + /** * Is the given 'config_values' iterator pointing at a valid element. * @@ -2553,6 +2667,80 @@ notmuch_config_values_start (notmuch_config_values_t *values); void notmuch_config_values_destroy (notmuch_config_values_t *values); + +/** + * Returns an iterator for a (key, value) configuration pairs + * + * @param[in] notmuch database + * @param[in] prefix prefix for keys. Pass "" for all keys. + * + * @since libnotmuch 5.4 (notmuch 0.32) + * + * @retval NULL in case of error. + */ +notmuch_config_pairs_t * +notmuch_config_get_pairs (notmuch_database_t *notmuch, + const char *prefix); + +/** + * Is the given 'config_pairs' iterator pointing at a valid element. + * + * @param[in] pairs iterator + * + * @since libnotmuch 5.4 (notmuch 0.32) + * + * @retval FALSE if passed a NULL pointer, or the iterator is exhausted. + * + */ +notmuch_bool_t +notmuch_config_pairs_valid (notmuch_config_pairs_t *pairs); + +/** + * Move the 'config_pairs' iterator to the next element + * + * @param[in,out] pairs iterator + * + * @since libnotmuch 5.4 (notmuch 0.32) + * + */ +void +notmuch_config_pairs_move_to_next (notmuch_config_pairs_t *pairs); + +/** + * Get the current key from the 'config_pairs' iterator + * + * @param[in] pairs iterator + * + * @since libnotmuch 5.4 (notmuch 0.32) + * + * @retval a string with the same lifetime as the iterator + */ +const char * +notmuch_config_pairs_key (notmuch_config_pairs_t *pairs); + +/** + * Get the current value from the 'config_pairs' iterator + * + * @param[in] pairs iterator + * + * @since libnotmuch 5.4 (notmuch 0.32) + * + * @retval a string with the same lifetime as the iterator + */ +const char * +notmuch_config_pairs_value (notmuch_config_pairs_t *pairs); + +/** + * Destroy a config_pairs iterator, along with any associated + * resources. + * + * @param[in,out] pairs iterator + * + * @since libnotmuch 5.4 (notmuch 0.32) + */ +void +notmuch_config_pairs_destroy (notmuch_config_pairs_t *pairs); + /** * get a configuration value from an open database as Boolean * @@ -2572,6 +2760,15 @@ notmuch_status_t notmuch_config_get_bool (notmuch_database_t *notmuch, notmuch_config_key_t key, notmuch_bool_t *val); + +/** + * return the path of the config file loaded, if any + * + * @retval NULL if no config file was loaded + */ +const char * +notmuch_config_path (notmuch_database_t *notmuch); + /** * get the current default indexing options for a given database. *