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,
* 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.
* 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);
* ....
* 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);
* ....
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.
*
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.
*
* 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);
* ....
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,
* 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.
*
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.
*
* 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 *
* 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);
* ....
* 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.
*
* 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
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,
* 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.
*
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.
*
/* 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);
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,
* 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.
*
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.
*
projects / notmuch / blobdiff