From 46fa24cd3bfea1138bb756d0e056e258d23ff1e2 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 4 Jul 2017 15:58:50 +0100 Subject: [PATCH 13/19] DBusMessageIter: Clarify the API Having opened a container for appending, the container must be closed exactly once. Signed-off-by: Simon McVittie --- dbus/dbus-message.c | 12 ++++++++++-- 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 119d8ac4..adde30bd 100644 --- a/dbus/dbus-message.c +++ b/dbus/dbus-message.c @@ -2875,8 +2875,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 @@ -2889,6 +2889,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 @@ -2981,6 +2985,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; /** -- 2.13.2