* value. Instead we should map to things like DATABASE_LOCKED or
* whatever.
*
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: An attempt was made to write to
+ * a database opened in read-only mode.
+ *
* NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
*
* NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to read or
typedef enum _notmuch_status {
NOTMUCH_STATUS_SUCCESS = 0,
NOTMUCH_STATUS_OUT_OF_MEMORY,
- NOTMUCH_STATUS_READONLY_DATABASE,
+ NOTMUCH_STATUS_READ_ONLY_DATABASE,
NOTMUCH_STATUS_XAPIAN_EXCEPTION,
NOTMUCH_STATUS_FILE_ERROR,
NOTMUCH_STATUS_FILE_NOT_EMAIL,
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;
+typedef struct _notmuch_filenames notmuch_filenames_t;
/* Create a new, empty notmuch database located at 'path'.
*
* (not necessarily by this process), by calling
* 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.
+ * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.
*
* An existing notmuch database can be identified by the presence of a
* directory named ".notmuch" below 'path'.
const char *
notmuch_database_get_path (notmuch_database_t *database);
-/* Read the stored contents of a directory from the database.
+/* Return the database format version of the given database. */
+unsigned int
+notmuch_database_get_version (notmuch_database_t *database);
+
+/* Does this database need to be upgraded before writing to it?
*
- * 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'.
+ * If this function returns TRUE then no functions that modify the
+ * database (notmuch_database_add_message, notmuch_message_add_tag,
+ * notmuch_directory_set_mtime, etc.) will work unless the function
+ * notmuch_database_upgrade is called successfully first. */
+notmuch_bool_t
+notmuch_database_needs_upgrade (notmuch_database_t *database);
+
+/* Upgrade the current database.
*
- * 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.
+ * After opening a database in read-write mode, the client should
+ * check if an upgrade is needed (notmuch_database_needs_upgrade) and
+ * if so, upgrade with this function before making any modifications.
+ *
+ * The optional progress_notify callback can be used by the caller to
+ * provide progress indication to the user. If non-NULL it will be
+ * called periodically with 'progress' as a floating-point value in
+ * the range of [0.0 .. 1.0] indicating the progress made so far in
+ * the upgrade process.
*/
notmuch_status_t
-notmuch_database_read_directory (notmuch_database_t *database,
- const char *filename,
- notmuch_directory_t **directory);
-
-/* Return the recorded 'mtime' for the given directory
- */
-time_t
-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);
+notmuch_database_upgrade (notmuch_database_t *database,
+ void (*progress_notify) (void *closure,
+ double progress),
+ void *closure);
-/* 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.
+/* Retrieve a directory object from the database for 'path'.
+ *
+ * Here, 'path' should be a path relative to the path of 'database'
+ * (see notmuch_database_get_path), or else should be an absolute path
+ * with initial components that match the path of 'database'.
+ *
+ * Can return NULL if a Xapian exception occurs.
*/
-const char *
-notmuch_files_get_filename (notmuch_files_t *files);
+notmuch_directory_t *
+notmuch_database_get_directory (notmuch_database_t *database,
+ const char *path);
/* Add a new message to the given notmuch database.
*
*
* NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
*
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ * message not added.
+ *
* NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
- * ID as another message already in the database. Nothing added
- * to the database.
+ * ID as another message already in the database. The new
+ * filename was successfully added to the message in the database
+ * (if not already present).
*
* NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
* file, (such as permission denied, or file not found,
*
* NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look
* like an email message. Nothing added to the database.
+ *
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
+ * mode so no message can be added.
*/
notmuch_status_t
notmuch_database_add_message (notmuch_database_t *database,
/* 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.
+ * Note that 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.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
+ * message was removed from the database.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ * message not removed.
+ *
+ * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
+ * the message persists in the database with at least one other
+ * filename.
+ *
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
+ * mode so no message can be removed.
*/
notmuch_status_t
notmuch_database_remove_message (notmuch_database_t *database,
* a new notmuch_message_t object is returned. The caller should call
* notmuch_message_destroy when done with the message.
*
- * If no message is found with the given message_id or if an
- * out-of-memory situation occurs, this function returns NULL.
+ * This function returns NULL in the following situations:
+ *
+ * * No message is found with the given message_id
+ * * An out-of-memory situation occurs
+ * * A Xapian exception occurs
*/
notmuch_message_t *
notmuch_database_find_message (notmuch_database_t *database,
*
* http://xapian.org/docs/queryparser.html
*
- * As a special case, passing a length-zero string, (that is ""), will
+ * As a special case, passing either a length-zero string, (that is ""),
+ * or a string consisting of a single asterisk (that is "*"), will
* result in a query that returns all messages in the database.
*
- * See notmuch_query_set_sort for controlling the order of results and
- * notmuch_query_search to actually execute the query.
+ * See notmuch_query_set_sort for controlling the order of results.
+ * See notmuch_query_search_messages and notmuch_query_search_threads
+ * to actually execute the query.
*
* User should call notmuch_query_destroy when finished with this
* query.
typedef enum {
NOTMUCH_SORT_OLDEST_FIRST,
NOTMUCH_SORT_NEWEST_FIRST,
- NOTMUCH_SORT_MESSAGE_ID
+ NOTMUCH_SORT_MESSAGE_ID,
+ NOTMUCH_SORT_UNSORTED
} notmuch_sort_t;
/* Specify the sorting desired for this query. */
* query = notmuch_query_create (database, query_string);
*
* for (threads = notmuch_query_search_threads (query);
- * notmuch_threads_has_more (threads);
- * notmuch_threads_advance (threads))
+ * notmuch_threads_valid (threads);
+ * notmuch_threads_move_to_next (threads))
* {
* thread = notmuch_threads_get (threads);
* ....
* 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).
+ *
+ * If a Xapian exception occurs this function will return NULL.
*/
notmuch_threads_t *
notmuch_query_search_threads (notmuch_query_t *query);
* query = notmuch_query_create (database, query_string);
*
* for (messages = notmuch_query_search_messages (query);
- * notmuch_messages_has_more (messages);
- * notmuch_messages_advance (messages))
+ * notmuch_messages_valid (messages);
+ * notmuch_messages_move_to_next (messages))
* {
* message = notmuch_messages_get (messages);
* ....
* 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).
+ *
+ * If a Xapian exception occurs this function will return NULL.
*/
notmuch_messages_t *
notmuch_query_search_messages (notmuch_query_t *query);
*
* 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
+ * turn any notmuch_thread_t and notmuch_message_t objects generated
* from those results, etc.), if such objects haven't already been
* destroyed.
*/
void
notmuch_query_destroy (notmuch_query_t *query);
-/* Does the given notmuch_threads_t object contain any more
- * results.
+/* Is the given 'threads' iterator pointing at a valid thread.
*
- * When this function returns TRUE, notmuch_threads_get will
- * return a valid object. Whereas when this function returns FALSE,
+ * When this function returns TRUE, notmuch_threads_get will return a
+ * valid object. Whereas when this function returns FALSE,
* notmuch_threads_get will return NULL.
*
* See the documentation of notmuch_query_search_threads for example
* code showing how to iterate over a notmuch_threads_t object.
*/
notmuch_bool_t
-notmuch_threads_has_more (notmuch_threads_t *threads);
+notmuch_threads_valid (notmuch_threads_t *threads);
/* Get the current thread from 'threads' as a notmuch_thread_t.
*
notmuch_thread_t *
notmuch_threads_get (notmuch_threads_t *threads);
-/* Advance the 'threads' iterator to the next thread.
+/* Move the 'threads' iterator to the next thread.
+ *
+ * If 'threads' is already pointing at the last thread then the
+ * iterator will be moved to a point just beyond that last thread,
+ * (where notmuch_threads_valid will return FALSE and
+ * notmuch_threads_get will return NULL).
*
* See the documentation of notmuch_query_search_threads for example
* code showing how to iterate over a notmuch_threads_t object.
*/
void
-notmuch_threads_advance (notmuch_threads_t *threads);
+notmuch_threads_move_to_next (notmuch_threads_t *threads);
/* Destroy a notmuch_threads_t object.
*
*
* This function performs a search and returns Xapian's best
* guess as to number of matching messages.
+ *
+ * If a Xapian exception occurs, this function may return 0 (after
+ * printing a message).
*/
unsigned
notmuch_query_count_messages (notmuch_query_t *query);
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.
+/* Get the date of the newest message in 'thread' as a time_t value.
*/
time_t
notmuch_thread_get_newest_date (notmuch_thread_t *thread);
* thread = notmuch_threads_get (threads);
*
* for (tags = notmuch_thread_get_tags (thread);
- * notmuch_tags_has_more (tags);
- * notmuch_result_advance (tags))
+ * notmuch_tags_valid (tags);
+ * notmuch_result_move_to_next (tags))
* {
* tag = notmuch_tags_get (tags);
* ....
void
notmuch_thread_destroy (notmuch_thread_t *thread);
-/* Does the given notmuch_messages_t object contain any more
- * messages.
+/* Is the given 'messages' iterator pointing at a valid message.
*
* When this function returns TRUE, notmuch_messages_get will return a
* valid object. Whereas when this function returns FALSE,
* code showing how to iterate over a notmuch_messages_t object.
*/
notmuch_bool_t
-notmuch_messages_has_more (notmuch_messages_t *messages);
+notmuch_messages_valid (notmuch_messages_t *messages);
/* Get the current message from 'messages' as a notmuch_message_t.
*
notmuch_message_t *
notmuch_messages_get (notmuch_messages_t *messages);
-/* Advance the 'messages' iterator to the next result.
+/* Move the 'messages' iterator to the next message.
+ *
+ * If 'messages' is already pointing at the last message then the
+ * iterator will be moved to a point just beyond that last message,
+ * (where notmuch_messages_valid will return FALSE and
+ * notmuch_messages_get will return NULL).
*
* See the documentation of notmuch_query_search_messages for example
* code showing how to iterate over a notmuch_messages_t object.
*/
void
-notmuch_messages_advance (notmuch_messages_t *messages);
+notmuch_messages_move_to_next (notmuch_messages_t *messages);
/* Destroy a notmuch_messages_t object.
*
* 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
+ * NULL. (Note that notmuch_messages_valid will accept that NULL
* value as legitimate, and simply return FALSE for it.)
*/
notmuch_messages_t *
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,
* message = notmuch_database_find_message (database, message_id);
*
* for (tags = notmuch_message_get_tags (message);
- * notmuch_tags_has_more (tags);
- * notmuch_result_advance (tags))
+ * notmuch_tags_valid (tags);
+ * notmuch_result_move_to_next (tags))
* {
* tag = notmuch_tags_get (tags);
* ....
*
* NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
* (exceeds NOTMUCH_TAG_MAX)
+ *
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
+ * mode so message cannot be modified.
*/
notmuch_status_t
notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
*
* NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
* (exceeds NOTMUCH_TAG_MAX)
+ *
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
+ * mode so message cannot be modified.
*/
notmuch_status_t
notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
*
* See notmuch_message_freeze for an example showing how to safely
* replace tag values.
+ *
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
+ * mode so message cannot be modified.
*/
-void
+notmuch_status_t
notmuch_message_remove_all_tags (notmuch_message_t *message);
/* Freeze the current state of 'message' within the database.
* notmuch_message_remove_all_tags), will not be committed to the
* database until the message is thawed with notmuch_message_thaw.
*
- * Multiple calls to freeze/thaw are valid and these calls with
+ * Multiple calls to freeze/thaw are valid and these calls will
* "stack". That is there must be as many calls to thaw as to freeze
* before a message is actually thawed.
*
* notmuch_message_thaw (message);
*
* With freeze/thaw used like this, the message in the database is
- * guaranteed to have either the full set of original tag value, or
+ * guaranteed to have either the full set of original tag values, or
* the full set of new tag values, but nothing in between.
*
* Imagine the example above without freeze/thaw and the operation
* somehow getting interrupted. This could result in the message being
* left with no tags if the interruption happened after
* notmuch_message_remove_all_tags but before notmuch_message_add_tag.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Message successfully frozen.
+ *
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
+ * mode so message cannot be modified.
*/
-void
+notmuch_status_t
notmuch_message_freeze (notmuch_message_t *message);
/* Thaw the current 'message', synchronizing any changes that may have
* NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least
* its frozen count has successfully been reduced by 1).
*
- * NOTMUCH_STATUS_UNBALANCE_FREEZE_THAW: An attempt was made to thaw
+ * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw
* an unfrozen message. That is, there have been an unbalanced
* number of calls to notmuch_message_freeze and
* notmuch_message_thaw.
void
notmuch_message_destroy (notmuch_message_t *message);
-/* Does the given notmuch_tags_t object contain any more tags.
+/* Is the given 'tags' iterator pointing at a valid tag.
*
* When this function returns TRUE, notmuch_tags_get will return a
* valid string. Whereas when this function returns FALSE,
* showing how to iterate over a notmuch_tags_t object.
*/
notmuch_bool_t
-notmuch_tags_has_more (notmuch_tags_t *tags);
+notmuch_tags_valid (notmuch_tags_t *tags);
/* Get the current tag from 'tags' as a string.
*
const char *
notmuch_tags_get (notmuch_tags_t *tags);
-/* Advance the 'tags' iterator to the next tag.
+/* Move the 'tags' iterator to the next tag.
+ *
+ * If 'tags' is already pointing at the last tag then the iterator
+ * will be moved to a point just beyond that last tag, (where
+ * notmuch_tags_valid will return FALSE and notmuch_tags_get will
+ * return NULL).
*
* See the documentation of notmuch_message_get_tags for example code
* showing how to iterate over a notmuch_tags_t object.
*/
void
-notmuch_tags_advance (notmuch_tags_t *tags);
+notmuch_tags_move_to_next (notmuch_tags_t *tags);
/* Destroy a notmuch_tags_t object.
*
void
notmuch_tags_destroy (notmuch_tags_t *tags);
+/* Store an mtime within the database for 'directory'.
+ *
+ * The 'directory' should be an object retrieved from the database
+ * with notmuch_database_get_directory for a particular path.
+ *
+ * The intention is for the caller to use the mtime 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_directory_set_mtime with the mtime read from the
+ * filesystem.
+ *
+ * Then, when wanting to check for updates to the directory in the
+ * future, the client can call notmuch_directory_get_mtime 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_directory_get_mtime 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.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
+ * occurred, mtime not stored.
+ *
+ * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
+ * mode so directory mtime cannot be modified.
+ */
+notmuch_status_t
+notmuch_directory_set_mtime (notmuch_directory_t *directory,
+ time_t mtime);
+
+/* Get the mtime of a directory, (as previously stored with
+ * notmuch_directory_set_mtime).
+ *
+ * Returns 0 if no mtime has previously been stored for this
+ * directory.*/
+time_t
+notmuch_directory_get_mtime (notmuch_directory_t *directory);
+
+/* Get a notmuch_filenames_t iterator listing all the filenames of
+ * messages in the database within the given directory.
+ *
+ * The returned filenames will be the basename-entries only (not
+ * complete paths). */
+notmuch_filenames_t *
+notmuch_directory_get_child_files (notmuch_directory_t *directory);
+
+/* Get a notmuch_filenams_t iterator listing all the filenames of
+ * sub-directories in the database within the given directory.
+ *
+ * The returned filenames will be the basename-entries only (not
+ * complete paths). */
+notmuch_filenames_t *
+notmuch_directory_get_child_directories (notmuch_directory_t *directory);
+
+/* Destroy a notmuch_directory_t object. */
+void
+notmuch_directory_destroy (notmuch_directory_t *directory);
+
+/* Is the given 'filenames' iterator pointing at a valid filename.
+ *
+ * When this function returns TRUE, notmuch_filenames_get will return
+ * a valid string. Whereas when this function returns FALSE,
+ * notmuch_filenames_get will return NULL.
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will always return FALSE.
+ */
+notmuch_bool_t
+notmuch_filenames_valid (notmuch_filenames_t *filenames);
+
+/* Get the current filename from 'filenames' as a string.
+ *
+ * Note: The returned string belongs to 'filenames' and has a lifetime
+ * identical to it (and the directory to which it ultimately belongs).
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will always return NULL.
+ */
+const char *
+notmuch_filenames_get (notmuch_filenames_t *filenames);
+
+/* Move the 'filenames' iterator to the next filename.
+ *
+ * If 'filenames' is already pointing at the last filename then the
+ * iterator will be moved to a point just beyond that last filename,
+ * (where notmuch_filenames_valid will return FALSE and
+ * notmuch_filenames_get will return NULL).
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will do nothing.
+ */
+void
+notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);
+
+/* Destroy a notmuch_filenames_t object.
+ *
+ * It's not strictly necessary to call this function. All memory from
+ * the notmuch_filenames_t object will be reclaimed when the
+ * containing directory object is destroyed.
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will do nothing.
+ */
+void
+notmuch_filenames_destroy (notmuch_filenames_t *filenames);
+
NOTMUCH_END_DECLS
#endif
projects / notmuch / blobdiff