X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.h;h=230c298e2af0384a6d7fb2f6c621fe997554eb56;hp=f4e59ab2ca47f47df30c81fba7323f3605b0033f;hb=d4c4318fb95ba2ed86823389cf82b11a2bcae073;hpb=203a717d64864411eb6802c06a5a0ad1cf98e077

diff --git a/notmuch.h b/notmuch.h
index f4e59ab2..230c298e 100644
--- a/notmuch.h
+++ b/notmuch.h
@@ -108,9 +108,9 @@ notmuch_status_to_string (notmuch_status_t status);
  * notmuch_<foo> functions below. */
 typedef struct _notmuch_database notmuch_database_t;
 typedef struct _notmuch_query notmuch_query_t;
-typedef struct _notmuch_thread_results notmuch_thread_results_t;
+typedef struct _notmuch_threads notmuch_threads_t;
 typedef struct _notmuch_thread notmuch_thread_t;
-typedef struct _notmuch_message_results notmuch_message_results_t;
+typedef struct _notmuch_messages notmuch_messages_t;
 typedef struct _notmuch_message notmuch_message_t;
 typedef struct _notmuch_tags notmuch_tags_t;
 
@@ -246,11 +246,14 @@ 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.
+ * '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
@@ -328,24 +331,24 @@ typedef enum {
 void
 notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
 
-/* Execute a query for threads, returning a notmuch_thread_results_t
- * object which can be used to iterate over the results. The results
+/* Execute a query for threads, returning a notmuch_threads_t object
+ * which can be used to iterate over the results. The returned threads
  * object is owned by the query and as such, will only be valid until
  * notmuch_query_destroy.
  *
  * Typical usage might be:
  *
  *     notmuch_query_t *query;
- *     notmuch_thread_results_t *results;
+ *     notmuch_threads_t *threads;
  *     notmuch_thread_t *thread;
  *
  *     query = notmuch_query_create (database, query_string);
  *
- *     for (results = notmuch_query_search_threads (query);
- *          notmuch_thread_results_has_more (results);
- *          notmuch_thread_results_advance (results))
+ *     for (threads = notmuch_query_search_threads (query);
+ *          notmuch_threads_has_more (threads);
+ *          notmuch_threads_advance (threads))
  *     {
- *         thread = notmuch_thread_results_get (results);
+ *         thread = notmuch_threads_get (threads);
  *         ....
  *         notmuch_thread_destroy (thread);
  *     }
@@ -360,31 +363,31 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  * destroyed.
  *
  * Note that there's no explicit destructor needed for the
- * notmuch_thread_results_t object. (For consistency, we do provide a
- * notmuch_thread_results_destroy function, but there's no good reason
+ * notmuch_threads_t object. (For consistency, we do provide a
+ * notmuch_threads_destroy function, but there's no good reason
  * to call it if the query is about to be destroyed).
  */
-notmuch_thread_results_t *
+notmuch_threads_t *
 notmuch_query_search_threads (notmuch_query_t *query);
 
-/* Execute a query for messages, returning a notmuch_message_results_t
- * object which can be used to iterate over the results. The results
- * object is owned by the query and as such, will only be valid until
- * notmuch_query_destroy.
+/* Execute a query for messages, returning a notmuch_messages_t object
+ * which can be used to iterate over the results. The returned
+ * messages object is owned by the query and as such, will only be
+ * valid until notmuch_query_destroy.
  *
  * Typical usage might be:
  *
  *     notmuch_query_t *query;
- *     notmuch_message_results_t *results;
+ *     notmuch_messages_t *messages;
  *     notmuch_message_t *message;
  *
  *     query = notmuch_query_create (database, query_string);
  *
- *     for (results = notmuch_query_search_messages (query);
- *          notmuch_message_results_has_more (results);
- *          notmuch_message_results_advance (results))
+ *     for (messages = notmuch_query_search_messages (query);
+ *          notmuch_messages_has_more (messages);
+ *          notmuch_messages_advance (messages))
  *     {
- *         message = notmuch_message_results_get (results);
+ *         message = notmuch_messages_get (messages);
  *         ....
  *         notmuch_message_destroy (message);
  *     }
@@ -399,17 +402,17 @@ notmuch_query_search_threads (notmuch_query_t *query);
  * when the query is destroyed.
  *
  * Note that there's no explicit destructor needed for the
- * notmuch_message_results_t object. (For consistency, we do provide a
- * notmuch_message_results_destroy function, but there's no good
+ * notmuch_messages_t object. (For consistency, we do provide a
+ * notmuch_messages_destroy function, but there's no good
  * reason to call it if the query is about to be destroyed).
  */
-notmuch_message_results_t *
+notmuch_messages_t *
 notmuch_query_search_messages (notmuch_query_t *query);
 
 /* Destroy a notmuch_query_t along with any associated resources.
  *
- * This will in turn destroy any notmuch_thread_results_t and
- * notmuch_message_results_t objects generated by this query, (and in
+ * This will in turn destroy any notmuch_threads_t and
+ * notmuch_messages_t objects generated by this query, (and in
  * turn any notmuch_thrad_t and notmuch_message_t objects generated
  * from those results, etc.), if such objects haven't already been
  * destroyed.
@@ -417,49 +420,49 @@ notmuch_query_search_messages (notmuch_query_t *query);
 void
 notmuch_query_destroy (notmuch_query_t *query);
 
-/* Does the given notmuch_thread_results_t object contain any more
+/* Does the given notmuch_threads_t object contain any more
  * results.
  *
- * When this function returns TRUE, notmuch_thread_results_get will
+ * When this function returns TRUE, notmuch_threads_get will
  * return a valid object. Whereas when this function returns FALSE,
- * notmuch_thread_results_get will return NULL.
+ * notmuch_threads_get will return NULL.
  *
  * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_thread_results_t object.
+ * code showing how to iterate over a notmuch_threads_t object.
  */
 notmuch_bool_t
-notmuch_thread_results_has_more (notmuch_thread_results_t *results);
+notmuch_threads_has_more (notmuch_threads_t *threads);
 
-/* Get the current result from 'results' as a notmuch_thread_t.
+/* Get the current thread from 'threads' as a notmuch_thread_t.
  *
- * Note: The returned thread belongs to 'results' and has a lifetime
+ * Note: The returned thread belongs to 'threads' and has a lifetime
  * identical to it (and the query to which it belongs).
  *
  * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_thread_results_t object.
+ * code showing how to iterate over a notmuch_threads_t object.
  *
  * If an out-of-memory situation occurs, this function will return
  * NULL.
  */
 notmuch_thread_t *
-notmuch_thread_results_get (notmuch_thread_results_t *results);
+notmuch_threads_get (notmuch_threads_t *threads);
 
-/* Advance the 'results' iterator to the next result.
+/* Advance the 'threads' iterator to the next thread.
  *
  * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_thread_results_t object.
+ * code showing how to iterate over a notmuch_threads_t object.
  */
 void
-notmuch_thread_results_advance (notmuch_thread_results_t *results);
+notmuch_threads_advance (notmuch_threads_t *threads);
 
-/* Destroy a notmuch_thread_results_t object.
+/* Destroy a notmuch_threads_t object.
  *
  * It's not strictly necessary to call this function. All memory from
- * the notmuch_thread_results_t object will be reclaimed when the
+ * the notmuch_threads_t object will be reclaimed when the
  * containg query object is destroyed.
  */
 void
-notmuch_thread_results_destroy (notmuch_thread_results_t *results);
+notmuch_threads_destroy (notmuch_threads_t *threads);
 
 /* Get the thread ID of 'thread'.
  *
@@ -485,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.
  *
@@ -504,7 +517,7 @@ notmuch_thread_get_subject (notmuch_thread_t *thread);
  *     notmuch_tags_t *tags;
  *     const char *tag;
  *
- *     thread = notmuch_thread_results_get (thread_results);
+ *     thread = notmuch_threads_get (threads);
  *
  *     for (tags = notmuch_thread_get_tags (thread);
  *          notmuch_tags_has_more (tags);
@@ -528,52 +541,49 @@ notmuch_thread_get_tags (notmuch_thread_t *thread);
 void
 notmuch_thread_destroy (notmuch_thread_t *thread);
 
-/* Does the given notmuch_message_results_t object contain any more
- * results.
+/* Does the given notmuch_messages_t object contain any more
+ * messages.
  *
- * When this function returns TRUE, notmuch_message_results_get will
- * return a valid object. Whereas when this function returns FALSE,
- * notmuch_message_results_get will return NULL.
+ * When this function returns TRUE, notmuch_messages_get will return a
+ * valid object. Whereas when this function returns FALSE,
+ * notmuch_messages_get will return NULL.
  *
  * See the documentation of notmuch_query_search_messages for example
- * code showing how to iterate over a notmuch_message_results_t
- * object.
+ * code showing how to iterate over a notmuch_messages_t object.
  */
 notmuch_bool_t
-notmuch_message_results_has_more (notmuch_message_results_t *results);
+notmuch_messages_has_more (notmuch_messages_t *messages);
 
-/* Get the current result from 'results' as a notmuch_message_t.
+/* Get the current message from 'messages' as a notmuch_message_t.
  *
- * Note: The returned message belongs to 'results' and has a lifetime
+ * Note: The returned message belongs to 'messages' and has a lifetime
  * identical to it (and the query to which it belongs).
  *
  * See the documentation of notmuch_query_search_messages for example
- * code showing how to iterate over a notmuch_message_results_t
- * object.
+ * code showing how to iterate over a notmuch_messages_t object.
  *
  * If an out-of-memory situation occurs, this function will return
  * NULL.
  */
 notmuch_message_t *
-notmuch_message_results_get (notmuch_message_results_t *results);
+notmuch_messages_get (notmuch_messages_t *messages);
 
-/* Advance the 'results' iterator to the next result.
+/* Advance the 'messages' iterator to the next result.
  *
  * See the documentation of notmuch_query_search_messages for example
- * code showing how to iterate over a notmuch_message_results_t
- * object.
+ * code showing how to iterate over a notmuch_messages_t object.
  */
 void
-notmuch_message_results_advance (notmuch_message_results_t *results);
+notmuch_messages_advance (notmuch_messages_t *messages);
 
-/* Destroy a notmuch_message_results_t object.
+/* Destroy a notmuch_messages_t object.
  *
  * It's not strictly necessary to call this function. All memory from
- * the notmuch_message_results_t object will be reclaimed when the
- * containg query object is destroyed.
+ * the notmuch_messages_t object will be reclaimed when the containg
+ * query object is destroyed.
  */
 void
-notmuch_message_results_destroy (notmuch_message_results_t *results);
+notmuch_messages_destroy (notmuch_messages_t *messages);
 
 /* Get the message ID of 'message'.
  *
@@ -605,14 +615,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.
  *