lib: Rename set/get_timestamp to set/get_directory_mtime.

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 3974820c0d3573305f8b5a168e8a414fd357bdfa..a98241de8878b7542c5e09a3805c4578ee671314 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -178,56 +178,51 @@ notmuch_database_close (notmuch_database_t *database);
 const char *
 notmuch_database_get_path (notmuch_database_t *database);
 
-/* Store a timestamp within the database.
+/* Store an mtime within the database for 'path'.
  *
- * 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:
+ * 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_database_set_timestamp with the path of the
- *     directory as 'key' and the originally read mtime as 'value'.
+ *   o Call notmuch_database_set_directory_mtime
  *
  * 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.
+ * future, the client can call notmuch_database_get_directory_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_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.
+ * Note: The notmuch_database_get_directory_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: Timestamp successfully stored in database.
+ * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database.
  *
  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
- *     occurred. Timestamp not stored.
+ *     occurred, mtime not stored.
  */
 notmuch_status_t
-notmuch_database_set_timestamp (notmuch_database_t *database,
-                               const char *key, time_t timestamp);
+notmuch_database_set_directory_mtime (notmuch_database_t *database,
+                                     const char *path,
+                                     time_t mtime);
 
-/* Retrieve a timestamp from the database.
+/* Retrieve the mtime from the database for 'path'.
  *
- * Returns the timestamp value previously stored by calling
- * notmuch_database_set_timestamp with the same value for 'key'.
+ * Returns the mtime value previously stored by calling
+ * notmuch_database_set_directory_mtime with the same 'path'.
  *
- * Returns 0 if no timestamp is stored for 'key' or if any error
- * occurred querying the database.
+ * Returns 0 if no mtime is stored for 'path' or if any error occurred
+ * querying the database.
  */
 time_t
-notmuch_database_get_timestamp (notmuch_database_t *database,
-                               const char *key);
+notmuch_database_get_directory_mtime (notmuch_database_t *database,
+                                     const char *path);
 
 /* Add a new message to the given notmuch database.
  *
@@ -280,6 +275,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
@@ -625,6 +630,21 @@ notmuch_messages_advance (notmuch_messages_t *messages);
 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
@@ -686,7 +706,7 @@ notmuch_message_get_filename (notmuch_message_t *message);
 
 /* Message flags */
 typedef enum _notmuch_message_flag {
-    NOTMUCH_MSG_FLAG_MATCHING_SEARCH,
+    NOTMUCH_MESSAGE_FLAG_MATCH,
 } notmuch_message_flag_t;
 
 /* Get a value of a flag for the email corresponding to 'message'. */