*
* 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,
* 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,
*
* 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);
*
* 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);
*
* 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.
* 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
*
* 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,
* 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);
*
* 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);
* 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);