X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=bbb17e4a66d5c3f5e6c7a9ba4c6990be0605883b;hp=e6e5cc2e01ca84f8a739d44fd6bd7f10891c3171;hb=0c950146a14fa2bb0a0bf542073b2cdca141afd1;hpb=ba5729421825e0ec9d38aa9d656553f329aa6f09 diff --git a/lib/notmuch.h b/lib/notmuch.h index e6e5cc2e..bbb17e4a 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -300,11 +300,28 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch); * (see notmuch_database_get_path), or else should be an absolute path * with initial components that match the path of 'database'. * - * Can return NULL if a Xapian exception occurs. + * Note: Currently this will create the directory object if it doesn't + * exist. In the future, when a directory object does not exist this + * will return NOTMUCH_STATUS_SUCCESS and set *directory to NULL. + * Callers should be prepared for this. + * + * Return value: + * + * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory. + * + * NOTMUCH_STATUS_NULL_POINTER: The given 'directory' argument is NULL. + * + * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; + * directory not retrieved. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so the directory cannot be created (this case will be + * removed in the future). */ -notmuch_directory_t * +notmuch_status_t notmuch_database_get_directory (notmuch_database_t *database, - const char *path); + const char *path, + notmuch_directory_t **directory); /* Add a new message to the given notmuch database or associate an * additional filename with an existing message.