X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.h;h=df432bcc6605f5ddfb14e672bde30383e59ac37e;hp=b63a7d77b7616ae1f8bf12d3a68b7022d49fa28a;hb=6519aff957df7a69d86ed9a00707c911d60259f6;hpb=55c8ee9a862f8f25be84adb591564b3777d88135 diff --git a/notmuch.h b/notmuch.h index b63a7d77..df432bcc 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,216 @@ 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 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. + * + * 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); + +/* 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 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); + +/* 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); + +/* 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 + * 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: If you are finished with a message before its containing + * query, you can call notmuch_message_destroy to clean up some memory + * sooner. If you don't call it, all the memory will still be + * reclaimed when the query is destroyed. + */ +notmuch_tags_t * +notmuch_message_get_tags (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 + * 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); + +/* 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); + NOTMUCH_END_DECLS #endif