notmuch search: Print the number of matched/total messages for each thread.

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index bab573dd4b22ad8b407a7d7dc16e2ba83e4a01d0..6469744df36251294fd62d0ba9e4cd1b07224b51 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -114,19 +114,6 @@ typedef struct _notmuch_messages notmuch_messages_t;
 typedef struct _notmuch_message notmuch_message_t;
 typedef struct _notmuch_tags notmuch_tags_t;
 
 typedef struct _notmuch_message notmuch_message_t;
 typedef struct _notmuch_tags notmuch_tags_t;
 

-/* Lookup the default database path.
- *
- * This is the path that will be used by notmuch_database_create and
- * notmuch_database_open if given a NULL path. Specifically it will be
- * the value of the NOTMUCH_BASE environment variable if set,
- * otherwise ${HOME}/mail
- *
- * Returns a newly allocated string which the caller should free()
- * when finished with it.
- */
-char *
-notmuch_database_default_path (void);
-

 /* Create a new, empty notmuch database located at 'path'.
  *
  * The path should be a top-level directory to a collection of
 /* Create a new, empty notmuch database located at 'path'.
  *
  * The path should be a top-level directory to a collection of


@@ -134,11 +121,6 @@ notmuch_database_default_path (void);
  * create a new ".notmuch" directory within 'path' where notmuch will
  * store its data.
  *
  * create a new ".notmuch" directory within 'path' where notmuch will
  * store its data.
  *

- * Passing a value of NULL for 'path' will cause notmuch to open the
- * default database. The default database path can be specified by the
- * NOTMUCH_BASE environment variable, and is equivalent to
- * ${HOME}/mail if NOTMUCH_BASE is not set.
- *

  * After a successful call to notmuch_database_create, the returned
  * database will be open so the caller should call
  * notmuch_database_close when finished with it.
  * After a successful call to notmuch_database_create, the returned
  * database will be open so the caller should call
  * notmuch_database_close when finished with it.


@@ -157,7 +139,7 @@ notmuch_database_create (const char *path);
 /* XXX: I think I'd like this to take an extra argument of
  * notmuch_status_t* for returning a status value on failure. */
 
 /* XXX: I think I'd like this to take an extra argument of
  * notmuch_status_t* for returning a status value on failure. */
 

-/* Open a an existing notmuch database located at 'path'.
+/* Open an existing notmuch database located at 'path'.

  *
  * The database should have been created at some time in the past,
  * (not necessarily by this process), by calling
  *
  * The database should have been created at some time in the past,
  * (not necessarily by this process), by calling


@@ -166,11 +148,6 @@ notmuch_database_create (const char *path);
  * An existing notmuch database can be identified by the presence of a
  * directory named ".notmuch" below 'path'.
  *
  * An existing notmuch database can be identified by the presence of a
  * directory named ".notmuch" below 'path'.
  *

- * Passing a value of NULL for 'path' will cause notmuch to open the
- * default database. The default database path can be specified by the
- * NOTMUCH_BASE environment variable, and is equivalent to
- * ${HOME}/mail if NOTMUCH_BASE is not set.
- *

  * The caller should call notmuch_database_close when finished with
  * this database.
  *
  * The caller should call notmuch_database_close when finished with
  * this database.
  *


@@ -336,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.
  *
  * 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;
  * Typical usage might be:
  *
  *     notmuch_query_t *query;


@@ -368,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 *
  * 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.
  *
 
 /* 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;
  * Typical usage might be:
  *
  *     notmuch_query_t *query;


@@ -407,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 *
  * 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.
  *
 
 /* Destroy a notmuch_query_t along with any associated resources.
  *


@@ -474,6 +469,37 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
 const char *
 notmuch_thread_get_thread_id (notmuch_thread_t *thread);
 
 const char *
 notmuch_thread_get_thread_id (notmuch_thread_t *thread);
 

+/* Get the total number of messages in 'thread'.
+ *
+ * This count consists of all messages in the database belonging to
+ * this thread. Contrast with notmuch_thread_get_matched_messages() .
+ */
+int
+notmuch_thread_get_total_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
+ * matched by the search from which the thread was created. Contrast
+ * with notmuch_thread_get_total_messages() .
+ */
+int
+notmuch_thread_get_matched_messages (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
 /* Get the subject of 'thread'
  *
  * The subject is taken from the first message (according to the query


@@ -641,8 +667,8 @@ notmuch_message_get_date  (notmuch_message_t *message);
  * modified or freed by the caller (nor should it be referenced after
  * the message is destroyed).
  *
  * modified or freed by the caller (nor should it be referenced after
  * the message is destroyed).
  *

- * Returns NULL if the message does not contain a header line matching
- * 'header' of if any error occurs.
+ * Returns an empty string ("") if the message does not contain a
+ * header line matching 'header'. Returns NULL if any error occurs.

  */
 const char *
 notmuch_message_get_header (notmuch_message_t *message, const char *header);
  */
 const char *
 notmuch_message_get_header (notmuch_message_t *message, const char *header);