X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=lib%2Fnotmuch.h;h=c67376ebd2b0fdeef2016c53b7537f9c253ca282;hb=bbf4b8e4aec69b5684587b77bd0af743afd61eb1;hp=40a1dca7e1cab7467c90372f330848733fba1056;hpb=091d18c54c046a08bda9d88982601589a1deea37;p=notmuch

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 40a1dca7..c67376eb 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -313,6 +313,14 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  * object is owned by the query and as such, will only be valid until
  * notmuch_query_destroy.
  *
+ * The 'first' and 'max_threads' arguments can be used to obtain
+ * partial results from the search. For example, to get results 10 at
+ * a time, pass 'max_threads' as 10 and for 'first' pass the values 0,
+ * 10, 20, etc. As a special case, a value of -1 for 'max_threads'
+ * indicates that no limiting is to be performed. So a search with
+ * 'first' == 0 and 'max_threads' == -1 will return the complete
+ * results of the search.
+ *
  * Typical usage might be:
  *
  *     notmuch_query_t *query;
@@ -345,13 +353,22 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  * to call it if the query is about to be destroyed).
  */
 notmuch_threads_t *
-notmuch_query_search_threads (notmuch_query_t *query);
+notmuch_query_search_threads (notmuch_query_t *query,
+			      int first, int max_threads);
 
 /* Execute a query for messages, returning a notmuch_messages_t object
  * which can be used to iterate over the results. The returned
  * messages object is owned by the query and as such, will only be
  * valid until notmuch_query_destroy.
  *
+ * The 'first' and 'max_messages' arguments can be used to obtain
+ * partial results from the search. For example, to get results 10 at
+ * a time, pass 'max_messages' as 10 and for 'first' pass the values
+ * 0, 10, 20, etc. As a special case, a value of -1 for 'max_messages'
+ * indicates that no limiting is to be performed. So a search with
+ * 'first' == 0 and 'max_messages' == -1 will return the complete
+ * results of the search.
+ *
  * Typical usage might be:
  *
  *     notmuch_query_t *query;
@@ -384,7 +401,8 @@ notmuch_query_search_threads (notmuch_query_t *query);
  * reason to call it if the query is about to be destroyed).
  */
 notmuch_messages_t *
-notmuch_query_search_messages (notmuch_query_t *query);
+notmuch_query_search_messages (notmuch_query_t *query,
+			       int first, int max_messages);
 
 /* Destroy a notmuch_query_t along with any associated resources.
  *
@@ -451,6 +469,20 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
 const char *
 notmuch_thread_get_thread_id (notmuch_thread_t *thread);
 
+/* Get the authors of 'thread'
+ *
+ * The returned string is a comma-separated list of the names of the
+ * authors of mail messages in the query results that belong to this
+ * thread.
+ *
+ * The returned string belongs to 'thread' and as such, should not be
+ * modified by the caller and will only be valid for as long as the
+ * thread is valid, (which is until notmuch_thread_destroy or until
+ * the query from which it derived is destroyed).
+ */
+const char *
+notmuch_thread_get_authors (notmuch_thread_t *thread);
+
 /* Get the subject of 'thread'
  *
  * The subject is taken from the first message (according to the query