From 321f6482cdb7bb13e4097cafe384b936eb6f4cd4 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Mon, 20 Oct 2014 15:38:49 +0200 Subject: [PATCH] eldbus: update missing eldbus_object API documentation. --- src/lib/eldbus/eldbus_object.h | 109 +++++++++++++++++++++++++++++---- 1 file changed, 97 insertions(+), 12 deletions(-) diff --git a/src/lib/eldbus/eldbus_object.h b/src/lib/eldbus/eldbus_object.h index 514b40ec0b..297cb0b0f3 100644 --- a/src/lib/eldbus/eldbus_object.h +++ b/src/lib/eldbus/eldbus_object.h @@ -14,17 +14,23 @@ * @param conn connection where object belongs * @param bus name of bus or unique-id of who listens for calls of this object * @param path object path of this object + * @return The corresponding Eldbus_Object. */ EAPI Eldbus_Object *eldbus_object_get(Eldbus_Connection *conn, const char *bus, const char *path) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; /** * @brief Increase object reference. + * + * @param obj An Eldbus_Object. + * @return The same Eldbus_Object with an increased refcount. */ EAPI Eldbus_Object *eldbus_object_ref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); /** * @brief Decrease object reference. * If reference == 0 object will be freed and all its children. + * + * @param obj An Eldbus_Object. */ EAPI void eldbus_object_unref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); @@ -39,60 +45,128 @@ EAPI void eldbus_object_free_cb_add(Eldbus_Object *obj, Eldbus_Free_Cb /** * @brief Remove callback registered in eldbus_object_free_cb_add(). + * + * @param obj Object monitored. + * @param cb Callback that was registered. + * @param data Data that was passed to callback. */ EAPI void eldbus_object_free_cb_del(Eldbus_Object *obj, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); +/** + * @typedef Eldbus_Object_Event_Type + * + * An enumeration containing several Eldbus_Object event types. + */ typedef enum { ELDBUS_OBJECT_EVENT_IFACE_ADDED = 0, /**< a parent path must have a ObjectManager interface */ ELDBUS_OBJECT_EVENT_IFACE_REMOVED, /**< a parent path must have a ObjectManager interface */ - ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, - ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, + ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, /**< a property has changes */ + ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, /**< a property was removed */ ELDBUS_OBJECT_EVENT_DEL, ELDBUS_OBJECT_EVENT_LAST /**< sentinel, not a real event type */ } Eldbus_Object_Event_Type; +/** + * @typedef Eldbus_Object_Event_Interface_Added + * + * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_ADDED event. + */ typedef struct _Eldbus_Object_Event_Interface_Added { - const char *interface; - Eldbus_Proxy *proxy; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ } Eldbus_Object_Event_Interface_Added; +/** + * @typedef Eldbus_Object_Event_Interface_Removed + * + * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_REMOVED event. + */ typedef struct _Eldbus_Object_Event_Interface_Removed { - const char *interface; + const char *interface; /**< The interface name */ } Eldbus_Object_Event_Interface_Removed; +/** + * @typedef Eldbus_Object_Event_Property_Changed + * + * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED event. + */ typedef struct _Eldbus_Object_Event_Property_Changed { - const char *interface; - Eldbus_Proxy *proxy; - const char *name; - const Eina_Value *value; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ + const char *name; /**< The name of the property */ + const Eina_Value *value; /**< The value of the property */ } Eldbus_Object_Event_Property_Changed; +/** + * @typedef Eldbus_Object_Event_Property_Removed + * + * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED event. + */ typedef struct _Eldbus_Object_Event_Property_Removed { - const char *interface; - Eldbus_Proxy *proxy; - const char *name; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ + const char *name; /**< The name of the property */ } Eldbus_Object_Event_Property_Removed; +/** + * @typedef Eldbus_Object_Event_Cb + * + * Callback that will be called when an Eldbus_Object event happens. + * + * @param data Context data. + * @param obj The Eldbus_Object. + * @param event_info Information about the event that triggered the callback. + */ typedef void (*Eldbus_Object_Event_Cb)(void *data, Eldbus_Object *obj, void *event_info); /** * @brief Add a callback function to be called when an event of the specified * type occurs. + * + * @param obj The Eldbus_Object on which to register a callback. + * @param type The type of the event. + * @param cb The callback to call. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_object_event_callback_add(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); /** * @brief Remove callback registered in eldbus_object_event_callback_add(). + * + * @param obj The Eldbus_Object. + * @param type The type of the event. + * @param cb The callback to call. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_object_event_callback_del(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); +/** + * Get the Eldbus_Connection object associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return The corresponding Eldbus_Connection object. + */ EAPI Eldbus_Connection *eldbus_object_connection_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the name associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return A string corresponding to the Eldbus_Object name. + */ EAPI const char *eldbus_object_bus_name_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the path associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return A string corresponding to the Eldbus_Object path. + */ EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** @@ -105,6 +179,7 @@ EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA * @param cb_data data passed to callback * @param timeout timeout in milliseconds, -1 to default internal value or * ELDBUS_TIMEOUT_INFINITE for no timeout + * @return A Eldbus_Pending object. */ EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); @@ -116,9 +191,19 @@ EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Messag * @param member name of the signal * @param cb callback that will be called when this signal is received * @param cb_data data that will be passed to callback + * @return A listener to the desired signal. */ EAPI Eldbus_Signal_Handler *eldbus_object_signal_handler_add(Eldbus_Object *obj, const char *interface, const char *member, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 4); +/** + * @brief Call a dbus method on the Eldbus_Object. + * + * @param obj The Eldbus_Object on which to call the method. + * @param interface Interface name. + * @param member Name of the method to be called. + * + * @return a new Eldbus_Message, free with eldbus_message_unref() + */ EAPI Eldbus_Message *eldbus_object_method_call_new(Eldbus_Object *obj, const char *interface, const char *member) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; /**