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 c05e802d584e798d9a78c9802bb0b8b8f7e4acb9..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.
  *
@@ -635,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
@@ -694,6 +704,21 @@ notmuch_message_get_replies (notmuch_message_t *message);
 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