Add notmuch_message_add_tag and notmuch_message_remove_tag

[notmuch] / notmuch.h

diff --git a/notmuch.h b/notmuch.h
index 3b4f980d0c25c4bc2b8db2a2c632150c2b36b68d..02c743aa60b192ffd398d94a0b027006957c3910 100644 (file)
--- a/notmuch.h
+++ b/notmuch.h
@@ -53,11 +53,23 @@ typedef int notmuch_bool_t;
  *
  * NOTMUCH_STATUS_FILE_NOT_EMAIL: A file was presented that doesn't
  *     appear to be an email message.
+ *
+ * NOTMUCH_STATUS_NULL_POINTER: The user erroneously passed a NULL
+ *     pointer to a notmuch function.
+ *
+ * NOTMUCH_STATUS_TAG_TOO_LONG: A tag value is too long.
+ *
+ * NOTMUCH_STATUS_LAST_STATUS: Not an actual status value. Just a way
+ *     to find out how many valid status values there are.
  */
 typedef enum _notmuch_status {
     NOTMUCH_STATUS_SUCCESS = 0,
     NOTMUCH_STATUS_XAPIAN_EXCEPTION,
-    NOTMUCH_STATUS_FILE_NOT_EMAIL
+    NOTMUCH_STATUS_FILE_NOT_EMAIL,
+    NOTMUCH_STATUS_NULL_POINTER,
+    NOTMUCH_STATUS_TAG_TOO_LONG,
+
+    NOTMUCH_STATUS_LAST_STATUS
 } notmuch_status_t;
 
 /* Various opaque data types. For each notmuch_<foo>_t see the various
@@ -231,17 +243,22 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  *     {
  *         message = notmuch_results_get (results);
  *         ....
+ *         notmuch_message_destroy (message);
  *     }
  *
  *     notmuch_query_destroy (query);
  *
- * Note that there's no explicit destructor needed for the
- * notmuch_results_t object.
+ * Note: If you are finished with a message before its containing
+ * query, you can call notmuch_message_destroy to clean up some memory
+ * sooner (as in the above example). Otherwise, if your message
+ * objects are long-lived, then you don't need to call
+ * notmuch_message_destroy and all the memory will still be reclaimed
+ * when the query is destroyed.
  *
- * (For consistency, we do provide a notmuch_results_destroy function,
- * but there's no point in calling it if you're about to destroy the
- * query object as well too---either call will free all the memory of
- * the results).
+ * Note that there's no explicit destructor needed for the
+ * notmuch_results_t object. (For consistency, we do provide a
+ * notmuch_results_destroy function, but there's no good reason to
+ * call it if the query is about to be destroyed).
  */
 notmuch_results_t *
 notmuch_query_search (notmuch_query_t *query);
@@ -371,6 +388,37 @@ notmuch_message_get_tags (notmuch_message_t *message);
 notmuch_thread_ids_t *
 notmuch_message_get_thread_ids (notmuch_message_t *message);
 
+/* The longest possible tag value. */
+#define NOTMUCH_TAG_MAX 200
+
+/* Add a tag to the given message.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message
+ *
+ * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
+ *
+ * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is longer than
+ *     too long (exceeds NOTMUCH_TAG_MAX)
+ */
+notmuch_status_t
+notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
+
+/* Remove a tag from the given message.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message
+ *
+ * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
+ *
+ * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is longer than
+ *     too long (exceeds NOTMUCH_TAG_MAX)
+ */
+notmuch_status_t
+notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
+
 /* Destroy a notmuch_message_t object.
  *
  * It can be useful to call this function in the case of a single