X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=e4f399291689d3d533a2aab90fe79d97159e41b8;hp=c1c7980aa06fe898e4a9697f9c8542b59b0d715d;hb=7a215c2de81e95798ecadd982eecf05e647c3988;hpb=305e76bc0ab2e7f3bd1ff2580e8d5dac8b4a7164

diff --git a/lib/notmuch.h b/lib/notmuch.h
index c1c7980a..e4f39929 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -86,6 +86,7 @@ typedef int notmuch_bool_t;
 typedef enum _notmuch_status {
     NOTMUCH_STATUS_SUCCESS = 0,
     NOTMUCH_STATUS_OUT_OF_MEMORY,
+    NOTMUCH_STATUS_READONLY_DATABASE,
     NOTMUCH_STATUS_XAPIAN_EXCEPTION,
     NOTMUCH_STATUS_FILE_ERROR,
     NOTMUCH_STATUS_FILE_NOT_EMAIL,
@@ -136,6 +137,11 @@ typedef struct _notmuch_tags notmuch_tags_t;
 notmuch_database_t *
 notmuch_database_create (const char *path);
 
+typedef enum {
+    NOTMUCH_DATABASE_MODE_READ_ONLY = 0,
+    NOTMUCH_DATABASE_MODE_READ_WRITE
+} notmuch_database_mode_t;
+
 /* XXX: I think I'd like this to take an extra argument of
  * notmuch_status_t* for returning a status value on failure. */
 
@@ -143,7 +149,9 @@ notmuch_database_create (const char *path);
  *
  * The database should have been created at some time in the past,
  * (not necessarily by this process), by calling
- * notmuch_database_create with 'path'.
+ * notmuch_database_create with 'path'. By default the database should be
+ * opened for reading only. In order to write to the database you need to
+ * pass the NOTMUCH_DATABASE_MODE_WRITABLE mode.
  *
  * An existing notmuch database can be identified by the presence of a
  * directory named ".notmuch" below 'path'.
@@ -155,7 +163,8 @@ notmuch_database_create (const char *path);
  * an error message on stderr).
  */
 notmuch_database_t *
-notmuch_database_open (const char *path);
+notmuch_database_open (const char *path,
+		       notmuch_database_mode_t mode);
 
 /* Close the given notmuch database, freeing all associated
  * resources. See notmuch_database_open. */
@@ -222,7 +231,7 @@ 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
+ * Here,'filename' 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'.
@@ -258,7 +267,7 @@ notmuch_database_add_message (notmuch_database_t *database,
 			      const char *filename,
 			      notmuch_message_t **message);
 
-/* Find a message with the given messsage_id.
+/* Find a message with the given message_id.
  *
  * If the database contains a message with the given message_id, then
  * a new notmuch_message_t object is returned. The caller should call
@@ -271,6 +280,16 @@ notmuch_message_t *
 notmuch_database_find_message (notmuch_database_t *database,
 			       const char *message_id);
 
+/* Return a list of all tags found in the database.
+ *
+ * This function creates a list of all tags found in the database. The
+ * resulting list contains all tags from all messages found in the database.
+ *
+ * On error this function returns NULL.
+ */
+notmuch_tags_t *
+notmuch_database_get_all_tags (notmuch_database_t *db);
+
 /* Create a new query for 'database'.
  *
  * Here, 'database' should be an open database, (see
@@ -299,8 +318,8 @@ notmuch_query_create (notmuch_database_t *database,
 
 /* Sort values for notmuch_query_set_sort */
 typedef enum {
-    NOTMUCH_SORT_DATE_OLDEST_FIRST,
-    NOTMUCH_SORT_DATE_NEWEST_FIRST,
+    NOTMUCH_SORT_OLDEST_FIRST,
+    NOTMUCH_SORT_NEWEST_FIRST,
     NOTMUCH_SORT_MESSAGE_ID
 } notmuch_sort_t;
 
@@ -441,6 +460,14 @@ notmuch_threads_advance (notmuch_threads_t *threads);
 void
 notmuch_threads_destroy (notmuch_threads_t *threads);
 
