+/* Create a new notmuch_message_t object for a specific message ID,
+ * (which may or may not already exist in the databas).
+ *
+ * Here, 'talloc owner' is an optional talloc context to which the new
+ * message will belong. This allows for the caller to not bother
+ * calling notmuch_message_destroy on the message, and no that all
+ * memory will be reclaimed with 'talloc_owner' is free. The caller
+ * still can call notmuch_message_destroy when finished with the
+ * message if desired.
+ *
+ * The 'talloc_owner' argument can also be NULL, in which case the
+ * caller *is* responsible for calling notmuch_message_destroy.
+ *
+ * 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 an error occurs, this function will return NULL and *status
+ * will be set as appropriate. (The status pointer argument must
+ * not be NULL.)
+ */
+notmuch_message_t *
+_notmuch_message_create_for_message_id (const void *talloc_owner,
+ notmuch_database_t *notmuch,
+ const char *message_id,
+ notmuch_private_status_t *status_ret)
+{
+ notmuch_message_t *message;
+ Xapian::Document doc;
+ unsigned int doc_id;
+ char *term;
+
+ *status_ret = NOTMUCH_PRIVATE_STATUS_SUCCESS;
+
+ message = notmuch_database_find_message (notmuch, message_id);
+ if (message)
+ return talloc_steal (talloc_owner, message);
+
+ term = talloc_asprintf (NULL, "%s%s",
+ _find_prefix ("id"), message_id);
+ if (term == NULL) {
+ *status_ret = NOTMUCH_PRIVATE_STATUS_OUT_OF_MEMORY;
+ return NULL;
+ }
+
+ try {
+ doc.add_term (term);
+ talloc_free (term);
+
+ doc.add_value (NOTMUCH_VALUE_MESSAGE_ID, message_id);
+
+ doc_id = notmuch->xapian_db->add_document (doc);
+ } catch (const Xapian::Error &error) {
+ *status_ret = NOTMUCH_PRIVATE_STATUS_XAPIAN_EXCEPTION;
+ return NULL;
+ }
+
+ message = _notmuch_message_create (talloc_owner, notmuch,
+ doc_id, status_ret);
+
+ /* We want to inform the caller that we had to create a new
+ * document. */
+ if (*status_ret == NOTMUCH_PRIVATE_STATUS_SUCCESS)
+ *status_ret = NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND;
+
+ return message;
+}
+