X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=notmuch.h;h=5dfc8ce2a71d431a920bd3fb7503ce1fe1b7d9f2;hb=a6b3f341dcfbf1160a02d02879a36777bcf459f1;hp=41987b588c1acfbb646edee2988f84e004a4fcd7;hpb=8ad4350fef132b016bbab5eeb1c4a713e51035c6;p=notmuch

diff --git a/notmuch.h b/notmuch.h
index 41987b58..5dfc8ce2 100644
--- a/notmuch.h
+++ b/notmuch.h
@@ -164,6 +164,19 @@ notmuch_status_t
 notmuch_database_add_message (notmuch_database_t *database,
 			      const char *filename);
 
+/* Find a message with the given messsage_id.
+ *
+ * If the database contains a message with the given message_id, then
+ * 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, this function
+ * returns NULL.
+ */
+notmuch_message_t *
+notmuch_database_find_message (notmuch_database_t *database,
+			       const char *message_id);
+
 /* Create a new query for 'database'.
  *
  * Here, 'database' should be an open database, (see
@@ -218,17 +231,22 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  *     {
  *         message = notmuch_results_get (results);
  *         ....
+ *         notmuch_message_destroy (message);
  *     }
  *
  *     notmuch_query_destroy (query);
  *
- * Note that there's no explicit destructor needed for the
- * notmuch_results_t object.
+ * Note: If you are finished with a message before its containing
+ * query, you can call notmuch_message_destroy to clean up some memory
+ * sooner (as in the above example). Otherwise, if your message
+ * objects are long-lived, then you don't need to call
+ * notmuch_message_destroy and all the memory will still be reclaimed
+ * when the query is destroyed.
  *
- * (For consistency, we do provide a notmuch_results_destroy function,
- * but there's no point in calling it if you're about to destroy the
- * query object as well too---either call will free all the memory of
- * the results).
+ * Note that there's no explicit destructor needed for the
+ * notmuch_results_t object. (For consistency, we do provide a
+ * notmuch_results_destroy function, but there's no good reason to
+ * call it if the query is about to be destroyed).
  */
 notmuch_results_t *
 notmuch_query_search (notmuch_query_t *query);
@@ -369,7 +387,7 @@ notmuch_message_get_thread_ids (notmuch_message_t *message);
 void
 notmuch_message_destroy (notmuch_message_t *message);
 
-/* Does the given notmuch_tags_t object contain any more results.
+/* Does the given notmuch_tags_t object contain any more tags.
  *
  * When this function returns TRUE, notmuch_tags_get will return a
  * valid string. Whereas when this function returns FALSE,
@@ -381,7 +399,7 @@ notmuch_message_destroy (notmuch_message_t *message);
 notmuch_bool_t
 notmuch_tags_has_more (notmuch_tags_t *tags);
 
-/* Get the current result from 'tags' as a string.
+/* Get the current tag from 'tags' as a string.
  *
  * Note: The returned string belongs to 'tags' and has a lifetime
  * identical to it (and the query to which it utlimately belongs).
@@ -398,7 +416,7 @@ notmuch_tags_get (notmuch_tags_t *tags);
  * showing how to iterate over a notmuch_tags_t object.
  */
 void
-notmuch_tags_advance (notmuch_tags_t *results);
+notmuch_tags_advance (notmuch_tags_t *tags);
 
 /* Destroy a notmuch_tags_t object.
  *