X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=6469744df36251294fd62d0ba9e4cd1b07224b51;hp=bab573dd4b22ad8b407a7d7dc16e2ba83e4a01d0;hb=c168e24174d32563ceb1a35d9bf1875c5bfeac25;hpb=146549321044615d9aef2b30cedccda9c49f3f38;ds=sidebyside diff --git a/lib/notmuch.h b/lib/notmuch.h index bab573dd..6469744d 100644 --- 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; -/* 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 @@ -134,11 +121,6 @@ notmuch_database_default_path (void); * 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. @@ -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. */ -/* 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 @@ -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'. * - * 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. * @@ -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. * + * 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; @@ -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 * -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; @@ -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 * -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. * @@ -474,6 +469,37 @@ notmuch_threads_destroy (notmuch_threads_t *threads); 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 @@ -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). * - * 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);