/* Add a new message to the given notmuch database.
*
* Here,'filename' should be a path relative to the the path of
- * 'database' (see notmuch_database_get_path). The file should be a
- * single mail message (not a multi-message mbox) that is expected to
- * remain at its current location, (since the notmuch database will
- * reference the filename, and will not copy the entire contents of
- * the file.
- *
- * If 'message' is not NULL, then '*message' will be initialized to a
- * message object that can be used for things such as adding tags to
- * the just-added message. The user should call
- * notmuch_message_destroy when done with the message.
+ * 'database' (see notmuch_database_get_path), or else should be an
+ * absolute filename with initial components that match the path of
+ * 'database'.
+ *
+ * The file should be a single mail message (not a multi-message mbox)
+ * that is expected to remain at its current location, (since the
+ * notmuch database will reference the filename, and will not copy the
+ * entire contents of the file.
+ *
+ * If 'message' is not NULL, then, on successful return '*message'
+ * will be initialized to a message object that can be used for things
+ * such as adding tags to the just-added message. The user should call
+ * notmuch_message_destroy when done with the message. On any failure
+ * '*message' will be set to NULL.
*
* Return value:
*
const char *
notmuch_thread_get_subject (notmuch_thread_t *thread);
+/* Get the date of the oldest message in 'thread' as a time_t value.
+ */
+time_t
+notmuch_thread_get_oldest_date (notmuch_thread_t *thread);
+
+/* Get the date of the oldest message in 'thread' as a time_t value.
+ */
+time_t
+notmuch_thread_get_newest_date (notmuch_thread_t *thread);
+
/* Get the tags for 'thread', returning a notmuch_tags_t object which
* can be used to iterate over all tags.
*
/* Get the filename for the email corresponding to 'message'.
*
- * The returned filename is relative to the base of the database from
- * which 'message' was obtained. See notmuch_database_get_path() .
+ * 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). */
const char *
notmuch_message_get_filename (notmuch_message_t *message);
+/* Get the date of 'message' as a time_t value.
+ *
+ * For the original textual representation of the Date header from the
+ * message call notmuch_message_get_header() with a header value of
+ * "date". */
+time_t
+notmuch_message_get_date (notmuch_message_t *message);
+
+/* Get the size in bytes of the full header section of 'message'.
+ *
+ * This is useful in conjunction with notmuch_message_get_filename
+ * for separately parsing the message header and content.
+ *
+ * Returns 0 in the case of any error.
+ */
+size_t
+notmuch_message_get_header_size (notmuch_message_t *message);
+
+/* Get the value of the specified header from 'message'.
+ *
+ * The value will be read from the actual message file, not from the
+ * notmuch database. The header name is case insensitive.
+ *
+ * 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).
+ *
+ * Returns NULL if the message does not contain a header line matching
+ * 'header' of if any error occurs.
+ */
+const char *
+notmuch_message_get_header (notmuch_message_t *message, const char *header);
+
+/* Get the entire set of headers from an email message as a string.
+ *
+ * The value will be read from the actual message file, not from the
+ * notmuch database.
+ *
+ * The returned value is owned by the notmuch message and is valid
+ * only until the message is closed. The caller should copy it if
+ * needing to modify the value or to hold onto it for longer.
+ *
+ * Returns NULL in the case of any error.
+ */
+const char *
+notmuch_message_get_all_headers (notmuch_message_t *message);
+
/* Get the tags for 'message', returning a notmuch_tags_t object which
* can be used to iterate over all tags.
*