X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.h;h=41987b588c1acfbb646edee2988f84e004a4fcd7;hp=6d81fb6ca08a0a0601a767d5238c39badbb9994d;hb=8ad4350fef132b016bbab5eeb1c4a713e51035c6;hpb=466a7bbf620e4bf1b57097a6d3c474159c475b6d diff --git a/notmuch.h b/notmuch.h index 6d81fb6c..41987b58 100644 --- a/notmuch.h +++ b/notmuch.h @@ -67,6 +67,7 @@ typedef struct _notmuch_query notmuch_query_t; typedef struct _notmuch_results notmuch_results_t; typedef struct _notmuch_message notmuch_message_t; typedef struct _notmuch_tags notmuch_tags_t; +typedef struct _notmuch_thread_ids notmuch_thread_ids_t; /* Create a new, empty notmuch database located at 'path'. * @@ -174,9 +175,8 @@ notmuch_database_add_message (notmuch_database_t *database, * * http://xapian.org/docs/queryparser.html * - * As a special case, passing a value of NOTMUCH_QUERY_ALL for the - * query string will result in a query that returns all messages in - * the database. + * As a special case, passing a length-zero string, (that is ""), will + * result in a query that returns all messages in the database. * * See notmuch_query_set_sort for controlling the order of results and * notmuch_query_search to actually execute the query. @@ -190,10 +190,6 @@ notmuch_query_t * notmuch_query_create (notmuch_database_t *database, const char *query_string); -/* Special value to cause notmuch_query_create to return all - * messages. */ -extern const char *NOTMUCH_QUERY_ALL; - /* Sort values for notmuch_query_set_sort */ typedef enum { NOTMUCH_SORT_DATE_OLDEST_FIRST, @@ -226,8 +222,13 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort); * * notmuch_query_destroy (query); * - * Note that there's no explicit destructor for the notmuch_results_t - * object. + * 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 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). */ notmuch_results_t * notmuch_query_search (notmuch_query_t *query); @@ -272,6 +273,15 @@ notmuch_results_get (notmuch_results_t *results); void notmuch_results_advance (notmuch_results_t *results); +/* Destroy a notmuch_results_t object. + * + * It's not strictly necessary to call this function. All memory from + * the notmuch_results_t object will be reclaimed when the containg + * query object is destroyed. + */ +void +notmuch_results_destroy (notmuch_results_t *results); + /* Get the message ID of 'message'. * * The returned string belongs to 'message' and as such, should not be @@ -295,22 +305,70 @@ notmuch_message_get_message_id (notmuch_message_t *message); * notmuch_tags_t *tags; * const char *tag; * - * message = notmuch_results_get (results); + * message = notmuch_database_find_message (database, message_id); * * for (tags = notmuch_message_get_tags (message); * notmuch_tags_has_more (tags); * notmuch_result_advance (tags)) * { - * tag = notmuch_tags_get_string (tags); + * tag = notmuch_tags_get (tags); * .... * } * - * Note that there's no explicit destructor for the notmuch_tags_t - * object. + * notmuch_message_destroy (message); + * + * Note that there's no explicit destructor needed for the + * notmuch_tags_t object. (For consistency, we do provide a + * notmuch_tags_destroy function, but there's no good reason to call + * it if the message is about to be destroyed). */ notmuch_tags_t * notmuch_message_get_tags (notmuch_message_t *message); +/* Get the thread IDs for 'message', returning a notmuch_thread_ids_t + * object which can be used to iterate over all thread IDs. + * + * The thread_ids object is owned by the message and as such, will + * only be valid for as long as the message is valid, (which is until + * the query from which it derived is destroyed). + * + * Typical usage might be: + * + * notmuch_message_t *message; + * notmuch_thread_ids_t *thread_ids; + * const char *thread_id; + * + * message = notmuch_database_find_message (database, message_id); + * + * for (thread_ids = notmuch_message_get_thread_ids (message); + * notmuch_thread_ids_has_more (thread_ids); + * notmuch_thread_ids_advance (thread_ids)) + * { + * thread_id = notmuch_thread_ids_get (thread_ids); + * .... + * } + * + * notmuch_message_destroy (message); + * + * Note that there's no explicit destructor needed for the + * notmuch_thread_ids_t object. (For consistency, we do provide a + * notmuch_thread_ids_destroy function, but there's no good reason to + * call it if the message is about to be destroyed). + */ +notmuch_thread_ids_t * +notmuch_message_get_thread_ids (notmuch_message_t *message); + +/* Destroy a notmuch_message_t object. + * + * It can be useful to call this function in the case of a single + * query object with many messages in the result, (such as iterating + * over the entire database). Otherwise, it's fine to never call this + * function and there will still be no memory leaks. (The memory from + * the messages get reclaimed when the containing query is destroyed.) + */ +void +notmuch_message_destroy (notmuch_message_t *message); + /* Does the given notmuch_tags_t object contain any more results. * * When this function returns TRUE, notmuch_tags_get will return a @@ -342,6 +400,55 @@ notmuch_tags_get (notmuch_tags_t *tags); void notmuch_tags_advance (notmuch_tags_t *results); +/* 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 + * message or query objects are destroyed. + */ +void +notmuch_tags_destroy (notmuch_tags_t *tags); + +/* Does the given notmuch_thread_ids_t object contain any more thread IDs. + * + * When this function returns TRUE, notmuch_thread_ids_get will return a + * valid string. Whereas when this function returns FALSE, + * notmuch_thread_ids_get will return NULL. + * + * See the documentation of notmuch_message_get_thread_ids for example code + * showing how to iterate over a notmuch_thread_ids_t object. + */ +notmuch_bool_t +notmuch_thread_ids_has_more (notmuch_thread_ids_t *thread_ids); + +/* Get the current thread ID from 'thread_ids' as a string. + * + * Note: The returned string belongs to 'thread_ids' and has a lifetime + * identical to it (and the query to which it utlimately belongs). + * + * See the documentation of notmuch_message_get_thread_ids for example code + * showing how to iterate over a notmuch_thread_ids_t object. + */ +const char * +notmuch_thread_ids_get (notmuch_thread_ids_t *thread_ids); + +/* Advance the 'thread_ids' iterator to the next tag. + * + * See the documentation of notmuch_message_get_thread_ids for example code + * showing how to iterate over a notmuch_thread_ids_t object. + */ +void +notmuch_thread_ids_advance (notmuch_thread_ids_t *thread_ids); + +/* Destroy a notmuch_thread_ids_t object. + * + * It's not strictly necessary to call this function. All memory from + * the notmuch_thread_ids_t object will be reclaimed when the containg + * message or query objects are destroyed. + */ +void +notmuch_thread_ids_destroy (notmuch_thread_ids_t *thread_ids); + NOTMUCH_END_DECLS #endif