Initially document the intended API and copy the code from notmuch_database_open_verbose. Most of the documented functionality is not there yet. --- lib/database.cc | 21 ++++++-- lib/notmuch.h | 138 ++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 127 insertions(+), 32 deletions(-)
diff --git a/lib/database.cc b/lib/database.cc index 75189685..acc686c0 100644 --- a/lib/database.cc +++ b/lib/database.cc @@ -918,6 +918,18 @@ notmuch_database_open_verbose (const char *path, notmuch_database_mode_t mode, notmuch_database_t **database, char **status_string) +{ + return notmuch_database_open_with_config (path, mode, "", NULL, + database, status_string); +} + +notmuch_status_t +notmuch_database_open_with_config (const char *database_path, + notmuch_database_mode_t mode, + const char *config_path, + const char *profile, + notmuch_database_t **database, + char **status_string) { notmuch_status_t status = NOTMUCH_STATUS_SUCCESS; void *local = talloc_new (NULL); @@ -929,19 +941,19 @@ notmuch_database_open_verbose (const char *path, unsigned int i, version; static int initialized = 0; - if (path == NULL) { + if (database_path == NULL) { message = strdup ("Error: Cannot open a database for a NULL path.\n"); status = NOTMUCH_STATUS_NULL_POINTER; goto DONE; } - if (path[0] != '/') { + if (database_path[0] != '/') { message = strdup ("Error: Database path must be absolute.\n"); status = NOTMUCH_STATUS_PATH_ERROR; goto DONE; } - if (! (notmuch_path = talloc_asprintf (local, "%s/%s", path, ".notmuch"))) { + if (! (notmuch_path = talloc_asprintf (local, "%s/%s", database_path, ".notmuch"))) { message = strdup ("Out of memory\n"); status = NOTMUCH_STATUS_OUT_OF_MEMORY; goto DONE; @@ -975,7 +987,7 @@ notmuch_database_open_verbose (const char *path, notmuch = talloc_zero (NULL, notmuch_database_t); notmuch->exception_reported = false; notmuch->status_string = NULL; - notmuch->path = talloc_strdup (notmuch, path); + notmuch->path = talloc_strdup (notmuch, database_path); strip_trailing (notmuch->path, '/'); @@ -1101,7 +1113,6 @@ notmuch_database_open_verbose (const char *path, return status; } - notmuch_status_t notmuch_database_close (notmuch_database_t *notmuch) { diff --git a/lib/notmuch.h b/lib/notmuch.h index f3cb0fe2..e61634a1 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -301,52 +301,136 @@ typedef enum { } notmuch_database_mode_t; /** - * Open an existing notmuch database located at 'path'. + * Deprecated alias for notmuch_database_open_with_config with + * config_path=error_message=NULL + * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) + */ +/* 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 + * + * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) + * + */ +/* NOTMUCH_DEPRECATED(5, 4) */ +notmuch_status_t +notmuch_database_open_verbose (const char *path, + notmuch_database_mode_t mode, + notmuch_database_t **database, + char **error_message); + +/** + * Open an existing notmuch database located at 'database_path', using + * configuration in 'config_path'. + * + * @param[in] database_path + * @parblock + * Path to existing database. + * + * A notmuch database is a Xapian database containing appropriate + * metadata. * * The database should have been created at some time in the past, * (not necessarily by this process), by calling - * notmuch_database_create with 'path'. By default the database should be - * opened for reading only. In order to write to the database you need to - * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode. + * notmuch_database_create. + * + * If 'database_path' is NULL, use the location specified + * + * - in the environment variable NOTMUCH_DATABASE, if non-empty + * + * - by $XDG_DATA_HOME/notmuch/$PROFILE where XDG_DATA_HOME defaults + * to "$HOME/.local/share" and PROFILE as as discussed in + * 'profile' + * + * If 'database_path' is non-NULL, but does not appear to be a Xapian + * database, check for a directory '.notmuch/xapian' below + * 'database_path' (this is the behavior of + * notmuch_database_open_verbose pre-0.32). + * + * @endparblock + * @param[in] mode + * @parblock + * Mode to open database. Use one of #NOTMUCH_DATABASE_MODE_READ_WRITE + * or #NOTMUCH_DATABASE_MODE_READ_WRITE + * + * @endparblock + * @param[in] config_path + * @parblock + * Path to config file. + * + * Config file is key-value, with mandatory sections. See + * <em>notmuch-config(5)</em> for more information. The key-value pair + * overrides the corresponding configuration data stored in the + * database (see <em>notmuch_database_get_config</em>) + * + * If <em>config_path</em> is NULL use the path specified * - * An existing notmuch database can be identified by the presence of a - * directory named ".notmuch" below 'path'. + * - in environment variable <em>NOTMUCH_CONFIG</em>, if non-empty + * + * - by <em>XDG_CONFIG_HOME</em>/notmuch/ where + * XDG_CONFIG_HOME defaults to "$HOME/.config". + * + * - by $HOME/.notmuch-config + * + * If <em>config_path</em> is "" (empty string) then do not + * open any configuration file. + * @endparblock + * @param[in] profile: + * @parblock + * Name of profile (configuration/database variant). + * + * If non-NULL, append to the directory / file path determined for + * <em>config_path</em> and <em>database_path</em>. + * + * If NULL then use + * - environment variable NOTMUCH_PROFILE if defined, + * - otherwise "default" for directories and "" (empty string) for paths. + * + * @endparblock + * @param[out] database + * @parblock + * Pointer to database object. May not be NULL. * * The caller should call notmuch_database_destroy when finished with * this database. * * In case of any failure, this function returns an error status and - * sets *database to NULL (after printing an error message on stderr). + * sets *database to NULL. * - * Return value: + * @endparblock + * @param[out] error_message + * If non-NULL, store error message from opening the database. + * Any such message is allocated by \a malloc(3) and should be freed + * by the caller. * - * NOTMUCH_STATUS_SUCCESS: Successfully opened the database. + * @retval NOTMUCH_STATUS_SUCCESS: Successfully opened the database. * - * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL. + * @retval NOTMUCH_STATUS_NULL_POINTER: The given \a database + * argument is NULL. * - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. * - * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the - * database file (such as permission denied, or file not found, + * @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.), or the database version is unknown. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. - */ -notmuch_status_t -notmuch_database_open (const char *path, - notmuch_database_mode_t mode, - notmuch_database_t **database); -/** - * Like notmuch_database_open, except optionally return an error - * message. This message is allocated by malloc and should be freed by - * the caller. + * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * + * @since libnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t -notmuch_database_open_verbose (const char *path, - notmuch_database_mode_t mode, - notmuch_database_t **database, - char **error_message); +notmuch_database_open_with_config (const char *database_path, + notmuch_database_mode_t mode, + const char *config_path, + const char *profile, + notmuch_database_t **database, + char **error_message); /** * Retrieve last status string for given database. -- 2.28.0 _______________________________________________ notmuch mailing list -- notmuch@notmuchmail.org To unsubscribe send an email to notmuch-le...@notmuchmail.org