Typsos

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index d0b0d9e43f5bc302e25cb67bccb771772b739df6..cc713a3309af6d3a44d0e4bbeca315a8caa84bb0 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -222,7 +222,7 @@ notmuch_database_get_timestamp (notmuch_database_t *database,
 
 /* Add a new message to the given notmuch database.
  *
- * Here,'filename' should be a path relative to the the path of
+ * Here,'filename' should be a path relative to the path of
  * 'database' (see notmuch_database_get_path), or else should be an
  * absolute filename with initial components that match the path of
  * 'database'.
@@ -258,7 +258,7 @@ notmuch_database_add_message (notmuch_database_t *database,
                              const char *filename,
                              notmuch_message_t **message);
 
-/* Find a message with the given messsage_id.
+/* Find a message with the given message_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
@@ -299,8 +299,8 @@ notmuch_query_create (notmuch_database_t *database,
 
 /* Sort values for notmuch_query_set_sort */
 typedef enum {
-    NOTMUCH_SORT_DATE,
-    NOTMUCH_SORT_DATE_REVERSE,
+    NOTMUCH_SORT_OLDEST_FIRST,
+    NOTMUCH_SORT_NEWEST_FIRST,
     NOTMUCH_SORT_MESSAGE_ID
 } notmuch_sort_t;
 
@@ -477,6 +477,21 @@ notmuch_thread_get_thread_id (notmuch_thread_t *thread);
 int
 notmuch_thread_get_total_messages (notmuch_thread_t *thread);
 
+/* Get a notmuch_messages_t iterator for the top-level messages in
+ * 'thread'.
+ *
+ * This iterator will not necessarily iterate over all of the messages
+ * in the thread. It will only iterate over the messages in the thread
+ * which are not replies to other messages in the thread.
+ *
+ * To iterate over all messages in the thread, the caller will need to
+ * iterate over the result of notmuch_message_get_replies for each
+ * top-level message (and do that recursively for the resulting
+ * messages, etc.).
+ */
+notmuch_messages_t *
+notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
+
 /* Get the number of messages in 'thread' that matched the search.
  *
  * This count includes only the messages in this thread that were
@@ -605,7 +620,7 @@ notmuch_messages_advance (notmuch_messages_t *messages);
 /* Destroy a notmuch_messages_t object.
  *
  * It's not strictly necessary to call this function. All memory from
- * the notmuch_messages_t object will be reclaimed when the containg
+ * the notmuch_messages_t object will be reclaimed when the containing
  * query object is destroyed.
  */
 void
@@ -639,6 +654,26 @@ notmuch_message_get_message_id (notmuch_message_t *message);
 const char *
 notmuch_message_get_thread_id (notmuch_message_t *message);
 
+/* Get a notmuch_messages_t iterator for all of the replies to
+ * 'message'.
+ *
+ * Note: This call only makes sense if 'message' was ultimately
+ * obtained from a notmuch_thread_t object, (such as by coming
+ * directly from the result of calling notmuch_thread_get_
+ * toplevel_messages or by any number of subsequent
+ * calls to notmuch_message_get_replies).
+ *
+ * If 'message' was obtained through some non-thread means, (such as
+ * by a call to notmuch_query_search_messages), then this function
+ * will return NULL.
+ *
+ * If there are no replies to 'message', this function will return
+ * NULL. (Note that notmuch_messages_has_more will accept that NULL
+ * value as legitimate, and simply return FALSE for it.)
+ */
+notmuch_messages_t *
+notmuch_message_get_replies (notmuch_message_t *message);
+
 /* Get the filename for the email corresponding to 'message'.
  *
  * The returned filename is an absolute filename, (the initial
@@ -830,7 +865,7 @@ notmuch_tags_has_more (notmuch_tags_t *tags);
 /* 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).
+ * identical to it (and the query to which it ultimately belongs).
  *
  * See the documentation of notmuch_message_get_tags for example code
  * showing how to iterate over a notmuch_tags_t object.
@@ -849,7 +884,7 @@ notmuch_tags_advance (notmuch_tags_t *tags);
 /* Destroy a notmuch_tags_t object.
  *
  * It's not strictly necessary to call this function. All memory from
- * the notmuch_tags_t object will be reclaimed when the containg
+ * the notmuch_tags_t object will be reclaimed when the containing
  * message or query objects are destroyed.
  */
 void