X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=d9fe152a0529206d2a780c06d03fc3091968a9cf;hp=a98241de8878b7542c5e09a3805c4578ee671314;hb=28ce73848d98d8ee2b661733402e2c10b13418d5;hpb=50ae83a17feb1fc2f48fb8e51ef73da08ae4e2f2

diff --git a/lib/notmuch.h b/lib/notmuch.h
index a98241de..d9fe152a 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -57,6 +57,9 @@ typedef int notmuch_bool_t;
  * value. Instead we should map to things like DATABASE_LOCKED or
  * whatever.
  *
+ * NOTMUCH_STATUS_READONLY_DATABASE: An attempt was made to write to a
+ *	database opened in read-only mode.
+ *
  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
  *
  * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to read or
@@ -114,6 +117,8 @@ typedef struct _notmuch_thread notmuch_thread_t;
 typedef struct _notmuch_messages notmuch_messages_t;
 typedef struct _notmuch_message notmuch_message_t;
 typedef struct _notmuch_tags notmuch_tags_t;
+typedef struct _notmuch_directory notmuch_directory_t;
+typedef struct _notmuch_filenames notmuch_filenames_t;
 
 /* Create a new, empty notmuch database located at 'path'.
  *
@@ -178,51 +183,19 @@ notmuch_database_close (notmuch_database_t *database);
 const char *
 notmuch_database_get_path (notmuch_database_t *database);
 
-/* Store an mtime within the database for 'path'.
- *
- * 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_directory_mtime
- *
- * Then, when wanting to check for updates to the directory in the
- * 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_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: mtime successfully stored in database.
- *
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
- *	occurred, mtime not stored.
- */
-notmuch_status_t
-notmuch_database_set_directory_mtime (notmuch_database_t *database,
-				      const char *path,
-				      time_t mtime);
-
-/* Retrieve the mtime from the database for 'path'.
+/* Retrieve a directory object from the database for 'path'.
  *
- * Returns the mtime value previously stored by calling
- * notmuch_database_set_directory_mtime with the same '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'.
  *
- * Returns 0 if no mtime is stored for 'path' or if any error occurred
- * querying the 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).
  */
-time_t
-notmuch_database_get_directory_mtime (notmuch_database_t *database,
-				      const char *path);
+notmuch_directory_t *
+notmuch_database_get_directory (notmuch_database_t *database,
+				const char *path);
 
 /* Add a new message to the given notmuch database.
  *
@@ -262,6 +235,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 +679,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);
 
@@ -924,6 +916,103 @@ notmuch_tags_advance (notmuch_tags_t *tags);
 void
 notmuch_tags_destroy (notmuch_tags_t *tags);
 
+/* Store an mtime within the database for 'directory'.
+ *
+ * The 'directory' should be an object retrieved from the database
+ * with notmuch_database_get_directory for a particular path.
+ *
+ * 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_directory_set_mtime with the mtime read from the
+ *     filesystem.
+ *
+ * Then, when wanting to check for updates to the directory in the
+ * future, the client can call notmuch_directory_get_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_directory_get_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: mtime successfully stored in database.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
+ *	occurred, mtime not stored.
+ */
+notmuch_status_t
+notmuch_directory_set_mtime (notmuch_directory_t *directory,
+			     time_t mtime);
+
+/* 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
+ * directory.*/
+time_t
+notmuch_directory_get_mtime (notmuch_directory_t *directory);
+
+/* Get a notmuch_filenames_t iterator listing all the filenames of
+ * messages in the database within the given directory.
+ *
+ * The returned filenames will be the basename-entries only (not
+ * complete paths). */
+notmuch_filenames_t *
+notmuch_directory_get_child_files (notmuch_directory_t *directory);
+
+/* Get a notmuch_filenams_t iterator listing all the filenames of
+ * sub-directories in the database within the given directory.
+ *
+ * The returned filenames will be the basename-entries only (not
+ * complete paths). */
+notmuch_filenames_t *
+notmuch_directory_get_child_directories (notmuch_directory_t *directory);
+
+/* Destroy a notmuch_directory_t object. */
+void
+notmuch_directory_destroy (notmuch_directory_t *directory);
+
+/* Does the given notmuch_filenames_t object contain any more
+ * filenames.
+ *
+ * When this function returns TRUE, notmuch_filenames_get will return
+ * a valid string. Whereas when this function returns FALSE,
+ * notmuch_filenames_get will return NULL.
+ */
+notmuch_bool_t
+notmuch_filenames_has_more (notmuch_filenames_t *filenames);
+
+/* Get the current filename from 'filenames' as a string.
+ *
+ * Note: The returned string belongs to 'filenames' and has a lifetime
+ * identical to it (and the directory to which it ultimately belongs).
+ */
+const char *
+notmuch_filenames_get (notmuch_filenames_t *filenames);
+
+/* Advance the 'filenames' iterator to the next filename.
+ */
+void
+notmuch_filenames_advance (notmuch_filenames_t *filenames);
+
+/* Destroy a notmuch_filenames_t object.
+ *
+ * It's not strictly necessary to call this function. All memory from
+ * the notmuch_filenames_t object will be reclaimed when the
+ * containing directory object is destroyed.
+ */
+void
+notmuch_filenames_destroy (notmuch_filenames_t *filenames);
+
 NOTMUCH_END_DECLS
 
 #endif