X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=cd5c1246b977151f56248dca06d2d16943d3d7cd;hp=5a5d99c0f750e2e7db2d824eea1c07263dc576e8;hb=HEAD;hpb=4c79a2dabe38ac72eb9eb21620f2ffca5f1885c6 diff --git a/lib/notmuch.h b/lib/notmuch.h index 5a5d99c0..4e2b0fa4 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. */ @@ -212,10 +212,26 @@ 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, + /** + * No mail root could be deduced from parameters and environment + */ + NOTMUCH_STATUS_NO_MAIL_ROOT, + /** + * Database is not fully opened, or has been closed + */ + NOTMUCH_STATUS_CLOSED_DATABASE, /** * Not an actual status value. Just a way to find out how many * valid status values there are. @@ -245,6 +261,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__ */ @@ -276,6 +293,8 @@ typedef struct _notmuch_indexopts notmuch_indexopts_t; * * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. * + * NOTMUCH_STATUS_PATH_ERROR: filename is too long + * * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the * database file (such as permission denied, or file not found, * etc.), or the database already exists. @@ -311,22 +330,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, @@ -424,6 +443,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 @@ -442,12 +463,50 @@ notmuch_database_open_with_config (const char *database_path, const char *profile, 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 + * + * 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. + * + * @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 * + * 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 @@ -492,11 +551,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: * @@ -633,7 +692,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: * @@ -660,7 +722,8 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch); * * The UUID is a NUL-terminated opaque string that uniquely identifies * this database. Two revision numbers are only comparable if they - * have the same database UUID. + * have the same database UUID. The string 'uuid' is owned by notmuch + * and should not be freed or modified by the user. */ unsigned long notmuch_database_get_revision (notmuch_database_t *notmuch, @@ -879,6 +942,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'. * @@ -908,6 +984,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. */ @@ -1087,7 +1173,10 @@ notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out * * query = notmuch_query_create (database, query_string); * - * for (messages = notmuch_query_search_messages (query); + * if (notmuch_query_search_messages (query, &messages) != NOTMUCH_STATUS_SUCCESS) + * return EXIT_FAILURE; + * + * for (; * notmuch_messages_valid (messages); * notmuch_messages_move_to_next (messages)) * { @@ -1611,7 +1700,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, @@ -1631,7 +1720,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); @@ -1826,7 +1915,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); @@ -2183,6 +2272,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. */ @@ -2403,7 +2495,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). @@ -2453,14 +2546,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 { +typedef enum { 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, @@ -2468,6 +2562,9 @@ 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_INDEX_AS_TEXT, NOTMUCH_CONFIG_LAST } notmuch_config_key_t; @@ -2522,6 +2619,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. * @@ -2581,6 +2694,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 * @@ -2600,6 +2787,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. *