diff options
Diffstat (limited to 'dbus')
-rw-r--r-- | dbus/dbus-message.c | 12 | ||||
-rw-r--r-- | dbus/dbus-message.h | 12 |
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; /** |