X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=d8508dfd682821bdeaed809e622a71db1635086f;hp=d0b0d9e43f5bc302e25cb67bccb771772b739df6;hb=909f52bd8c4bdfa11cd3e75e3d0959e0293689bd;hpb=f7b49d658ad507b72d01b06d56975dba0b7cafc8 diff --git a/lib/notmuch.h b/lib/notmuch.h index d0b0d9e4..d8508dfd 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -57,6 +57,9 @@ typedef int notmuch_bool_t; * value. Instead we should map to things like DATABASE_LOCKED or * whatever. * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: An attempt was made to write to + * a database opened in read-only mode. + * * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred * * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to read or @@ -86,6 +89,7 @@ typedef int notmuch_bool_t; typedef enum _notmuch_status { NOTMUCH_STATUS_SUCCESS = 0, NOTMUCH_STATUS_OUT_OF_MEMORY, + NOTMUCH_STATUS_READ_ONLY_DATABASE, NOTMUCH_STATUS_XAPIAN_EXCEPTION, NOTMUCH_STATUS_FILE_ERROR, NOTMUCH_STATUS_FILE_NOT_EMAIL, @@ -113,6 +117,8 @@ typedef struct _notmuch_thread notmuch_thread_t; typedef struct _notmuch_messages notmuch_messages_t; typedef struct _notmuch_message notmuch_message_t; typedef struct _notmuch_tags notmuch_tags_t; +typedef struct _notmuch_directory notmuch_directory_t; +typedef struct _notmuch_filenames notmuch_filenames_t; /* Create a new, empty notmuch database located at 'path'. * @@ -136,6 +142,11 @@ typedef struct _notmuch_tags notmuch_tags_t; notmuch_database_t * notmuch_database_create (const char *path); +typedef enum { + NOTMUCH_DATABASE_MODE_READ_ONLY = 0, + NOTMUCH_DATABASE_MODE_READ_WRITE +} notmuch_database_mode_t; + /* XXX: I think I'd like this to take an extra argument of * notmuch_status_t* for returning a status value on failure. */ @@ -143,7 +154,9 @@ notmuch_database_create (const char *path); * * The database should have been created at some time in the past, * (not necessarily by this process), by calling - * notmuch_database_create with 'path'. + * notmuch_database_create with 'path'. By default the database should be + * opened for reading only. In order to write to the database you need to + * pass the NOTMUCH_DATABASE_MODE_WRITABLE mode. * * An existing notmuch database can be identified by the presence of a * directory named ".notmuch" below 'path'. @@ -155,7 +168,8 @@ notmuch_database_create (const char *path); * an error message on stderr). */ notmuch_database_t * -notmuch_database_open (const char *path); +notmuch_database_open (const char *path, + notmuch_database_mode_t mode); /* Close the given notmuch database, freeing all associated * resources. See notmuch_database_open. */ @@ -169,60 +183,51 @@ notmuch_database_close (notmuch_database_t *database); const char * notmuch_database_get_path (notmuch_database_t *database); -/* Store a timestamp within the database. - * - * The Notmuch database will not interpret this key nor the timestamp - * values at all. It will merely store them together and return the - * timestamp when notmuch_database_get_timestamp is called with the - * same value for 'key'. - * - * The intention is for the caller to use the timestamp to allow - * efficient identification of new messages to be added to the - * database. The recommended usage is as follows: - * - * o Read the mtime of a directory from the filesystem - * - * o Call add_message for all mail files in the directory - * - * o Call notmuch_database_set_timestamp with the path of the - * directory as 'key' and the originally read mtime as 'value'. - * - * Then, when wanting to check for updates to the directory in the - * future, the client can call notmuch_database_get_timestamp and know - * that it only needs to add files if the mtime of the directory and - * files are newer than the stored timestamp. - * - * Note: The notmuch_database_get_timestamp function does not allow - * the caller to distinguish a timestamp of 0 from a non-existent - * timestamp. So don't store a timestamp of 0 unless you are - * comfortable with that. +/* Return the database format version of the given database. */ +unsigned int +notmuch_database_get_version (notmuch_database_t *database); + +/* Does this database need to be upgraded before writing to it? * - * Return value: + * If this function returns TRUE then no functions that modify the + * database (notmuch_database_add_message, notmuch_message_add_tag, + * notmuch_directory_set_mtime, etc.) will work unless the function + * notmuch_database_upgrade is called successfully first. */ +notmuch_bool_t +notmuch_database_needs_upgrade (notmuch_database_t *database); + +/* Upgrade the current database. * - * NOTMUCH_STATUS_SUCCESS: Timestamp successfully stored in database. + * After opening a database in read-write mode, the client should + * check if an upgrade is needed (notmuch_database_needs_upgrade) and + * if so, upgrade with this function before making any modifications. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception - * occurred. Timestamp not stored. + * The optional progress_notify callback can be used by the caller to + * provide progress indication to the user. If non-NULL it will be + * called periodically with 'count' as the number of messages upgraded + * so far and 'total' the overall number of messages that will be + * converted. */ notmuch_status_t -notmuch_database_set_timestamp (notmuch_database_t *database, - const char *key, time_t timestamp); +notmuch_database_upgrade (notmuch_database_t *database, + void (*progress_notify) (void *closure, + unsigned int count, + unsigned int total), + void *closure); -/* Retrieve a timestamp from the database. +/* Retrieve a directory object from the database for 'path'. * - * Returns the timestamp value previously stored by calling - * notmuch_database_set_timestamp with the same value for 'key'. - * - * Returns 0 if no timestamp is stored for 'key' or if any error - * occurred querying the database. + * Here, 'path' should be a path relative to the path of 'database' + * (see notmuch_database_get_path), or else should be an absolute path + * with initial components that match the path of 'database'. */ -time_t -notmuch_database_get_timestamp (notmuch_database_t *database, - const char *key); +notmuch_directory_t * +notmuch_database_get_directory (notmuch_database_t *database, + const char *path); /* Add a new message to the given notmuch database. * - * Here,'filename' should be a path relative to the the path of + * Here,'filename' should be a path relative to the path of * 'database' (see notmuch_database_get_path), or else should be an * absolute filename with initial components that match the path of * 'database'. @@ -243,8 +248,8 @@ notmuch_database_get_timestamp (notmuch_database_t *database, * NOTMUCH_STATUS_SUCCESS: Message successfully added to database. * * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message - * ID as another message already in the database. Nothing added - * to the database. + * ID as another message already in the database. The new filename + * was successfully added to the message in the database. * * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the * file, (such as permission denied, or file not found, @@ -252,13 +257,41 @@ notmuch_database_get_timestamp (notmuch_database_t *database, * * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look * like an email message. Nothing added to the database. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so no message can be added. */ notmuch_status_t notmuch_database_add_message (notmuch_database_t *database, const char *filename, notmuch_message_t **message); -/* Find a message with the given messsage_id. +/* Remove a message from the given notmuch database. + * + * Note that only this particular filename association is removed from + * the database. If the same message (as determined by the message ID) + * is still available via other filenames, then the message will + * persist in the database for those filenames. When the last filename + * is removed for a particular message, the database content for that + * message will be entirely removed. + * + * Return value: + * + * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the + * message was removed from the database. + * + * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but + * the message persists in the database with at least one other + * filename. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so no message can be removed. + */ +notmuch_status_t +notmuch_database_remove_message (notmuch_database_t *database, + const char *filename); + +/* Find a message with the given message_id. * * If the database contains a message with the given message_id, then * a new notmuch_message_t object is returned. The caller should call @@ -271,6 +304,16 @@ notmuch_message_t * notmuch_database_find_message (notmuch_database_t *database, const char *message_id); +/* Return a list of all tags found in the database. + * + * This function creates a list of all tags found in the database. The + * resulting list contains all tags from all messages found in the database. + * + * On error this function returns NULL. + */ +notmuch_tags_t * +notmuch_database_get_all_tags (notmuch_database_t *db); + /* Create a new query for 'database'. * * Here, 'database' should be an open database, (see @@ -299,8 +342,8 @@ notmuch_query_create (notmuch_database_t *database, /* Sort values for notmuch_query_set_sort */ typedef enum { - NOTMUCH_SORT_DATE, - NOTMUCH_SORT_DATE_REVERSE, + NOTMUCH_SORT_OLDEST_FIRST, + NOTMUCH_SORT_NEWEST_FIRST, NOTMUCH_SORT_MESSAGE_ID } notmuch_sort_t; @@ -313,14 +356,6 @@ 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; @@ -353,22 +388,13 @@ 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, - int first, int max_threads); +notmuch_query_search_threads (notmuch_query_t *query); /* 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; @@ -401,8 +427,7 @@ 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, - int first, int max_messages); +notmuch_query_search_messages (notmuch_query_t *query); /* Destroy a notmuch_query_t along with any associated resources. * @@ -459,6 +484,14 @@ notmuch_threads_advance (notmuch_threads_t *threads); void notmuch_threads_destroy (notmuch_threads_t *threads); +/* Return an estimate of the number of messages matching a search + * + * This function performs a search and returns Xapian's best + * guess as to number of matching messages. + */ +unsigned +notmuch_query_count_messages (notmuch_query_t *query); + /* Get the thread ID of 'thread'. * * The returned string belongs to 'thread' and as such, should not be @@ -477,6 +510,21 @@ notmuch_thread_get_thread_id (notmuch_thread_t *thread); int notmuch_thread_get_total_messages (notmuch_thread_t *thread); +/* Get a notmuch_messages_t iterator for the top-level messages in + * 'thread'. + * + * This iterator will not necessarily iterate over all of the messages + * in the thread. It will only iterate over the messages in the thread + * which are not replies to other messages in the thread. + * + * To iterate over all messages in the thread, the caller will need to + * iterate over the result of notmuch_message_get_replies for each + * top-level message (and do that recursively for the resulting + * messages, etc.). + */ +notmuch_messages_t * +notmuch_thread_get_toplevel_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 @@ -605,12 +653,27 @@ notmuch_messages_advance (notmuch_messages_t *messages); /* Destroy a notmuch_messages_t object. * * It's not strictly necessary to call this function. All memory from - * the notmuch_messages_t object will be reclaimed when the containg + * the notmuch_messages_t object will be reclaimed when the containing * query object is destroyed. */ void notmuch_messages_destroy (notmuch_messages_t *messages); +/* Return a list of tags from all messages. + * + * The resulting list is guaranteed not to contain duplicated tags. + * + * WARNING: You can no longer iterate over messages after calling this + * function, because the iterator will point at the end of the list. + * We do not have a function to reset the iterator yet and the only + * way how you can iterate over the list again is to recreate the + * message list. + * + * The function returns NULL on error. + */ +notmuch_tags_t * +notmuch_messages_collect_tags (notmuch_messages_t *messages); + /* Get the message ID of 'message'. * * The returned string belongs to 'message' and as such, should not be @@ -639,17 +702,58 @@ notmuch_message_get_message_id (notmuch_message_t *message); const char * notmuch_message_get_thread_id (notmuch_message_t *message); -/* Get the filename for the email corresponding to 'message'. +/* Get a notmuch_messages_t iterator for all of the replies to + * 'message'. + * + * Note: This call only makes sense if 'message' was ultimately + * obtained from a notmuch_thread_t object, (such as by coming + * directly from the result of calling notmuch_thread_get_ + * toplevel_messages or by any number of subsequent + * calls to notmuch_message_get_replies). + * + * If 'message' was obtained through some non-thread means, (such as + * by a call to notmuch_query_search_messages), then this function + * will return NULL. + * + * If there are no replies to 'message', this function will return + * NULL. (Note that notmuch_messages_has_more will accept that NULL + * value as legitimate, and simply return FALSE for it.) + */ +notmuch_messages_t * +notmuch_message_get_replies (notmuch_message_t *message); + +/* Get a filename for the email corresponding to 'message'. * * The returned filename is an absolute filename, (the initial * component will match notmuch_database_get_path() ). * * The returned string belongs to the message so should not be * modified or freed by the caller (nor should it be referenced after - * the message is destroyed). */ + * the message is destroyed). + * + * Note: If this message corresponds to multiple files in the mail + * store, (that is, multiple files contain identical message IDs), + * this function will arbitrarily return a single one of those + * filenames. + */ const char * notmuch_message_get_filename (notmuch_message_t *message); +/* Message flags */ +typedef enum _notmuch_message_flag { + NOTMUCH_MESSAGE_FLAG_MATCH, +} notmuch_message_flag_t; + +/* Get a value of a flag for the email corresponding to 'message'. */ +notmuch_bool_t +notmuch_message_get_flag (notmuch_message_t *message, + notmuch_message_flag_t flag); + +/* Set a value of a flag for the email corresponding to 'message'. */ +void +notmuch_message_set_flag (notmuch_message_t *message, + notmuch_message_flag_t flag, notmuch_bool_t value); + /* Get the date of 'message' as a time_t value. * * For the original textual representation of the Date header from the @@ -719,6 +823,9 @@ notmuch_message_get_tags (notmuch_message_t *message); * * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long * (exceeds NOTMUCH_TAG_MAX) + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ notmuch_status_t notmuch_message_add_tag (notmuch_message_t *message, const char *tag); @@ -733,6 +840,9 @@ notmuch_message_add_tag (notmuch_message_t *message, const char *tag); * * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long * (exceeds NOTMUCH_TAG_MAX) + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ notmuch_status_t notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); @@ -741,8 +851,11 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); * * See notmuch_message_freeze for an example showing how to safely * replace tag values. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ -void +notmuch_status_t notmuch_message_remove_all_tags (notmuch_message_t *message); /* Freeze the current state of 'message' within the database. @@ -777,8 +890,15 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * somehow getting interrupted. This could result in the message being * left with no tags if the interruption happened after * notmuch_message_remove_all_tags but before notmuch_message_add_tag. + * + * Return value: + * + * NOTMUCH_STATUS_SUCCESS: Message successfully frozen. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so message cannot be modified. */ -void +notmuch_status_t notmuch_message_freeze (notmuch_message_t *message); /* Thaw the current 'message', synchronizing any changes that may have @@ -830,7 +950,7 @@ notmuch_tags_has_more (notmuch_tags_t *tags); /* Get the current tag 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). + * identical to it (and the query to which it ultimately belongs). * * See the documentation of notmuch_message_get_tags for example code * showing how to iterate over a notmuch_tags_t object. @@ -849,12 +969,124 @@ notmuch_tags_advance (notmuch_tags_t *tags); /* 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 + * the notmuch_tags_t object will be reclaimed when the containing * message or query objects are destroyed. */ void notmuch_tags_destroy (notmuch_tags_t *tags); +/* Store an mtime within the database for 'directory'. + * + * The 'directory' should be an object retrieved from the database + * with notmuch_database_get_directory for a particular path. + * + * The intention is for the caller to use the mtime to allow efficient + * identification of new messages to be added to the database. The + * recommended usage is as follows: + * + * o Read the mtime of a directory from the filesystem + * + * o Call add_message for all mail files in the directory + * + * o Call notmuch_directory_set_mtime with the mtime read from the + * filesystem. + * + * Then, when wanting to check for updates to the directory in the + * future, the client can call notmuch_directory_get_mtime and know + * that it only needs to add files if the mtime of the directory and + * files are newer than the stored timestamp. + * + * Note: The notmuch_directory_get_mtime function does not allow the + * caller to distinguish a timestamp of 0 from a non-existent + * timestamp. So don't store a timestamp of 0 unless you are + * comfortable with that. + * + * Return value: + * + * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database. + * + * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception + * occurred, mtime not stored. + * + * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only + * mode so directory mtime cannot be modified. + */ +notmuch_status_t +notmuch_directory_set_mtime (notmuch_directory_t *directory, + time_t mtime); + +/* Get the mtime of a directory, (as previously stored with + * notmuch_directory_set_mtime). + * + * Returns 0 if no mtime has previously been stored for this + * directory.*/ +time_t +notmuch_directory_get_mtime (notmuch_directory_t *directory); + +/* Get a notmuch_filenames_t iterator listing all the filenames of + * messages in the database within the given directory. + * + * The returned filenames will be the basename-entries only (not + * complete paths). */ +notmuch_filenames_t * +notmuch_directory_get_child_files (notmuch_directory_t *directory); + +/* Get a notmuch_filenams_t iterator listing all the filenames of + * sub-directories in the database within the given directory. + * + * The returned filenames will be the basename-entries only (not + * complete paths). */ +notmuch_filenames_t * +notmuch_directory_get_child_directories (notmuch_directory_t *directory); + +/* Destroy a notmuch_directory_t object. */ +void +notmuch_directory_destroy (notmuch_directory_t *directory); + +/* Does the given notmuch_filenames_t object contain any more + * filenames. + * + * When this function returns TRUE, notmuch_filenames_get will return + * a valid string. Whereas when this function returns FALSE, + * notmuch_filenames_get will return NULL. + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will always return FALSE. + */ +notmuch_bool_t +notmuch_filenames_has_more (notmuch_filenames_t *filenames); + +/* Get the current filename from 'filenames' as a string. + * + * Note: The returned string belongs to 'filenames' and has a lifetime + * identical to it (and the directory to which it ultimately belongs). + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will always return NULL. + */ +const char * +notmuch_filenames_get (notmuch_filenames_t *filenames); + +/* Advance the 'filenames' iterator to the next filename. + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will do nothing. + */ +void +notmuch_filenames_advance (notmuch_filenames_t *filenames); + +/* Destroy a notmuch_filenames_t object. + * + * It's not strictly necessary to call this function. All memory from + * the notmuch_filenames_t object will be reclaimed when the + * containing directory object is destroyed. + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will do nothing. + */ +void +notmuch_filenames_destroy (notmuch_filenames_t *filenames); + NOTMUCH_END_DECLS #endif