- * If there is already a document with message ID 'message_id' in the
- * database, then the returned message can be used to query/modify the
- * document. Otherwise, a new document will be inserted into the
- * database before this function returns, (and *status will be set
- * to NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND).
+ * If no document exists in the database with document ID of 'doc_id'
+ * then this function returns NULL and optionally sets *status to
+ * NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND.
+ *
+ * This function can also fail to due lack of available memory,
+ * returning NULL and optionally setting *status to
+ * NOTMUCH_PRIVATE_STATUS_OUT_OF_MEMORY.
+ *
+ * The caller can pass NULL for status if uninterested in
+ * distinguishing these two cases.
+ */
+notmuch_message_t *
+_notmuch_message_create (const void *talloc_owner,
+ notmuch_database_t *notmuch,
+ unsigned int doc_id,
+ notmuch_private_status_t *status)
+{
+ Xapian::Document doc;
+
+ try {
+ doc = notmuch->xapian_db->get_document (doc_id);
+ } catch (const Xapian::DocNotFoundError &error) {
+ if (status)
+ *status = NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND;
+ return NULL;
+ }
+
+ return _notmuch_message_create_for_document (talloc_owner, notmuch,
+ doc_id, doc, status);
+}
+
+/* Create a new notmuch_message_t object for a specific message ID,
+ * (which may or may not already exist in the database).
+ *
+ * The 'notmuch' database will be the talloc owner of the returned
+ * message.
+ *
+ * This function returns a valid notmuch_message_t whether or not
+ * there is already a document in the database with the given message
+ * ID. These two cases can be distinguished by the value of *status:
+ *
+ *
+ * NOTMUCH_PRIVATE_STATUS_SUCCESS:
+ *
+ * There is already a document with message ID 'message_id' in the
+ * database. The returned message can be used to query/modify the
+ * document.
+ * NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND:
+ *
+ * No document with 'message_id' exists in the database. The
+ * returned message contains a newly created document (not yet
+ * added to the database) and a document ID that is known not to
+ * exist in the database. The caller can modify the message, and a
+ * call to _notmuch_message_sync will add * the document to the
+ * database.