lib: Fix notmuch_query_search_threads to return NULL on any Xapian exception.

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 88da07898eb20958154d80e5cfb72e054b6a2981..9a19699956dc0a9178d6f0fc39110e0ee7acf92d 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -156,7 +156,7 @@ typedef enum {
  * (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_WRITABLE mode.
+ * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.
  *
  * An existing notmuch database can be identified by the presence of a
  * directory named ".notmuch" below 'path'.
@@ -219,6 +219,8 @@ notmuch_database_upgrade (notmuch_database_t *database,
  * Here, 'path' should be a path relative to the path of 'database'
  * (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.
  */
 notmuch_directory_t *
 notmuch_database_get_directory (notmuch_database_t *database,
@@ -246,6 +248,9 @@ notmuch_database_get_directory (notmuch_database_t *database,
  *
  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
  *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ *     message not added.
+ *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
  *     ID as another message already in the database. The new
  *     filename was successfully added to the message in the database
@@ -280,6 +285,9 @@ notmuch_database_add_message (notmuch_database_t *database,
  * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
  *     message was removed from the database.
  *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ *     message not removed.
+ *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
  *     the message persists in the database with at least one other
  *     filename.
@@ -297,8 +305,11 @@ notmuch_database_remove_message (notmuch_database_t *database,
  * a new notmuch_message_t object is returned. The caller should call
  * notmuch_message_destroy when done with the message.
  *
- * If no message is found with the given message_id or if an
- * out-of-memory situation occurs, this function returns NULL.
+ * This function returns NULL in the following situations:
+ *
+ *     * No message is found with the given message_id
+ *     * An out-of-memory situation occurs
+ *     * A Xapian exception occurs
  */
 notmuch_message_t *
 notmuch_database_find_message (notmuch_database_t *database,
@@ -325,7 +336,8 @@ notmuch_database_get_all_tags (notmuch_database_t *db);
  *
  * http://xapian.org/docs/queryparser.html
  *
- * As a special case, passing a length-zero string, (that is ""), will
+ * As a special case, passing either a length-zero string, (that is ""),
+ * or a string consisting of a single asterisk (that is "*"), will
  * result in a query that returns all messages in the database.
  *
  * See notmuch_query_set_sort for controlling the order of results.
@@ -345,7 +357,8 @@ notmuch_query_create (notmuch_database_t *database,
 typedef enum {
     NOTMUCH_SORT_OLDEST_FIRST,
     NOTMUCH_SORT_NEWEST_FIRST,
-    NOTMUCH_SORT_MESSAGE_ID
+    NOTMUCH_SORT_MESSAGE_ID,
+    NOTMUCH_SORT_UNSORTED
 } notmuch_sort_t;
 
 /* Specify the sorting desired for this query. */
@@ -387,6 +400,8 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  * notmuch_threads_t object. (For consistency, we do provide a
  * notmuch_threads_destroy function, but there's no good reason
  * to call it if the query is about to be destroyed).
+ *
+ * If a Xapian exception occurs this function will return NULL.
  */
 notmuch_threads_t *
 notmuch_query_search_threads (notmuch_query_t *query);
@@ -426,6 +441,8 @@ notmuch_query_search_threads (notmuch_query_t *query);
  * notmuch_messages_t object. (For consistency, we do provide a
  * notmuch_messages_destroy function, but there's no good
  * reason to call it if the query is about to be destroyed).
+ *
+ * If a Xapian exception occurs this function will return NULL.
  */
 notmuch_messages_t *
 notmuch_query_search_messages (notmuch_query_t *query);
@@ -493,6 +510,9 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
  *
  * This function performs a search and returns Xapian's best
  * guess as to number of matching messages.
+ *
+ * If a Xapian exception occurs, this function may return 0 (after
+ * printing a message).
  */
 unsigned
 notmuch_query_count_messages (notmuch_query_t *query);