notmuch search: Add (relative) date to search output

[notmuch] / notmuch.h

diff --git a/notmuch.h b/notmuch.h
index 7e83d23941be6e9309e63b0edeed25f83da29640..a3608ba0dfcc03e0e8701192c57d4eab7199c165 100644 (file)
--- a/notmuch.h
+++ b/notmuch.h
@@ -246,16 +246,20 @@ notmuch_database_get_timestamp (notmuch_database_t *database,
 /* 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:
  *
@@ -484,6 +488,16 @@ notmuch_thread_get_thread_id (notmuch_thread_t *thread);
 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.
  *
@@ -604,14 +618,62 @@ notmuch_message_get_thread_id (notmuch_message_t *message);
 
 /* 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.
  *