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
