aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eldbus/eldbus_proxy.h
blob: b010aeec7879075333d4772d18f98c6127b84441 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
#ifndef ELDBUS_PROXY_H
#define ELDBUS_PROXY_H 1

/**
 * @defgroup Eldbus_Proxy Proxy
 * @ingroup Eldbus
 *
 * @{
 */

/**
 * @brief Get a proxy of the following interface name in a Eldbus_Object.
 *
 * @param obj The Eldbus_Object on which to do the query.
 * @param interface The interface name of the proxy.
 * @return The corresponding Eldbus_Proxy object.
 */
EAPI Eldbus_Proxy          *eldbus_proxy_get(Eldbus_Object *obj, const char *interface) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Increase proxy reference.
 *
 * @param proxy The Eldbus_Proxy on which to increase the refcount.
 * @return The Eldbus_Proxy with an increased refcount.
 */
EAPI Eldbus_Proxy          *eldbus_proxy_ref(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1);

/**
 * @brief Decrease proxy reference.
 * If reference == 0 proxy will be freed and all your children.
 *
 * @param proxy The Eldbus_Proxy on which to decrease the refcount.
 */
EAPI void                  eldbus_proxy_unref(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1);

/**
 * @brief Get the Eldbus_Object associated with a proxy object.
 *
 * @param proxy The Eldbus_Proxy on which to do the query.
 * @return The corresponding Eldbus_Object.
 */
