From de5e028d7dfa7e4b03d958ed0b6213f316c22107 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Mon, 20 Oct 2014 14:34:45 +0200 Subject: [PATCH] eldbus: update missing eldbus_message API documentation. --- src/lib/eldbus/eldbus_message.h | 77 +++++++++++++++++++++++--- src/lib/eldbus/eldbus_message_helper.h | 9 +++ 2 files changed, 77 insertions(+), 9 deletions(-) diff --git a/src/lib/eldbus/eldbus_message.h b/src/lib/eldbus/eldbus_message.h index 39bc41efa0..c3e3b8e5c9 100644 --- a/src/lib/eldbus/eldbus_message.h +++ b/src/lib/eldbus/eldbus_message.h @@ -10,6 +10,9 @@ /** * @brief Increase message reference. + * + * @param msg The Eldbus_Message object. + * @return The previous Eldbus_Message with incremented refcount. */ EAPI Eldbus_Message *eldbus_message_ref(Eldbus_Message *msg) EINA_ARG_NONNULL(1); @@ -18,14 +21,57 @@ EAPI Eldbus_Message *eldbus_message_ref(Eldbus_Message *msg) EINA_ARG_NON * * When refcount reaches zero the message and all its resources will be * freed. + * + * @param msg The Eldbus_Message object. */ EAPI void eldbus_message_unref(Eldbus_Message *msg) EINA_ARG_NONNULL(1); +/** + * Get the Eldbus message path. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message path. + */ EAPI const char *eldbus_message_path_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message interface. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message interface. + */ EAPI const char *eldbus_message_interface_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message member. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message member. + */ EAPI const char *eldbus_message_member_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message destination. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message destination. + */ EAPI const char *eldbus_message_destination_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message sender. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message sender. + */ EAPI const char *eldbus_message_sender_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message signature. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message signature. + */ EAPI const char *eldbus_message_signature_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** @@ -72,6 +118,7 @@ EAPI Eldbus_Message *eldbus_message_method_return_new(const Eldbus_Messag * desired. * @param text Variable in which to store the error text or @c NULL if it's not * desired. + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eldbus_message_error_get(const Eldbus_Message *msg, const char **name, const char **text) EINA_ARG_NONNULL(1); @@ -79,9 +126,9 @@ EAPI Eina_Bool eldbus_message_error_get(const Eldbus_Message *msg, c * @brief Get the arguments from an Eldbus_Message * * Get the arguments of an Eldbus_Message storing them in the locations pointed - * to by the pointer arguments that follow @param signature. Each pointer + * to by the pointer arguments that follow param signature. Each pointer * argument must be of a type that is appropriate for the correspondent complete - * type in @param signature. For complex types such as arrays, structs, + * type in param signature. For complex types such as arrays, structs, * dictionaries or variants, a pointer to Eldbus_Message_Iter* must be provided. * * @param msg The message to get the arguments from. @@ -98,7 +145,7 @@ EAPI Eina_Bool eldbus_message_arguments_get(const Eldbus_Message *ms * @brief Get the arguments from an Eldbus_Message using a va_list. * * @param msg The message to get the arguments from. - * @param signature The signature user is expecting to read from @param msg. + * @param signature The signature user is expecting to read from param msg. * @param ap The va_list containing the pointer arguments. * * @see eldbus_message_arguments_get() @@ -111,8 +158,8 @@ EAPI Eina_Bool eldbus_message_arguments_vget(const Eldbus_Message *m /** * @brief Append arguments into an Eldbus_Message * - * Append arguments into an Eldbus_Message according to the @param signature - * provided. For each complete type in @param signature, a value of the + * Append arguments into an Eldbus_Message according to the param signature + * provided. For each complete type in param signature, a value of the * corresponding type must be provided. * * This function supports only basic types. For complex types use @@ -120,7 +167,7 @@ EAPI Eina_Bool eldbus_message_arguments_vget(const Eldbus_Message *m * * @param msg The message in which arguments are being appended. * @param signature Signature of the arguments that are being appended. - * @param ... Values of each argument to append in @param msg. + * @param ... Values of each argument to append in param msg. * * @return EINA_TRUE on success, EINA_FALSE otherwise. */ @@ -183,6 +230,7 @@ EAPI Eina_Bool eldbus_message_iter_basic_append(Eldbus_Message_Ite * @param iter iterator in which data will be appended * @param signature signature of the contained data * @param ... values for each complete type + * @return EINA_TRUE on success, else EINA_FALSE * * @see eldbus_message_iter_container_new() * @see eldbus_message_iter_container_close() @@ -206,6 +254,7 @@ EAPI Eina_Bool eldbus_message_iter_arguments_append(Eldbus_Message * @param iter iterator * @param signature of data * @param ap va_list with the values + * @return EINA_TRUE on success, else EINA_FALSE * * @note This function don't support variant, use instead * eldbus_message_iter_container_new() to create the variant fill @@ -221,6 +270,7 @@ EAPI Eina_Bool eldbus_message_iter_arguments_vappend(Eldbus_Messag * @param type basic type that will be appended * @param array data to append * @param size of array + * @return EINA_TRUE on success, else EINA_FALSE */ EAPI Eina_Bool eldbus_message_iter_fixed_array_append(Eldbus_Message_Iter *iter, int type, const void *array, unsigned int size) EINA_ARG_NONNULL(1, 3); @@ -247,6 +297,9 @@ EAPI void eldbus_message_iter_basic_get(Eldbus_Message_Iter * /** * @brief Returns the current signature of a message iterator. * + * @param iter The iterator on which to query the signature. + * @return A string containing the message iterator signature. + * * @note The returned string must be freed. */ EAPI char *eldbus_message_iter_signature_get(Eldbus_Message_Iter *iter) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -265,14 +318,14 @@ EAPI Eina_Bool eldbus_message_iter_next(Eldbus_Message_Iter *iter) * Useful to iterate over arrays. * * @param iter iterator - * @param type of the next completed type in Iterator + * @param signature of the next completed type in Iterator * @param ... pointer of where data will be stored * - * @param if iterator was reach to end or if type different of the type that + * @return if iterator was reach to end or if type different of the type that * iterator points return EINA_FALSE * */ -EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Iter *iter, char type, ...) EINA_ARG_NONNULL(1, 2, 3); +EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Iter *iter, char signature, ...) EINA_ARG_NONNULL(1, 2, 3); /** * @brief Reads a block of fixed-length values from the message iterator. @@ -290,6 +343,12 @@ EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Ite * * Because the array is not copied, this function runs in constant time and is * fast; it's much preferred over walking the entire array with an iterator. + * + * @param iter The message iterator + * @param signature + * @param value + * @param n_elements + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eldbus_message_iter_fixed_array_get(Eldbus_Message_Iter *iter, int signature, void *value, int *n_elements) EINA_ARG_NONNULL(1, 3, 4); diff --git a/src/lib/eldbus/eldbus_message_helper.h b/src/lib/eldbus/eldbus_message_helper.h index 3009bc1301..584318267f 100644 --- a/src/lib/eldbus/eldbus_message_helper.h +++ b/src/lib/eldbus/eldbus_message_helper.h @@ -5,6 +5,15 @@ * @{ */ +/** + * @typedef Eldbus_Dict_Cb_Get + * + * Callback used when iterating over a dictionary. It is called at each entry iteration. + * + * @param data Context data passed to the callback. + * @param key Key parameter. + * @param var A message iterator on the current entry. + */ typedef void (*Eldbus_Dict_Cb_Get)(void *data, const void *key, Eldbus_Message_Iter *var); /**