summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPierre Le Magourou <pierre.lemagourou@openwide.fr>2014-10-20 15:38:49 +0200
committerNicolas Aguirre <aguirre.nicolas@gmail.com>2014-10-20 16:54:56 +0200
commit211e62cab298774690a92618b4d33f4f702f60f3 (patch)
tree2ea4fa7a324b82058fa36d0826e3f33a3e67f009
parent8c5f81913ce789d90f004db88a95f6b8116ce1d4 (diff)
eldbus: Update missing eldbus_object API documentation.
-rw-r--r--src/lib/eldbus/eldbus_object.h109
1 files 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 @@
14 * @param conn connection where object belongs 14 * @param conn connection where object belongs
15 * @param bus name of bus or unique-id of who listens for calls of this object 15 * @param bus name of bus or unique-id of who listens for calls of this object
16 * @param path object path of this object 16 * @param path object path of this object
17 * @return The corresponding Eldbus_Object.
17 */ 18 */
18EAPI Eldbus_Object *eldbus_object_get(Eldbus_Connection *conn, const char *bus, const char *path) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; 19EAPI Eldbus_Object *eldbus_object_get(Eldbus_Connection *conn, const char *bus, const char *path) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT;
19 20
20/** 21/**
21 * @brief Increase object reference. 22 * @brief Increase object reference.
23 *
24 * @param obj An Eldbus_Object.
25 * @return The same Eldbus_Object with an increased refcount.
22 */ 26 */
23EAPI Eldbus_Object *eldbus_object_ref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); 27EAPI Eldbus_Object *eldbus_object_ref(Eldbus_Object *obj) EINA_ARG_NONNULL(1);
24 28
25/** 29/**
26 * @brief Decrease object reference. 30 * @brief Decrease object reference.
27 * If reference == 0 object will be freed and all its children. 31 * If reference == 0 object will be freed and all its children.
32 *
33 * @param obj An Eldbus_Object.
28 */ 34 */
29EAPI void eldbus_object_unref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); 35EAPI void eldbus_object_unref(Eldbus_Object *obj) EINA_ARG_NONNULL(1);
30 36
@@ -39,60 +45,128 @@ EAPI void eldbus_object_free_cb_add(Eldbus_Object *obj, Eldbus_Free_Cb
39 45
40/** 46/**
41 * @brief Remove callback registered in eldbus_object_free_cb_add(). 47 * @brief Remove callback registered in eldbus_object_free_cb_add().
48 *
49 * @param obj Object monitored.
50 * @param cb Callback that was registered.
51 * @param data Data that was passed to callback.
42 */ 52 */
43EAPI void eldbus_object_free_cb_del(Eldbus_Object *obj, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); 53EAPI void eldbus_object_free_cb_del(Eldbus_Object *obj, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2);
44 54
55/**
56 * @typedef Eldbus_Object_Event_Type
57 *
58 * An enumeration containing several Eldbus_Object event types.
59 */
45typedef enum 60typedef enum
46{ 61{
47 ELDBUS_OBJECT_EVENT_IFACE_ADDED = 0, /**< a parent path must have a ObjectManager interface */ 62 ELDBUS_OBJECT_EVENT_IFACE_ADDED = 0, /**< a parent path must have a ObjectManager interface */
48 ELDBUS_OBJECT_EVENT_IFACE_REMOVED, /**< a parent path must have a ObjectManager interface */ 63 ELDBUS_OBJECT_EVENT_IFACE_REMOVED, /**< a parent path must have a ObjectManager interface */
49 ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, 64 ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, /**< a property has changes */
50 ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, 65 ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, /**< a property was removed */
51 ELDBUS_OBJECT_EVENT_DEL, 66 ELDBUS_OBJECT_EVENT_DEL,
52 ELDBUS_OBJECT_EVENT_LAST /**< sentinel, not a real event type */ 67 ELDBUS_OBJECT_EVENT_LAST /**< sentinel, not a real event type */
53} Eldbus_Object_Event_Type; 68} Eldbus_Object_Event_Type;
54 69
70/**
71 * @typedef Eldbus_Object_Event_Interface_Added
72 *
73 * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_ADDED event.
74 */
55typedef struct _Eldbus_Object_Event_Interface_Added 75typedef struct _Eldbus_Object_Event_Interface_Added
56{ 76{
57 const char *interface; 77 const char *interface; /**< The interface name */
58 Eldbus_Proxy *proxy; 78 Eldbus_Proxy *proxy; /**< The proxy object */
59} Eldbus_Object_Event_Interface_Added; 79} Eldbus_Object_Event_Interface_Added;
60 80
81/**
82 * @typedef Eldbus_Object_Event_Interface_Removed
83 *
84 * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_REMOVED event.
85 */
61typedef struct _Eldbus_Object_Event_Interface_Removed 86typedef struct _Eldbus_Object_Event_Interface_Removed
62{ 87{
63 const char *interface; 88 const char *interface; /**< The interface name */
64} Eldbus_Object_Event_Interface_Removed; 89} Eldbus_Object_Event_Interface_Removed;
65 90
91/**
92 * @typedef Eldbus_Object_Event_Property_Changed
93 *
94 * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED event.
95 */
66typedef struct _Eldbus_Object_Event_Property_Changed 96typedef struct _Eldbus_Object_Event_Property_Changed
67{ 97{
68 const char *interface; 98 const char *interface; /**< The interface name */
69 Eldbus_Proxy *proxy; 99 Eldbus_Proxy *proxy; /**< The proxy object */
70 const char *name; 100 const char *name; /**< The name of the property */
71 const Eina_Value *value; 101 const Eina_Value *value; /**< The value of the property */
72} Eldbus_Object_Event_Property_Changed; 102} Eldbus_Object_Event_Property_Changed;
73 103
104/**
105 * @typedef Eldbus_Object_Event_Property_Removed
106 *
107 * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED event.
108 */
74typedef struct _Eldbus_Object_Event_Property_Removed 109typedef struct _Eldbus_Object_Event_Property_Removed
75{ 110{
76 const char *interface; 111 const char *interface; /**< The interface name */
77 Eldbus_Proxy *proxy; 112 Eldbus_Proxy *proxy; /**< The proxy object */
78 const char *name; 113 const char *name; /**< The name of the property */
79} Eldbus_Object_Event_Property_Removed; 114} Eldbus_Object_Event_Property_Removed;
80 115
116/**
117 * @typedef Eldbus_Object_Event_Cb
118 *
119 * Callback that will be called when an Eldbus_Object event happens.
120 *
121 * @param data Context data.
122 * @param obj The Eldbus_Object.
123 * @param event_info Information about the event that triggered the callback.
124 */
81typedef void (*Eldbus_Object_Event_Cb)(void *data, Eldbus_Object *obj, void *event_info); 125typedef void (*Eldbus_Object_Event_Cb)(void *data, Eldbus_Object *obj, void *event_info);
82 126
83/** 127/**
84 * @brief Add a callback function to be called when an event of the specified 128 * @brief Add a callback function to be called when an event of the specified
85 * type occurs. 129 * type occurs.
130 *
131 * @param obj The Eldbus_Object on which to register a callback.
132 * @param type The type of the event.
133 * @param cb The callback to call.
134 * @param cb_data The data to pass to the callback.
86 */ 135 */
87EAPI 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); 136EAPI 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);
88 137
89/** 138/**
90 * @brief Remove callback registered in eldbus_object_event_callback_add(). 139 * @brief Remove callback registered in eldbus_object_event_callback_add().
140 *
141 * @param obj The Eldbus_Object.
142 * @param type The type of the event.
143 * @param cb The callback to call.
144 * @param cb_data The data to pass to the callback.
91 */ 145 */
92EAPI 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); 146EAPI 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);
93 147
148/**
149 * Get the Eldbus_Connection object associated with a Eldbus_Object.
150 *
151 * @param obj The Eldbus_Object.
152 * @return The corresponding Eldbus_Connection object.
153 */
94EAPI Eldbus_Connection *eldbus_object_connection_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 154EAPI Eldbus_Connection *eldbus_object_connection_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
155
156/**
157 * Get the name associated with a Eldbus_Object.
158 *
159 * @param obj The Eldbus_Object.
160 * @return A string corresponding to the Eldbus_Object name.
161 */
95EAPI const char *eldbus_object_bus_name_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 162EAPI const char *eldbus_object_bus_name_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
163
164/**
165 * Get the path associated with a Eldbus_Object.
166 *
167 * @param obj The Eldbus_Object.
168 * @return A string corresponding to the Eldbus_Object path.
169 */
96EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 170EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
97 171
98/** 172/**
@@ -105,6 +179,7 @@ EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA
105 * @param cb_data data passed to callback 179 * @param cb_data data passed to callback
106 * @param timeout timeout in milliseconds, -1 to default internal value or 180 * @param timeout timeout in milliseconds, -1 to default internal value or
107 * ELDBUS_TIMEOUT_INFINITE for no timeout 181 * ELDBUS_TIMEOUT_INFINITE for no timeout
182 * @return A Eldbus_Pending object.
108 */ 183 */
109EAPI 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); 184EAPI 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);
110 185
@@ -116,9 +191,19 @@ EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Messag
116 * @param member name of the signal 191 * @param member name of the signal
117 * @param cb callback that will be called when this signal is received 192 * @param cb callback that will be called when this signal is received
118 * @param cb_data data that will be passed to callback 193 * @param cb_data data that will be passed to callback
194 * @return A listener to the desired signal.
119 */ 195 */
120EAPI 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); 196EAPI 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);
121 197
198/**
199 * @brief Call a dbus method on the Eldbus_Object.
200 *
201 * @param obj The Eldbus_Object on which to call the method.
202 * @param interface Interface name.
203 * @param member Name of the method to be called.
204 *
205 * @return a new Eldbus_Message, free with eldbus_message_unref()
206 */
122EAPI 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; 207EAPI 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;
123 208
124/** 209/**