X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=b40fa53d8a25fbcae9f442e614c19c6ae4b7ff41;hp=d9fe152a0529206d2a780c06d03fc3091968a9cf;hb=bc69bf09cb8c989f4b3b8116f0907b7618000299;hpb=3f32fd8a1c06d417bdcb467bac2805f658cb5476 diff --git a/lib/notmuch.h b/lib/notmuch.h index d9fe152a..b40fa53d 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -57,8 +57,8 @@ typedef int notmuch_bool_t; * value. Instead we should map to things like DATABASE_LOCKED or * whatever. * - * NOTMUCH_STATUS_READONLY_DATABASE: An attempt was made to write to a - * database opened in read-only mode. + * 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 * @@ -89,7 +89,7 @@ typedef int notmuch_bool_t; typedef enum _notmuch_status { NOTMUCH_STATUS_SUCCESS = 0, NOTMUCH_STATUS_OUT_OF_MEMORY, - NOTMUCH_STATUS_READONLY_DATABASE, + NOTMUCH_STATUS_READ_ONLY_DATABASE, NOTMUCH_STATUS_XAPIAN_EXCEPTION, NOTMUCH_STATUS_FILE_ERROR, NOTMUCH_STATUS_FILE_NOT_EMAIL, @@ -183,15 +183,42 @@ notmuch_database_close (notmuch_database_t *database); const char * notmuch_database_get_path (notmuch_database_t *database); +/* 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? + * + * 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. + * + * 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. + * + * 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 'progress' as a floating-point value in + * the range of [0.0 .. 1.0] indicating the progress made so far in + * the upgrade process. + */ +notmuch_status_t +notmuch_database_upgrade (notmuch_database_t *database, + void (*progress_notify) (void *closure, + double progress), + void *closure); + /* Retrieve a directory object from the database for 'path'. * * 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'. - * - * Note: The resulting notmuch_directory_t object will represent the - * state as it currently exists in the database, (and will not reflect - * subsequent changes). */ notmuch_directory_t * notmuch_database_get_directory (notmuch_database_t *database, @@ -220,8 +247,8 @@ notmuch_database_get_directory (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, @@ -229,6 +256,9 @@ notmuch_database_get_directory (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, @@ -237,12 +267,24 @@ notmuch_database_add_message (notmuch_database_t *database, /* Remove a message from the given notmuch database. * - * Note that the 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. + * 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, @@ -285,8 +327,9 @@ notmuch_database_get_all_tags (notmuch_database_t *db); * 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. + * See notmuch_query_set_sort for controlling the order of results. + * See notmuch_query_search_messages and notmuch_query_search_threads + * to actually execute the query. * * User should call notmuch_query_destroy when finished with this * query. @@ -322,8 +365,8 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort); * query = notmuch_query_create (database, query_string); * * for (threads = notmuch_query_search_threads (query); - * notmuch_threads_has_more (threads); - * notmuch_threads_advance (threads)) + * notmuch_threads_valid (threads); + * notmuch_threads_move_to_next (threads)) * { * thread = notmuch_threads_get (threads); * .... @@ -361,8 +404,8 @@ notmuch_query_search_threads (notmuch_query_t *query); * query = notmuch_query_create (database, query_string); * * for (messages = notmuch_query_search_messages (query); - * notmuch_messages_has_more (messages); - * notmuch_messages_advance (messages)) + * notmuch_messages_valid (messages); + * notmuch_messages_move_to_next (messages)) * { * message = notmuch_messages_get (messages); * .... @@ -397,18 +440,17 @@ notmuch_query_search_messages (notmuch_query_t *query); void notmuch_query_destroy (notmuch_query_t *query); -/* Does the given notmuch_threads_t object contain any more - * results. +/* Is the given 'threads' iterator pointing at a valid thread. * - * When this function returns TRUE, notmuch_threads_get will - * return a valid object. Whereas when this function returns FALSE, + * When this function returns TRUE, notmuch_threads_get will return a + * valid object. Whereas when this function returns FALSE, * notmuch_threads_get will return NULL. * * See the documentation of notmuch_query_search_threads for example * code showing how to iterate over a notmuch_threads_t object. */ notmuch_bool_t -notmuch_threads_has_more (notmuch_threads_t *threads); +notmuch_threads_valid (notmuch_threads_t *threads); /* Get the current thread from 'threads' as a notmuch_thread_t. * @@ -424,13 +466,18 @@ notmuch_threads_has_more (notmuch_threads_t *threads); notmuch_thread_t * notmuch_threads_get (notmuch_threads_t *threads); -/* Advance the 'threads' iterator to the next thread. +/* Move the 'threads' iterator to the next thread. + * + * If 'threads' is already pointing at the last thread then the + * iterator will be moved to a point just beyond that last thread, + * (where notmuch_threads_valid will return FALSE and + * notmuch_threads_get will return NULL). * * See the documentation of notmuch_query_search_threads for example * code showing how to iterate over a notmuch_threads_t object. */ void -notmuch_threads_advance (notmuch_threads_t *threads); +notmuch_threads_move_to_next (notmuch_threads_t *threads); /* Destroy a notmuch_threads_t object. * @@ -551,8 +598,8 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread); * thread = notmuch_threads_get (threads); * * for (tags = notmuch_thread_get_tags (thread); - * notmuch_tags_has_more (tags); - * notmuch_result_advance (tags)) + * notmuch_tags_valid (tags); + * notmuch_result_move_to_next (tags)) * { * tag = notmuch_tags_get (tags); * .... @@ -572,8 +619,7 @@ notmuch_thread_get_tags (notmuch_thread_t *thread); void notmuch_thread_destroy (notmuch_thread_t *thread); -/* Does the given notmuch_messages_t object contain any more - * messages. +/* Is the given 'messages' iterator pointing at a valid message. * * When this function returns TRUE, notmuch_messages_get will return a * valid object. Whereas when this function returns FALSE, @@ -583,7 +629,7 @@ notmuch_thread_destroy (notmuch_thread_t *thread); * code showing how to iterate over a notmuch_messages_t object. */ notmuch_bool_t -notmuch_messages_has_more (notmuch_messages_t *messages); +notmuch_messages_valid (notmuch_messages_t *messages); /* Get the current message from 'messages' as a notmuch_message_t. * @@ -599,13 +645,18 @@ notmuch_messages_has_more (notmuch_messages_t *messages); notmuch_message_t * notmuch_messages_get (notmuch_messages_t *messages); -/* Advance the 'messages' iterator to the next result. +/* Move the 'messages' iterator to the next message. + * + * If 'messages' is already pointing at the last message then the + * iterator will be moved to a point just beyond that last message, + * (where notmuch_messages_valid will return FALSE and + * notmuch_messages_get will return NULL). * * See the documentation of notmuch_query_search_messages for example * code showing how to iterate over a notmuch_messages_t object. */ void -notmuch_messages_advance (notmuch_messages_t *messages); +notmuch_messages_move_to_next (notmuch_messages_t *messages); /* Destroy a notmuch_messages_t object. * @@ -673,7 +724,7 @@ notmuch_message_get_thread_id (notmuch_message_t *message); * 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 + * NULL. (Note that notmuch_messages_valid will accept that NULL * value as legitimate, and simply return FALSE for it.) */ notmuch_messages_t * @@ -750,8 +801,8 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header); * message = notmuch_database_find_message (database, message_id); * * for (tags = notmuch_message_get_tags (message); - * notmuch_tags_has_more (tags); - * notmuch_result_advance (tags)) + * notmuch_tags_valid (tags); + * notmuch_result_move_to_next (tags)) * { * tag = notmuch_tags_get (tags); * .... @@ -780,6 +831,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); @@ -794,6 +848,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); @@ -802,8 +859,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. @@ -813,7 +873,7 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * notmuch_message_remove_all_tags), will not be committed to the * database until the message is thawed with notmuch_message_thaw. * - * Multiple calls to freeze/thaw are valid and these calls with + * Multiple calls to freeze/thaw are valid and these calls will * "stack". That is there must be as many calls to thaw as to freeze * before a message is actually thawed. * @@ -831,15 +891,22 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * notmuch_message_thaw (message); * * With freeze/thaw used like this, the message in the database is - * guaranteed to have either the full set of original tag value, or + * guaranteed to have either the full set of original tag values, or * the full set of new tag values, but nothing in between. * * Imagine the example above without freeze/thaw and the operation * 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 @@ -876,7 +943,7 @@ notmuch_message_thaw (notmuch_message_t *message); void notmuch_message_destroy (notmuch_message_t *message); -/* Does the given notmuch_tags_t object contain any more tags. +/* Is the given 'tags' iterator pointing at a valid tag. * * When this function returns TRUE, notmuch_tags_get will return a * valid string. Whereas when this function returns FALSE, @@ -886,7 +953,7 @@ notmuch_message_destroy (notmuch_message_t *message); * showing how to iterate over a notmuch_tags_t object. */ notmuch_bool_t -notmuch_tags_has_more (notmuch_tags_t *tags); +notmuch_tags_valid (notmuch_tags_t *tags); /* Get the current tag from 'tags' as a string. * @@ -899,13 +966,18 @@ notmuch_tags_has_more (notmuch_tags_t *tags); const char * notmuch_tags_get (notmuch_tags_t *tags); -/* Advance the 'tags' iterator to the next tag. +/* Move the 'tags' iterator to the next tag. + * + * If 'tags' is already pointing at the last tag then the iterator + * will be moved to a point just beyond that last tag, (where + * notmuch_tags_valid will return FALSE and 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. */ void -notmuch_tags_advance (notmuch_tags_t *tags); +notmuch_tags_move_to_next (notmuch_tags_t *tags); /* Destroy a notmuch_tags_t object. * @@ -948,6 +1020,9 @@ notmuch_tags_destroy (notmuch_tags_t *tags); * * 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, @@ -956,7 +1031,7 @@ notmuch_directory_set_mtime (notmuch_directory_t *directory, /* Get the mtime of a directory, (as previously stored with * notmuch_directory_set_mtime). * - * Returns 0 if not mtime has previously been stored for this + * Returns 0 if no mtime has previously been stored for this * directory.*/ time_t notmuch_directory_get_mtime (notmuch_directory_t *directory); @@ -981,34 +1056,50 @@ notmuch_directory_get_child_directories (notmuch_directory_t *directory); void notmuch_directory_destroy (notmuch_directory_t *directory); -/* Does the given notmuch_filenames_t object contain any more - * filenames. +/* Is the given 'filenames' iterator pointing at a valid filename. * * 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); +notmuch_filenames_valid (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. +/* Move the 'filenames' iterator to the next filename. + * + * If 'filenames' is already pointing at the last filename then the + * iterator will be moved to a point just beyond that last filename, + * (where notmuch_filenames_valid will return FALSE and + * notmuch_filenames_get will return NULL). + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will do nothing. */ void -notmuch_filenames_advance (notmuch_filenames_t *filenames); +notmuch_filenames_move_to_next (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);