aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eldbus/eldbus_message.h
blob: dbb9e0c919d8f081e3441f3d4987ccda943acd2f (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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
#ifndef ELDBUS_MESSAGE_H
#define ELDBUS_MESSAGE_H 1

/**
 * @defgroup Eldbus_Message Message
 * @ingroup Eldbus
 *
 * @{
 */

/**
 * @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);

/**
 * @brief Decrease message reference.
 *
 * 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;

/**
 * @brief Create a new message to invoke a method on a remote object.
 *
 * @param dest bus name or unique id of the remote application
 * @param path object path
 * @param iface interface name
 * @param method name of the method to be called
 *
 * @return a new Eldbus_Message, free with eldbus_message_unref()
 */
EAPI Eldbus_Message        *eldbus_message_method_call_new(const char *dest, const char *path, const char *iface, const char *method) EINA_ARG_NONNULL(1, 2, 3, 4) EINA_WARN_UNUSED_RESULT EINA_MALLOC;

/**
 * @brief Create a new signal message.
 *
 * @param path object path
 * @param interface interface name
 * @param name name of the signal to be broadcasted
 *
 * @return a new Eldbus_Message, free with eldbus_message_unref()
 *
 * @since 1.16
 */
EAPI Eldbus_Message *eldbus_message_signal_new(const char *path, const char *interface, const char *name) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Create a new message that is an error reply to another message.
 *
 * @param msg the message we're replying to
 * @param error_name the error name
 * @param error_msg the error message string
 *
 * @return a new Eldbus_Message, free with eldbus_message_unref()
 */
EAPI Eldbus_Message        *eldbus_message_error_new(const Eldbus_Message *msg, const char *error_name, const char *error_msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Create a message that is a reply to a method call.
 *
 * @param msg the message we're replying to
 *
 * @return new Eldbus_Message, free with eldbus_message_unref()
 */
EAPI Eldbus_Message        *eldbus_message_method_return_new(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;


/**
 * @brief Get the error text and name from a Eldbus_Message.
 *
 * If @param msg is an error message return EINA_TRUE and fill in the name and
 * text of the error.
 *
 * @param msg The message containing the error
 * @param name Variable in which to store the error name or @c NULL if it's not
 * 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);

/**
 * @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
 * argument must be of a type that is appropriate for the correspondent complete
 * 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.
 * @param signature The signature of the arguments user is expecting to read
 * from @param msg
 * @param ... The pointers in which to store the message arguments
 *
 * @return EINA_TRUE if the arguments were read successfully and stored in the
 * respective pointer arguments.
 */
EAPI Eina_Bool             eldbus_message_arguments_get(const Eldbus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;

/**
 * @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 ap The va_list containing the pointer arguments.
 *
 * @see eldbus_message_arguments_get()
 *
 * @return EINA_TRUE if the arguments were read successfully and stored in the
 * respective pointer arguments.
 */
EAPI Eina_Bool             eldbus_message_arguments_vget(const Eldbus_Message *msg, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;

/**
 * @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
 * corresponding type must be provided.
 *
 * This function supports only basic types. For complex types use
 * eldbus_message_iter_* family of functions.
 *
 * @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.
 *
 * @return EINA_TRUE on success, EINA_FALSE otherwise.
 */
EAPI Eina_Bool             eldbus_message_arguments_append(Eldbus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Append arguments into an Eldbus_Message using a va_list.
 *
 * @param msg The message in which arguments are being appended.
 * @param signature Signature of the arguments that are being appended.
 * @param ap The va_list containing the arguments to append.
 *
 * @see eldbus_message_arguments_append().
 *
 * @return EINA_TRUE on success, EINA_FALSE otherwise.
 */
EAPI Eina_Bool             eldbus_message_arguments_vappend(Eldbus_Message *msg, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2);

/**
 * @defgroup Eldbus_Message_Iter Iterator
 * @{
 */

/**
 * @brief Create and append a typed iterator to another iterator.
 *
 * After append data to returned iterator it must be closed calling
 * eldbus_message_iter_container_close().
 *
 * Container types are for example struct, variant, and array.
 * For variants, the contained_signature should be the type of the single
 * value inside the variant. For structs and dict entries, contained_signature
 * should be NULL; it will be set to whatever types you write into the struct.
 * For arrays, contained_signature should be the type of the array elements.
 *
 * @param iter parent of the new iterator
 * @param type of iterator (e.g struct, dict, variant or array)
 * @param contained_signature signature of what iterator will store
 *
 * @return the new iterator
 */
EAPI Eldbus_Message_Iter *eldbus_message_iter_container_new(Eldbus_Message_Iter *iter, int type, const char* contained_signature) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Append a basic type into an Eldbus_Iterator.
 *
 * @param iter The iterator in which basic type will be appended.
 * @param type The basic type that will be appended.
 * @param ... The values for the basic type.
 *
 * @return EINA_TRUE on success, else EINA_FALSE.
 */
EAPI Eina_Bool               eldbus_message_iter_basic_append(Eldbus_Message_Iter *iter, int type, ...) EINA_ARG_NONNULL(1, 3);

/**
 * @brief Append an argument into an Eldbus_Message_Iter. For each complete type
 * you need to provide the correspondent value. In case of complex types you
 * need to provide an Eldbus_Message_Iter** to be allocated and then filled in.
 *
 * It's not possible to open two iterators at same iterator with this function.
 * For example, to create a message with signature="aiai" you need to create the
 * first container with eldbus_message_iter_container_new(), fill the array,
 * close it with eldbus_message_iter_container_close() and then do the same for
 * the second array.
 *
 * @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()
 *
 * @note This function doesn't support variant, use
 * eldbus_message_iter_container_new() instead to create the variant, fill
 * with data and close it.
 */
EAPI Eina_Bool               eldbus_message_iter_arguments_append(Eldbus_Message_Iter *iter, const char *signature, ...) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Set data to Eldbus_Message_Iter. For each complete in signature
 * you need pass the value, in case of complex type a pointer to be allocated a
 * Eldbus_Message_Iter that you need fill and close.
 *
 * It's not possible open two iterators at same Iterator. Example:
 * "aiai", to set this you need create and put the first array with
 * eldbus_message_iter_container_new() fill array with data and close then
 * you could open the second array with eldbus_message_iter_container_new().
 *
 * @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
 * data and close it.
 */
EAPI Eina_Bool               eldbus_message_iter_arguments_vappend(Eldbus_Message_Iter *iter, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2, 3);


/**
 * Append a array of basic type with fixed size to Eldbus_Message_Iter.
 *
 * @param iter iterator
 * @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);

/**
 * @brief Closes a container-typed value appended to the message.
 *
 * @param iter parent of the sub-iterator
 * @param sub the iterator that will be closed
 *
 * @return EINA_FALSE if iterator was already close or if not enough memory
 */
EAPI Eina_Bool               eldbus_message_iter_container_close(Eldbus_Message_Iter *iter, Eldbus_Message_Iter *sub) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Get the main Eldbus_Message_Iter from the Eldbus_Message.
 *
 * @param msg The message to get the iterator from.
 *
 * @return The iterator of the message.
 */
EAPI Eldbus_Message_Iter *eldbus_message_iter_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Get a basic type from Eldbus_Iterator.
 *
 * @param iter The iterator to get the basic type from.
 * @param value The basic type of the iterator.
 */
EAPI void                    eldbus_message_iter_basic_get(Eldbus_Message_Iter *iter, void *value) EINA_ARG_NONNULL(1, 2);

/**
 * @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;

/**
 * @brief Moves the iterator to the next field, if any.
 * @param iter iterator
 *
 * @return if iterator was reach to end return EINA_FALSE
 */
EAPI Eina_Bool               eldbus_message_iter_next(Eldbus_Message_Iter *iter) EINA_ARG_NONNULL(1);

/**
 * @brief Get a complete type from Eldbus_Message_Iter if is not at the end
 * of iterator and move to next field.
 * Useful to iterate over arrays.
 *
 * @param iter iterator
 * @param signature of the next completed type in Iterator
 * @param ... pointer of where data will be stored
 *
 * @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 signature, ...) EINA_ARG_NONNULL(1, 2, 3);

/**
 * @brief Reads a block of fixed-length values from the message iterator.
 *
 * Fixed-length values are those basic types that are not string-like,
 * such as integers, bool, double. The returned block will be from the
 * current position in the array until the end of the array.
 *
 * There is one exception here: although ELDBUS_TYPE_UNIX_FD is considered a
 * 'fixed' type arrays of this type may not be read with this function.
 *
 * The value argument should be the address of a location to store the returned
 * array. So for int32 it should be a "const dbus_int32_t**" The returned value
 * is by reference and should not be freed.
 *
 * 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);

/**
 * @brief Get data from Eldbus_Message_Iter, for each complete type must have
 * a pointer to store his value, in case of complex type a
 * Eldbus_Message_Iter will be need.
 *
 * @param iter iterator
 * @param signature of the complete data types on interator
 * @param ... pointers of where data will be stored
 *
 * @return EINA_FALSE if signature different from signature in iterator
 */
EAPI Eina_Bool               eldbus_message_iter_arguments_get(Eldbus_Message_Iter *iter, const char *signature, ...) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Get data from Eldbus_Message_Iter, for each complete type must have
 * a pointer to store his value, in case of complex type a
 * Eldbus_Message_Iter will be need.
 *
 * @param iter iterator
 * @param signature of the complete data types on interator
 * @param ap va_list of the pointers of where data will be stored
 *
 * @return EINA_FALSE if signature different from signature in iterator
 */
EAPI Eina_Bool               eldbus_message_iter_arguments_vget(Eldbus_Message_Iter *iter, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Manually delete the iterator.
 *
 * Iterators are usually bound to the life of @ref Eldbus_Message
 * they were created from, being deleted automatically once the
 * message is deleted.
 *
 * However when dealing with huge arrays or dicts it may become a
 * major memory impact to leave the unused iterators alive. By
 * calling this function one states the iterator is not used anymore
 * and can be deleted.
 *
 * @param iter the iterator to be deleted.
 */
EAPI void                  eldbus_message_iter_del(Eldbus_Message_Iter *iter) EINA_ARG_NONNULL(1);

/**
 * @}
 */

#include "eldbus_message_helper.h"
#include "eldbus_message_eina_value.h"

/**
 * @}
 */
#endif