+/* Return an estimate of the number of messages matching a search
+ *
+ * This function performs a search and returns Xapian's best
+ * guess as to number of matching messages.
+ */
+unsigned
+notmuch_query_count_messages (notmuch_query_t *query);
+ 
 /* Get the thread ID of 'thread'.
  *
  * The returned string belongs to 'thread' and as such, should not be
@@ -451,6 +478,52 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
 const char *
 notmuch_thread_get_thread_id (notmuch_thread_t *thread);
 
+/* Get the total number of messages in 'thread'.
+ *
+ * This count consists of all messages in the database belonging to
+ * this thread. Contrast with notmuch_thread_get_matched_messages() .
+ */
+int
+notmuch_thread_get_total_messages (notmuch_thread_t *thread);
+
+/* Get a notmuch_messages_t iterator for the top-level messages in
+ * 'thread'.
+ *
+ * This iterator will not necessarily iterate over all of the messages
+ * in the thread. It will only iterate over the messages in the thread
+ * which are not replies to other messages in the thread.
+ *
+ * To iterate over all messages in the thread, the caller will need to
+ * iterate over the result of notmuch_message_get_replies for each
+ * top-level message (and do that recursively for the resulting
+ * messages, etc.).
+ */
+notmuch_messages_t *
+notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
+
+/* Get the number of messages in 'thread' that matched the search.
+ *
+ * This count includes only the messages in this thread that were
+ * matched by the search from which the thread was created. Contrast
+ * with notmuch_thread_get_total_messages() .
+ */
+int
+notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
+
+/* Get the authors of 'thread'
+ *
+ * The returned string is a comma-separated list of the names of the
+ * authors of mail messages in the query results that belong to this
+ * thread.
+ *
+ * The returned string belongs to 'thread' and as such, should not be
+ * modified by the caller and will only be valid for as long as the
+ * thread is valid, (which is until notmuch_thread_destroy or until
+ * the query from which it derived is destroyed).
+ */
+const char *
+notmuch_thread_get_authors (notmuch_thread_t *thread);
+
 /* Get the subject of 'thread'
  *
  * The subject is taken from the first message (according to the query
@@ -556,12 +629,27 @@ notmuch_messages_advance (notmuch_messages_t *messages);
 /* Destroy a notmuch_messages_t object.
  *
  * It's not strictly necessary to call this function. All memory from
- * the notmuch_messages_t object will be reclaimed when the containg
+ * the notmuch_messages_t object will be reclaimed when the containing
  * query object is destroyed.
  */
 void
 notmuch_messages_destroy (notmuch_messages_t *messages);
 
+/* Return a list of tags from all messages.
+ *
+ * The resulting list is guaranteed not to contain duplicated tags.
+ *
+ * WARNING: You can no longer iterate over messages after calling this
+ * function, because the iterator will point at the end of the list.
+ * We do not have a function to reset the iterator yet and the only
+ * way how you can iterate over the list again is to recreate the
+ * message list.
+ *
+ * The function returns NULL on error.
+ */
+notmuch_tags_t *
+notmuch_messages_collect_tags (notmuch_messages_t *messages);
+
 /* Get the message ID of 'message'.
  *
  * The returned string belongs to 'message' and as such, should not be
@@ -590,6 +678,26 @@ notmuch_message_get_message_id (notmuch_message_t *message);
 const char *
 notmuch_message_get_thread_id (notmuch_message_t *message);
 
+/* Get a notmuch_messages_t iterator for all of the replies to
+ * 'message'.
+ *
+ * Note: This call only makes sense if 'message' was ultimately
+ * obtained from a notmuch_thread_t object, (such as by coming
+ * directly from the result of calling notmuch_thread_get_
+ * toplevel_messages or by any number of subsequent
+ * calls to notmuch_message_get_replies).
+ *
+ * If 'message' was obtained through some non-thread means, (such as
+ * by a call to notmuch_query_search_messages), then this function
+ * will return NULL.
+ *
+ * If there are no replies to 'message', this function will return
+ * NULL. (Note that notmuch_messages_has_more will accept that NULL
+ * value as legitimate, and simply return FALSE for it.)
+ */
+notmuch_messages_t *
+notmuch_message_get_replies (notmuch_message_t *message);
+
 /* Get the filename for the email corresponding to 'message'.
  *
  * The returned filename is an absolute filename, (the initial
@@ -601,6 +709,21 @@ notmuch_message_get_thread_id (notmuch_message_t *message);
 const char *
 notmuch_message_get_filename (notmuch_message_t *message);
 
+/* Message flags */
+typedef enum _notmuch_message_flag {
+    NOTMUCH_MSG_FLAG_MATCHING_SEARCH,
+} notmuch_message_flag_t;
+
+/* Get a value of a flag for the email corresponding to 'message'. */
+notmuch_bool_t
+notmuch_message_get_flag (notmuch_message_t *message,
+			  notmuch_message_flag_t flag);
+
+/* Set a value of a flag for the email corresponding to 'message'. */
+void
+notmuch_message_set_flag (notmuch_message_t *message,
+			  notmuch_message_flag_t flag, notmuch_bool_t value);
+
 /* Get the date of 'message' as a time_t value.
  *
  * For the original textual representation of the Date header from the
@@ -618,8 +741,8 @@ notmuch_message_get_date  (notmuch_message_t *message);
  * 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.
+ * Returns an empty string ("") if the message does not contain a
+ * header line matching 'header'. Returns NULL if any error occurs.
  */
 const char *
 notmuch_message_get_header (notmuch_message_t *message, const char *header);
@@ -781,7 +904,7 @@ notmuch_tags_has_more (notmuch_tags_t *tags);
 /* Get the current tag from 'tags' as a string.
  *
  * Note: The returned string belongs to 'tags' and has a lifetime
- * identical to it (and the query to which it utlimately belongs).
+ * identical to it (and the query to which it ultimately belongs).
  *
  * See the documentation of notmuch_message_get_tags for example code
  * showing how to iterate over a notmuch_tags_t object.
@@ -800,7 +923,7 @@ notmuch_tags_advance (notmuch_tags_t *tags);
 /* Destroy a notmuch_tags_t object.
  *
  * It's not strictly necessary to call this function. All memory from
- * the notmuch_tags_t object will be reclaimed when the containg
+ * the notmuch_tags_t object will be reclaimed when the containing
  * message or query objects are destroyed.
  */
 void