database: Add new, public notmuch_database_remove_message

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index a98241de8878b7542c5e09a3805c4578ee671314..2e59865633ffa6ce7b8206ec7d14ac1202b618e9 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -179,6 +179,11 @@ const char *
 notmuch_database_get_path (notmuch_database_t *database);
 
 /* Store an mtime within the database for 'path'.
+ *
+ * Here,'path' should be the path of a directory 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'.
  *
  * The intention is for the caller to use the mtime to allow efficient
  * identification of new messages to be added to the database. The
@@ -262,6 +267,19 @@ notmuch_database_add_message (notmuch_database_t *database,
                              const char *filename,
                              notmuch_message_t **message);
 
+/* 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.
+ */
+notmuch_status_t
+notmuch_database_remove_message (notmuch_database_t *database,
+                                const char *filename);
+
 /* Find a message with the given message_id.
  *
  * If the database contains a message with the given message_id, then
@@ -693,14 +711,20 @@ notmuch_message_get_thread_id (notmuch_message_t *message);
 notmuch_messages_t *
 notmuch_message_get_replies (notmuch_message_t *message);
 
-/* Get the filename for the email corresponding to 'message'.
+/* Get a filename for the email corresponding to 'message'.
  *
  * The returned filename is an absolute filename, (the initial
  * component will match notmuch_database_get_path() ).
  *
  * The returned string belongs to the message so should not be
  * modified or freed by the caller (nor should it be referenced after
- * the message is destroyed). */
+ * the message is destroyed).
+ *
+ * Note: If this message corresponds to multiple files in the mail
+ * store, (that is, multiple files contain identical message IDs),
+ * this function will arbitrarily return a single one of those
+ * filenames.
+ */
 const char *
 notmuch_message_get_filename (notmuch_message_t *message);