EAPI Eldbus_Object         *eldbus_proxy_object_get(const Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Get the interface name associated with a proxy object.
 *
 * @param proxy The Eldbus_Proxy on which to do the query.
 * @return The string corresponding to the interface name.
 */
EAPI const char           *eldbus_proxy_interface_get(const Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Set data to an Eldbus_Proxy object.
 *
 * @param proxy The Eldbus_Proxy on which to set the data.
 * @param key A string to which the data will be associated.
 * @param data The data to set to the proxy object.
 */
EAPI void                  eldbus_proxy_data_set(Eldbus_Proxy *proxy, const char *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);

/**
 * @brief Get data of an Eldbus_Proxy object.
 *
 * @param proxy The Eldbus_Proxy on which to get the data.
 * @param key The string to which the data is associated.
 * @return The data set to the proxy object associated with the provided key.
 */
EAPI void                 *eldbus_proxy_data_get(const Eldbus_Proxy *proxy, const char *key) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Delete data of an Eldbus_Proxy object.
 *
 * @param proxy The Eldbus_Proxy on which to delete the data.
 * @param key The string to which the data is associated.
 */
EAPI void                 *eldbus_proxy_data_del(Eldbus_Proxy *proxy, const char *key) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Add a callback function to be called when an event of the
 * type passed occurs.
 *
 * @param proxy The Eldbus_Proxy on which to add the callback.
 * @param cb The callback to add.
 * @param data The data to pass to the callback.
 */
EAPI void                  eldbus_proxy_free_cb_add(Eldbus_Proxy *proxy, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Remove callback registered in eldbus_proxy_free_cb_add().
 *
 * @param proxy The Eldbus_Proxy on which to delete the callback.
 * @param cb The callback to delete.
 * @param data The data passed to the callback.
 */
EAPI void                  eldbus_proxy_free_cb_del(Eldbus_Proxy *proxy, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Constructs a new message to invoke a method on a remote interface.
 *
 * @param proxy The Eldbus_Proxy on which to call the method.
 * @param member The name of the method to invoke.
 * @return An Eldbus_Message object.
 */
EAPI Eldbus_Message        *eldbus_proxy_method_call_new(Eldbus_Proxy *proxy, const char *member) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Send a message.
 *
 * @param proxy the msg will be send in connection that proxy belongs
 * @param msg message that will be send
 * @param cb if msg is a method call a callback should be passed
 * @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 on the sent message.
 */
EAPI Eldbus_Pending        *eldbus_proxy_send(Eldbus_Proxy *proxy, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Send a message and block while waiting for the reply.
 *
 * @param proxy the msg will be send in connection that proxy belongs
 * @param msg message that will be send
 * @param timeout timeout in milliseconds, -1 to default internal value or
 * ELDBUS_TIMEOUT_INFINITE for no timeout
 *
 * @return The reply message, error message or NULL.
 * The returned Eldbus_Message need to be unref after read.
 * @since 1.13
 */
EAPI Eldbus_Message        *eldbus_proxy_send_and_block(Eldbus_Proxy *proxy, Eldbus_Message *msg, double timeout) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Call a method in proxy.
 * Send a method call to interface that proxy belong with data.
 *
 * @param proxy
 * @param member method name
 * @param cb if msg is a method call a callback should be passed
 * to be execute when response arrive
 * @param cb_data data passed to callback
 * @param timeout timeout in milliseconds, -1 to default internal value or
 * ELDBUS_TIMEOUT_INFINITE for no timeout
 * @param signature of data that will be send
 * @param ... data value
 * @return A Eldbus_Pending object on the sent message.
 *
 * @note This function only support basic type to complex types use
 * eldbus_message_iter_* functions.
 */
EAPI Eldbus_Pending        *eldbus_proxy_call(Eldbus_Proxy *proxy, const char *member, Eldbus_Message_Cb cb, const void *cb_data, double timeout, const char *signature, ...) EINA_ARG_NONNULL(1, 2, 6);

/**
 * @brief Call a method in proxy.
 * Send a method call to interface that proxy belong with data.
 *
 * @param proxy
 * @param member method name
 * @param cb callback that will be called when response arrive.
 * @param cb_data data passed to callback
 * @param timeout timeout in milliseconds, -1 to default internal value or
 * ELDBUS_TIMEOUT_INFINITE for no timeout
 * @param signature of data that will be send
 * @param ap va_list of data value
 * @return A Eldbus_Pending object on the sent message.
 *
 * @note This function only support basic type to complex types use
 * eldbus_message_iter_* functions.
 */
EAPI Eldbus_Pending        *eldbus_proxy_vcall(Eldbus_Proxy *proxy, const char *member, Eldbus_Message_Cb cb, const void *cb_data, double timeout, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2, 6);

/**
 * @brief Add a signal handler.
 *
 * @param proxy interface where the signal is emitted
 * @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_proxy_signal_handler_add(Eldbus_Proxy *proxy, const char *member, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3);

/**
 * @typedef Eldbus_Proxy_Event_Type
 *
 * An enumeration containing proxy event types.
 */
typedef enum
{
   ELDBUS_PROXY_EVENT_PROPERTY_CHANGED = 0, /**< a property has changed */
   ELDBUS_PROXY_EVENT_PROPERTY_REMOVED, /**< a property was removed */
   ELDBUS_PROXY_EVENT_DEL,
   ELDBUS_PROXY_EVENT_PROPERTY_LOADED,
   ELDBUS_PROXY_EVENT_LAST    /**< sentinel, not a real event type */
} Eldbus_Proxy_Event_Type;

/**
 * @typedef Eldbus_Proxy_Event_Property_Changed
 *
 * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_CHANGED event is received.
 */
typedef struct _Eldbus_Proxy_Event_Property_Changed
{
   const char       *name; /**< the name of the property */
   const Eldbus_Proxy *proxy; /**< the proxy object */
   const Eina_Value *value; /**< the value of the property */
} Eldbus_Proxy_Event_Property_Changed;

/**
 * @typedef Eldbus_Proxy_Event_Property_Loaded
 *
 * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_LOADED event is received.
 */
typedef struct _Eldbus_Proxy_Event_Property_Loaded
{
   const Eldbus_Proxy *proxy; /**< the proxy object */
} Eldbus_Proxy_Event_Property_Loaded;

/**
 * @typedef Eldbus_Proxy_Event_Property_Removed
 *
 * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_REMOVED event is received.
 */
typedef struct _Eldbus_Proxy_Event_Property_Removed
{
   const char  *interface; /**< interface name */
   const Eldbus_Proxy *proxy; /**< the proxy object */
   const char  *name; /**< the name of the property */
} Eldbus_Proxy_Event_Property_Removed;

/**
 * @typedef Eldbus_Proxy_Event_Cb
 *
 * A callback called when an event occurs.
 * @param data The data passed by the caller.
 * @param proxy The Eldbus_Proxy object.
 * @param event_info Information on the event that triggered the callback.
 */
typedef void (*Eldbus_Proxy_Event_Cb)(void *data, Eldbus_Proxy *proxy, void *event_info);

/**
 * @brief Add a callback function to be called when occurs a event of the
 * type passed.
 *
 * @param proxy The Eldbus_Proxy object.
 * @param type The type of the event to register an callback on.
 * @param cb The callback function to register.
 * @param cb_data The data to pass to the callback.
 */
EAPI void eldbus_proxy_event_callback_add(Eldbus_Proxy *proxy, Eldbus_Proxy_Event_Type type, Eldbus_Proxy_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3);

/**
 * @brief Remove callback registered in eldbus_proxy_event_callback_add().
 *
 * @param proxy The Eldbus_Proxy object.
 * @param type The type of the event the callback was registered on.
 * @param cb The callback function to delete.
 * @param cb_data The data passed to the callback.
 */
EAPI void eldbus_proxy_event_callback_del(Eldbus_Proxy *proxy, Eldbus_Proxy_Event_Type type, Eldbus_Proxy_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3);

/**
 * @}
 */
#endif