diff options
author | Carl Worth <cworth@cworth.org> | 2009-10-23 14:31:01 -0700 |
---|---|---|
committer | Carl Worth <cworth@cworth.org> | 2009-10-23 14:31:01 -0700 |
commit | 68a10091d6b2c29e996ee84040eecad487cb5e91 (patch) | |
tree | 1f3cfd152cf2ef0b505f933c02684cfcbca5e038 /notmuch.h | |
parent | 668f20bdfbaa5ae9caedd3f02017c5637e5e6ff7 (diff) |
Add notmuch_database_set_timestamp and notmuch_database_get_timestamp
These will be very helpful to implement an efficient "notmuch new"
command which imports new mail messages that have appeared.
Diffstat (limited to 'notmuch.h')
-rw-r--r-- | notmuch.h | 53 |
1 files changed, 53 insertions, 0 deletions
@@ -31,6 +31,8 @@ NOTMUCH_BEGIN_DECLS +#include <time.h> + #ifndef FALSE #define FALSE 0 #endif @@ -172,6 +174,57 @@ notmuch_database_default_path (void); 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. + * + * Return value: + * + * NOTMUCH_STATUS_SUCCESS: Timestamp successfully stored in database. + * + * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception + * occurred. Timestamp not stored. + */ +notmuch_status_t +notmuch_database_set_timestamp (notmuch_database_t *database, + const char *key, time_t timestamp); + +/* 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. + */ +time_t +notmuch_database_get_timestamp (notmuch_database_t *database, + const char *key); + /* Add a new message to the given notmuch database. * * Here,'filename' should be a path relative to the the path of |