X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.h;h=6d81fb6ca08a0a0601a767d5238c39badbb9994d;hp=b63a7d77b7616ae1f8bf12d3a68b7022d49fa28a;hb=466a7bbf620e4bf1b57097a6d3c474159c475b6d;hpb=cd4a8734d3bb151df70d51a84903bff994439b05 diff --git a/notmuch.h b/notmuch.h index b63a7d77..6d81fb6c 100644 --- a/notmuch.h +++ b/notmuch.h @@ -31,6 +31,16 @@ NOTMUCH_BEGIN_DECLS +#ifndef FALSE +#define FALSE 0 +#endif + +#ifndef TRUE +#define TRUE 1 +#endif + +typedef int notmuch_bool_t; + /* Status codes used for the return values of most functions. * * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function @@ -50,10 +60,13 @@ typedef enum _notmuch_status { NOTMUCH_STATUS_FILE_NOT_EMAIL } notmuch_status_t; -/* An opaque data structure representing a notmuch database. See - * notmuch_database_open and other notmuch_database functions - * below. */ +/* Various opaque data types. For each notmuch__t see the various + * notmuch_ functions below. */ typedef struct _notmuch_database notmuch_database_t; +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; /* Create a new, empty notmuch database located at 'path'. * @@ -150,6 +163,185 @@ notmuch_status_t notmuch_database_add_message (notmuch_database_t *database, const char *filename); +/* Create a new query for 'database'. + * + * Here, 'database' should be an open database, (see + * notmuch_database_open and notmuch_database_create). + * + * For the query string, we'll document the syntax here more + * completely in the future, but it's likely to be a specialized + * version of the general Xapian query syntax: + * + * 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. + * + * See notmuch_query_set_sort for controlling the order of results and + * notmuch_query_search to actually execute the query. + * + * User should call notmuch_query_destroy when finished with this + * query. + * + * Will return NULL if insufficient memory is available. + */ +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, + NOTMUCH_SORT_DATE_NEWEST_FIRST, + NOTMUCH_SORT_MESSAGE_ID +} notmuch_sort_t; + +/* Specify the sorting desired for this query. */ +void +notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort); + +/* Execute a query, returning a notmuch_results_t object which can be + * used to iterate over the results. The results object is owned by + * the query and as such, will only be valid until notmuch_query_destroy. + * + * Typical usage might be: + * + * notmuch_query_t *query; + * notmuch_results_t *results; + * + * query = notmuch_query_create (database, query_string); + * + * for (results = notmuch_query_search (query); + * notmuch_results_has_more (results); + * notmuch_result_advance (results)) + * { + * message = notmuch_results_get (results); + * .... + * } + * + * notmuch_query_destroy (query); + * + * Note that there's no explicit destructor for the notmuch_results_t + * object. + */ +notmuch_results_t * +notmuch_query_search (notmuch_query_t *query); + +/* Destroy a notmuch_query_t along with any associated resources. + * + * This will in turn destroy any notmuch_results_t objects generated + * by this query, (and in turn any notmuch_message_t objects generated + * from those results, etc.). + */ +void +notmuch_query_destroy (notmuch_query_t *query); + +/* Does the given notmuch_results_t object contain any more results. + * + * When this function returns TRUE, notmuch_results_get will return a + * valid object. Whereas when this function returns FALSE, + * notmuch_results_get will return NULL. + * + * See the documentation of notmuch_query_search for example code + * showing how to iterate over a notmuch_results_t object. + */ +notmuch_bool_t +notmuch_results_has_more (notmuch_results_t *results); + +/* Get the current result from 'results' as a notmuch_message_t. + * + * Note: The returned message belongs to 'results' and has a lifetime + * identical to it (and the query to which it belongs). + * + * See the documentation of notmuch_query_search for example code + * showing how to iterate over a notmuch_results_t object. + */ +notmuch_message_t * +notmuch_results_get (notmuch_results_t *results); + +/* Advance the 'results' iterator to the next result. + * + * See the documentation of notmuch_query_search for example code + * showing how to iterate over a notmuch_results_t object. + */ +void +notmuch_results_advance (notmuch_results_t *results); + +/* Get the message ID of 'message'. + * + * The returned string belongs to 'message' and as such, should not be + * modified by the caller and will only be valid for as long as the + * message is valid, (which is until the query from which it derived + * is destroyed). + */ +const char * +notmuch_message_get_message_id (notmuch_message_t *message); + +/* Get the tags for 'message', returning a notmuch_tags_t object which + * can be used to iterate over all tags. + * + * The tags 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_tags_t *tags; + * const char *tag; + * + * message = notmuch_results_get (results); + * + * for (tags = notmuch_message_get_tags (message); + * notmuch_tags_has_more (tags); + * notmuch_result_advance (tags)) + * { + * tag = notmuch_tags_get_string (tags); + * .... + * } + * + * Note that there's no explicit destructor for the notmuch_tags_t + * object. + */ +notmuch_tags_t * +notmuch_message_get_tags (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 + * valid string. Whereas when this function returns FALSE, + * notmuch_tags_get will return NULL. + * + * See the documentation of notmuch_message_get_tags for example code + * showing how to iterate over a notmuch_tags_t object. + */ +notmuch_bool_t +notmuch_tags_has_more (notmuch_tags_t *tags); + +/* Get the current result 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). + * + * See the documentation of notmuch_message_get_tags for example code + * showing how to iterate over a notmuch_tags_t object. + */ +const char * +notmuch_tags_get (notmuch_tags_t *tags); + +/* Advance the 'tags' iterator to the next tag. + * + * See the documentation of notmuch_message_get_tags for example code + * showing how to iterate over a notmuch_tags_t object. + */ +void +notmuch_tags_advance (notmuch_tags_t *results); + NOTMUCH_END_DECLS #endif