lib: Consolidate checks for read-only database.

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 110061c29ae62d37e8df2b53038980d2e3a76cea..d03373044a2b800e6ac03d7922cd1355c8ebe75e 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -229,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,
@@ -252,6 +255,9 @@ 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,
@@ -789,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);
@@ -803,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);
@@ -811,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.
@@ -847,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
@@ -957,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,
@@ -996,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);
@@ -1004,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);
@@ -1018,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);