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,
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'.
*
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. */
*
* 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'.
* 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. */
const char *
notmuch_database_get_path (notmuch_database_t *database);
-/* Store a timestamp within 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.
+/* Read the stored contents of a directory from the database.
*
- * 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.
*
- * 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'.
const char *filename,
notmuch_message_t **message);
-/* Find a message with the given messsage_id.
+/* 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
* a new notmuch_message_t object is returned. The caller should call
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
/* Sort values for notmuch_query_set_sort */
typedef enum {
- NOTMUCH_SORT_DATE,
- NOTMUCH_SORT_DATE_REVERSE,
+ NOTMUCH_SORT_OLDEST_FIRST,
+ NOTMUCH_SORT_NEWEST_FIRST,
NOTMUCH_SORT_MESSAGE_ID
} notmuch_sort_t;
* object is owned by the query and as such, will only be valid until
* notmuch_query_destroy.
*
- * The 'first' and 'max_threads' arguments can be used to obtain
- * partial results from the search. For example, to get results 10 at
- * a time, pass 'max_threads' as 10 and for 'first' pass the values 0,
- * 10, 20, etc. As a special case, a value of -1 for 'max_threads'
- * indicates that no limiting is to be performed. So a search with
- * 'first' == 0 and 'max_threads' == -1 will return the complete
- * results of the search.
- *
* Typical usage might be:
*
* notmuch_query_t *query;
* to call it if the query is about to be destroyed).
*/
notmuch_threads_t *
-notmuch_query_search_threads (notmuch_query_t *query,
- int first, int max_threads);
+notmuch_query_search_threads (notmuch_query_t *query);
/* 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.
*
- * The 'first' and 'max_messages' arguments can be used to obtain
- * partial results from the search. For example, to get results 10 at
- * a time, pass 'max_messages' as 10 and for 'first' pass the values
- * 0, 10, 20, etc. As a special case, a value of -1 for 'max_messages'
- * indicates that no limiting is to be performed. So a search with
- * 'first' == 0 and 'max_messages' == -1 will return the complete
- * results of the search.
- *
* Typical usage might be:
*
* notmuch_query_t *query;
* reason to call it if the query is about to be destroyed).
*/
notmuch_messages_t *
-notmuch_query_search_messages (notmuch_query_t *query,
- int first, int max_messages);
+notmuch_query_search_messages (notmuch_query_t *query);
/* Destroy a notmuch_query_t along with any associated resources.
*
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
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
/* 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
const char *
notmuch_message_get_thread_id (notmuch_message_t *message);
-/* Get the filename for the email corresponding to '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 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_MESSAGE_FLAG_MATCH,
+} 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
/* 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.
/* 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
projects / notmuch / blobdiff