DBusMessageIter: Clarify the API

Having opened a container for appending, the container must be closed
exactly once.

Signed-off-by: Simon McVittie <smcv@collabora.com>
Reviewed-by: Philip Withnall <withnall@endlessm.com>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=101568

2 files changed, 21 insertions, 3 deletions

diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c
index a3354f5d..9a42dbe1 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -2878,8 +2878,8 @@ dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
 }
 
 /**
- * Appends a container-typed value to the message; you are required to
- * append the contents of the container using the returned
+ * Appends a container-typed value to the message. On success, you are
+ * required to append the contents of the container using the returned
  * sub-iterator, and then call
  * dbus_message_iter_close_container(). Container types are for
  * example struct, variant, and array. For variants, the
@@ -2892,6 +2892,10 @@ dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
  * @todo If this fails due to lack of memory, the message is hosed and
  * you have to start over building the whole message.
  *
+ * If this function fails, the sub-iterator remains invalid, and must
+ * not be closed with dbus_message_iter_close_container() or abandoned
+ * with dbus_message_iter_abandon_container().
+ *
  * @param iter the append iterator
  * @param type the type of the value
  * @param contained_signature the type of container contents
@@ -2984,6 +2988,10 @@ dbus_message_iter_open_container (DBusMessageIter *iter,
  * container is written, and may free resources created by
  * dbus_message_iter_open_container().
  *
+ * Even if this function fails due to lack of memory, the sub-iterator sub
+ * has been closed and invalidated. It must not be closed again with this
+ * function, or abandoned with dbus_message_iter_abandon_container().
+ *
  * @todo If this fails due to lack of memory, the message is hosed and
  * you have to start over building the whole message.
  *
diff --git a/dbus/dbus-message.h b/dbus/dbus-message.h
index a4aeb5a1..993234de 100644
--- a/dbus/dbus-message.h
+++ b/dbus/dbus-message.h
@@ -42,7 +42,17 @@ DBUS_BEGIN_DECLS
  */
 
 typedef struct DBusMessage DBusMessage;
-/** Opaque type representing a message iterator. Can be copied by value, and contains no allocated memory so never needs to be freed and can be allocated on the stack. */
+/**
+ * Opaque type representing a message iterator. Can be copied by value and
+ * allocated on the stack.
+ *
+ * A DBusMessageIter usually contains no allocated memory. However, there
+ * is one special case: after a successful call to
+ * dbus_message_iter_open_container(), the caller is responsible for calling
+ * either dbus_message_iter_close_container() or
+ * dbus_message_iter_abandon_container() exactly once, with the same pair
+ * of iterators.
+ */
 typedef struct DBusMessageIter DBusMessageIter;
 
 /**