X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=a7e66dd35c9e69bfa8882b8b2b27b8aee8d99a97;hp=d3e50a79536c37283e3cd42fc74b5e7c79ad1d88;hb=9ddde6eb14c126e314d90e2e08f213fb81f0457f;hpb=7a9bacac6786729d7f28495b0ef30f9b6ded7696

diff --git a/lib/notmuch.h b/lib/notmuch.h
index d3e50a79..a7e66dd3 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -156,7 +156,7 @@ typedef enum {
  * (not necessarily by this process), by calling
  * 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.
+ * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.
  *
  * An existing notmuch database can be identified by the presence of a
  * directory named ".notmuch" below 'path'.
@@ -247,8 +247,9 @@ 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. The new filename
- *	was successfully added to the message in the database.
+ *	ID as another message already in the database. The new
+ *	filename was successfully added to the message in the database
+ *	(if not already present).
  *
  * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
  *	file, (such as permission denied, or file not found,
@@ -324,11 +325,13 @@ notmuch_database_get_all_tags (notmuch_database_t *db);
  *
  * http://xapian.org/docs/queryparser.html
  *
- * As a special case, passing a length-zero string, (that is ""), will
+ * As a special case, passing either a length-zero string, (that is ""),
+ * or a string consisting of a single asterisk (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.
@@ -364,8 +367,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);
  *         ....
@@ -403,8 +406,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);
  *         ....
@@ -432,25 +435,24 @@ notmuch_query_search_messages (notmuch_query_t *query);
  *
  * This will in turn destroy any notmuch_threads_t and
  * notmuch_messages_t objects generated by this query, (and in
- * turn any notmuch_thrad_t and notmuch_message_t objects generated
+ * turn any notmuch_thread_t and notmuch_message_t objects generated
  * from those results, etc.), if such objects haven't already been
  * destroyed.
  */
 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.
  *
@@ -466,13 +468,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.
  *
@@ -566,7 +573,7 @@ notmuch_thread_get_subject (notmuch_thread_t *thread);
 time_t
 notmuch_thread_get_oldest_date (notmuch_thread_t *thread);
 
-/* Get the date of the oldest message in 'thread' as a time_t value.
+/* Get the date of the newest message in 'thread' as a time_t value.
  */
 time_t
 notmuch_thread_get_newest_date (notmuch_thread_t *thread);
@@ -593,8 +600,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);
  *         ....
@@ -614,8 +621,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,
@@ -625,7 +631,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.
  *
@@ -641,13 +647,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.
  *
@@ -715,7 +726,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 *
@@ -792,8 +803,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);
  *         ....
@@ -915,7 +926,7 @@ notmuch_message_freeze (notmuch_message_t *message);
  * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least
  *	its frozen count has successfully been reduced by 1).
  *
- * NOTMUCH_STATUS_UNBALANCE_FREEZE_THAW: An attempt was made to thaw
+ * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw
  *	an unfrozen message. That is, there have been an unbalanced
  *	number of calls to notmuch_message_freeze and
  *	notmuch_message_thaw.
@@ -934,7 +945,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,
@@ -944,7 +955,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.
  *
@@ -957,13 +968,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.
  *
@@ -1042,8 +1058,7 @@ 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,
@@ -1053,7 +1068,7 @@ notmuch_directory_destroy (notmuch_directory_t *directory);
  * 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.
  *
@@ -1066,13 +1081,18 @@ notmuch_filenames_has_more (notmuch_filenames_t *filenames);
 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.
  *