X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=lib%2Fnotmuch.h;h=d03373044a2b800e6ac03d7922cd1355c8ebe75e;hb=f93b7218c3e2d11c5b3cdd4c367a42ca7a7ede77;hp=13efd5db90b77e1cb1b49473665715423842cde8;hpb=ba07fe1819b59c9ecf7041834699d8959a604828;p=notmuch diff --git a/lib/notmuch.h b/lib/notmuch.h index 13efd5db..d0337304 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -57,6 +57,9 @@ typedef int notmuch_bool_t; * value. Instead we should map to things like DATABASE_LOCKED or * whatever. * + * NOTMUCH_STATUS_READONLY_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 @@ -217,8 +220,8 @@ notmuch_database_get_directory (notmuch_database_t *database, * NOTMUCH_STATUS_SUCCESS: Message successfully added to database. * * 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. * * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the * file, (such as permission denied, or file not found, @@ -226,6 +229,9 @@ notmuch_database_get_directory (notmuch_database_t *database, * * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look * like an email message. Nothing added to the database. + * + * NOTMUCH_STATUS_READONLY_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, @@ -234,12 +240,24 @@ 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_DUPLICATE_MESSAGE_ID: This filename was removed but + * the message persists in the database with at least one other + * filename. + * + * NOTMUCH_STATUS_READONLY_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, @@ -777,6 +795,9 @@ notmuch_message_get_tags (notmuch_message_t *message); * * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long * (exceeds NOTMUCH_TAG_MAX) + * + * NOTMUCH_STATUS_READONLY_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); @@ -791,6 +812,9 @@ 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_READONLY_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); @@ -799,8 +823,11 @@ 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_READONLY_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. @@ -835,8 +862,15 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * 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_READONLY_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 @@ -945,6 +979,9 @@ notmuch_tags_destroy (notmuch_tags_t *tags); * * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception * occurred, mtime not stored. + * + * NOTMUCH_STATUS_READONLY_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, @@ -984,6 +1021,9 @@ notmuch_directory_destroy (notmuch_directory_t *directory); * 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_has_more (notmuch_filenames_t *filenames); @@ -992,11 +1032,17 @@ notmuch_filenames_has_more (notmuch_filenames_t *filenames); * * 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); /* Advance the 'filenames' iterator to the next filename. + * + * It is acceptable to pass NULL for 'filenames', in which case this + * function will do nothing. */ void notmuch_filenames_advance (notmuch_filenames_t *filenames); @@ -1006,6 +1052,9 @@ notmuch_filenames_advance (notmuch_filenames_t *filenames); * 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);