add status value to _notmuch_message_ensure_metadata

[David Bremner]

In id:1487339566.mz8acpov1j.astroid at strange.none , Gaute provided a
traceback of an uncaught Xapian::DatabaseModifiedError. The fix for
this is simple, but somewhat intrusive.

This patch series catches any Xapian exceptions in
_notmuch_message_ensure_metadata and converts them into status returns
(this could be refined in the future to different codes if someone(TM)
finds the time).  The rest of the series is either trivial cleanup, or
propagating that status through the API. In particular the following
changes to the API docs are included.

Some of the NULL returns were there already, just not
documented. However message_get_message_id is a genuine change.

The change to message_get_flag is a bit annoying, the new API is
notably less friendly, and the proposed solution for the CLI is the
wrap_message_get_flag function. Neither being inline nor the name is
crucial.  Perhaps we should start a file of convenenience functions
that succeed or exit in the CLI.

I haven't tested against Gaute's test case (needs more boost than I
have handy).

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 16da8be9..ac588922 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -1286,9 +1286,7 @@ notmuch_messages_collect_tags (notmuch_messages_t *messages);
  * message is valid, (which is until the query from which it derived
  * is destroyed).
  *
- * This function will not return NULL since Notmuch ensures that every
- * message has a unique message ID, (Notmuch will generate an ID for a
- * message if the original file does not contain one).
+ * The function returns NULL on error.
  */
 const char *
 notmuch_message_get_message_id (notmuch_message_t *message);
@@ -1302,8 +1300,7 @@ notmuch_message_get_message_id (notmuch_message_t *message);
  * notmuch_message_destroy on 'message' or until a query from which it
  * derived is destroyed).
  *
- * This function will not return NULL since Notmuch ensures that every
- * message belongs to a single thread.
+ * The function returns NULL on error.
  */
 const char *
 notmuch_message_get_thread_id (notmuch_message_t *message);
@@ -1344,6 +1341,8 @@ notmuch_message_get_replies (notmuch_message_t *message);
  * this function will arbitrarily return a single one of those
  * filenames. See notmuch_message_get_filenames for returning the
  * complete list of filenames.
+ *
+ * The function returns NULL on error.
  */
 const char *
 notmuch_message_get_filename (notmuch_message_t *message);
@@ -1357,6 +1356,8 @@ notmuch_message_get_filename (notmuch_message_t *message);
  *
  * Each filename in the iterator is an absolute filename, (the initial
  * component will match notmuch_database_get_path() ).
+ *
+ * The function returns NULL on error.
  */
 notmuch_filenames_t *
 notmuch_message_get_filenames (notmuch_message_t *message);
@@ -1378,10 +1379,16 @@ typedef enum _notmuch_message_flag {
 
 /**
  * Get a value of a flag for the email corresponding to 'message'.
+ * @returns
+ * - NOTMUCH_STATUS_XAPIAN_EXCEPTION: an error occured reading message metadata from disk
+ * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
+ * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * @since libnotmuch 5 (notmuch 0.24)
  */
-notmuch_bool_t
+notmuch_status_t
 notmuch_message_get_flag (notmuch_message_t *message,
-			  notmuch_message_flag_t flag);
+			  notmuch_message_flag_t flag,
+			  notmuch_bool_t *value);
 
 /**
  * Set a value of a flag for the email corresponding to 'message'.
@@ -1449,6 +1456,8 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header);
  * notmuch_tags_t object. (For consistency, we do provide a
  * notmuch_tags_destroy function, but there's no good reason to call
  * it if the message is about to be destroyed).
+ *
+ * The function returns NULL on error.
  */
 notmuch_tags_t *
 notmuch_message_get_tags (notmuch_message_t *message);
@@ -1659,6 +1668,12 @@ void
 notmuch_message_destroy (notmuch_message_t *message);
 
 /**
+ * Return the notmuch database of this message.
+ */
+notmuch_database_t *
+notmuch_message_get_database (notmuch_message_t *message);
+
+/**
  * @name Message Properties
  *
  * This interface provides the ability to attach arbitrary (key,value)
@@ -1750,7 +1765,7 @@ typedef struct _notmuch_string_map_iterator notmuch_message_properties_t;
  *     notmuch_message_properties_t *list;
  *
  *     for (list = notmuch_message_get_properties (message, "testkey1", TRUE);
- *          notmuch_message_properties_valid (list); notmuch_message_properties_move_to_next (list)) {
+ *          list && notmuch_message_properties_valid (list); notmuch_message_properties_move_to_next (list)) {
  *        printf("%s\n", notmuch_message_properties_value(list));
  *     }
  *
@@ -1758,9 +1773,11 @@ typedef struct _notmuch_string_map_iterator notmuch_message_properties_t;
  *
  * Note that there's no explicit destructor needed for the
  * notmuch_message_properties_t object. (For consistency, we do
- * provide a notmuch_message_properities_destroy function, but there's
+ * provide a notmuch_message_properties_destroy function, but there's
  * no good reason to call it if the message is about to be destroyed).
  *
+ * @return The function returns NULL on error
+ *
  * @since libnotmuch 4.4 (notmuch 0.23)
  */
 notmuch_message_properties_t *