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_files notmuch_files_t;
/* Create a new, empty notmuch database located at 'path'.
*
const char *
notmuch_database_get_path (notmuch_database_t *database);
-/* Store a timestamp within the database.
+/* Read the stored contents of a directory from the database.
*
- * 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:
- *
- * 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'.
- *
- * 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.
- *
- * 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.
- *
- * Return value:
- *
- * NOTMUCH_STATUS_SUCCESS: Timestamp successfully stored in database.
+ * Here, 'dirname' should be a path relative to the path of
+ * 'database' (see notmuch_database_get_path), or else should be an
+ * absolute filename with initial components that match the path of
+ * 'database'.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
- * occurred. Timestamp not stored.
+ * The stored mtime of the directory along with a list of messages
+ * and directories in the database contained in 'dirname' are
+ * returned in 'directory'. The entries are sorted by filename.
*/
notmuch_status_t
-notmuch_database_set_timestamp (notmuch_database_t *database,
- const char *key, time_t timestamp);
+notmuch_database_read_directory (notmuch_database_t *database,
+ const char *filename,
+ notmuch_directory_t **directory);
-/* Retrieve a timestamp from the database.
- *
- * Returns the timestamp value previously stored by calling
- * notmuch_database_set_timestamp with the same value for 'key'.
- *
- * Returns 0 if no timestamp is stored for 'key' or if any error
- * occurred querying the database.
+/* Return the recorded 'mtime' for the given directory
*/
time_t
-notmuch_database_get_timestamp (notmuch_database_t *database,
- const char *key);
+notmuch_directory_get_mtime (notmuch_directory_t *directory);
+
+/* Return a notmuch_files_t iterator for all regular files in 'directory'.
+ */
+notmuch_files_t *
+notmuch_directory_get_files (notmuch_directory_t *directory);
+
+/* Return a notmuch_files_t iterator for all sub-directories of
+ * 'directory'.
+ */
+notmuch_files_t *
+notmuch_directory_get_subdirs (notmuch_directory_t *directory);
+
+/* Does the given notmuch_files_t object contain any more results.
+ */
+notmuch_bool_t
+notmuch_files_has_more (notmuch_files_t *files);
+
+/* Get the current filename from 'files' as a string.
+ */
+const char *
+notmuch_files_get_filename (notmuch_files_t *files);
/* Add a new message to the given notmuch 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
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);
+/* Remove a filename for the email corresponding to 'message'.
+ *
+ * This removes the association between a filename and a message,
+ * when the last filename is gone, the entire message is removed
+ * from the database.
+ */
+notmuch_status_t
+notmuch_message_remove_filename (notmuch_message_t *message,
+ const char *filename);
+
/* 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'. */
projects / notmuch / blobdiff