lib: define NOTMUCH_DEPRECATED macro, document its use.

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index f0b60b83a4bd2ec7a54be51426a906fcbc71d168..9b5046b423c43963882d7af3c3cfb043786033e9 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -59,6 +59,8 @@ NOTMUCH_BEGIN_DECLS
 #define LIBNOTMUCH_MINOR_VERSION       2
 #define LIBNOTMUCH_MICRO_VERSION       0
 
+#define NOTMUCH_DEPRECATED(major,minor) \
+    __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor)))
 #endif /* __DOXYGEN__ */
 
 /**
@@ -163,6 +165,11 @@ typedef enum _notmuch_status {
      * The operation requires a database upgrade.
      */
     NOTMUCH_STATUS_UPGRADE_REQUIRED,
+    /**
+     * There is a problem with the proposed path, e.g. a relative path
+     * passed to a function expecting an absolute path.
+     */
+    NOTMUCH_STATUS_PATH_ERROR,
     /**
      * Not an actual status value. Just a way to find out how many
      * valid status values there are.
@@ -229,6 +236,16 @@ typedef struct _notmuch_filenames notmuch_filenames_t;
 notmuch_status_t
 notmuch_database_create (const char *path, notmuch_database_t **database);
 
+/**
+ * Like notmuch_database_create, except optionally return an error
+ * message. This message is allocated by malloc and should be freed by
+ * the caller.
+ */
+notmuch_status_t
+notmuch_database_create_verbose (const char *path,
+                                notmuch_database_t **database,
+                                char **error_message);
+
 /**
  * Database open mode for notmuch_database_open.
  */
@@ -279,6 +296,24 @@ 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.
+ */
+
+notmuch_status_t
+notmuch_database_open_verbose (const char *path,
+                              notmuch_database_mode_t mode,
+                              notmuch_database_t **database,
+                              char **error_message);
+
+/**
+ * Retrieve last status string for given database.
+ *
+ */
+const char *
+notmuch_database_status_string (notmuch_database_t *notmuch);
 
 /**
  * Commit changes and close the given notmuch database.
@@ -909,10 +944,10 @@ void
 notmuch_threads_destroy (notmuch_threads_t *threads);
 
 /**
- * Return an estimate of the number of messages matching a search.
+ * Return the number of messages matching a search.
  *
- * This function performs a search and returns Xapian's best
- * guess as to number of matching messages.
+ * This function performs a search and returns the number of matching
+ * messages.
  *
  * If a Xapian exception occurs, this function may return 0 (after
  * printing a message).