diff options
Diffstat (limited to 'libraries/eina/src/include/eina_value.h')
-rw-r--r-- | libraries/eina/src/include/eina_value.h | 3533 |
1 files changed, 0 insertions, 3533 deletions
diff --git a/libraries/eina/src/include/eina_value.h b/libraries/eina/src/include/eina_value.h deleted file mode 100644 index 341781f..0000000 --- a/libraries/eina/src/include/eina_value.h +++ /dev/null | |||
@@ -1,3533 +0,0 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2012 ProFUSION embedded systems | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_VALUE_H_ | ||
20 | #define EINA_VALUE_H_ | ||
21 | |||
22 | #include <stdarg.h> | ||
23 | |||
24 | #include "eina_types.h" | ||
25 | #include "eina_fp.h" /* defines int64_t and uint64_t */ | ||
26 | #include "eina_inarray.h" | ||
27 | #include "eina_list.h" | ||
28 | #include "eina_hash.h" | ||
29 | |||
30 | /** | ||
31 | * @page eina_value_example_01_page Eina_Value usage | ||
32 | * @dontinclude eina_value_01.c | ||
33 | * | ||
34 | * This very simple example shows how to use some of the basic features of eina | ||
35 | * value: setting and getting values, converting between types and printing a | ||
36 | * value as a string. | ||
37 | * | ||
38 | * Our main function starts out with the basic, declaring some variables and | ||
39 | * initializing eina: | ||
40 | * @until eina_init | ||
41 | * | ||
42 | * Now we can jump into using eina value. We set a value, get this value and | ||
43 | * then print it: | ||
44 | * @until printf | ||
45 | * | ||
46 | * In the above snippet of code we printed an @c int value, we can however print | ||
47 | * the value as a string: | ||
48 | * @until free | ||
49 | * | ||
50 | * And once done with a value it's good practice to destroy it: | ||
51 | * @until eina_value_flush | ||
52 | * | ||
53 | * We now reuse @c v to store a string, get its value and print it: | ||
54 | * @until printf | ||
55 | * @note Since @c s is the value and not returned by @c eina_value_to_string() | ||
56 | * we don't need to free it. | ||
57 | * | ||
58 | * Just because we stored a string doesn't mean we can't use the @c | ||
59 | * eina_value_to_string() function, we can and it's important to note that it | ||
60 | * will return not the stored string but rather a copy of it(one we have to | ||
61 | * free): | ||
62 | * @until eina_value_flush | ||
63 | * | ||
64 | * And now to explore conversions between two type we'll create another value: | ||
65 | * @until eina_value_setup | ||
66 | * | ||
67 | * And make sure @c v and @c otherv have different types: | ||
68 | * @until eina_value_setup | ||
69 | * | ||
70 | * We then set a value to @c v and have it converted, to do this we don't need | ||
71 | * to tell to which type we want to convert, we just say were we want to store | ||
72 | * the converted value and eina value will figure out what to convert to, and | ||
73 | * how: | ||
74 | * @until eina_value_convert | ||
75 | * | ||
76 | * And now let's check the conversion worked: | ||
77 | * @until printf | ||
78 | * | ||
79 | * But converting to strings is not particularly exciting, @c | ||
80 | * eina_value_to_string() already did that, so now let's make the conversion the | ||
81 | * other way around, from string to @c int: | ||
82 | * @until printf | ||
83 | * | ||
84 | * And once done, destroy the values: | ||
85 | * @until } | ||
86 | * | ||
87 | * Full source code: @ref eina_value_01_c | ||
88 | */ | ||
89 | |||
90 | /** | ||
91 | * @page eina_value_01_c eina_value_01.c | ||
92 | * @include eina_value_01.c | ||
93 | * @example eina_value_01.c | ||
94 | */ | ||
95 | |||
96 | /** | ||
97 | * @page eina_value_example_02_page Eina_Value struct usage | ||
98 | * @dontinclude eina_value_02.c | ||
99 | * | ||
100 | * This example will examine a hypothetical situation in which we had a | ||
101 | * structure(which represented parameters) with two fields, and then need to add | ||
102 | * a third field to our structure. If using structs directly we'd need to | ||
103 | * rewrite every piece of code that touches the struct, by using eina value, and | ||
104 | * thus having the compiler not even know the struct, we can reduce the amount | ||
105 | * of changes needed and retain interoperability between the old and new format. | ||
106 | * | ||
107 | * Our example will start with a function that creates descriptions of both of | ||
108 | * our structs for eina value usage. The first step is to create a struct and | ||
109 | * describe its members: | ||
110 | * @until v1_members[1] | ||
111 | * @note We can't pass the types of the members to EINA_VALUE_STRUCT_MEMBER | ||
112 | * macro because they are not constant initializers. | ||
113 | * | ||
114 | * So far it should be pretty easy to understand, we said @c My_Struct_V1 has | ||
115 | * two members, one of type @c int and another of type @c char. We now create | ||
116 | * the description of the actual struct, again nothing overly complex, we signal | ||
117 | * which version of EINA_VALUE_STRUCT we're using, we declare no special | ||
118 | * operations, our members and our size: | ||
119 | * @until V1_DESC | ||
120 | * | ||
121 | * We now repeat the process for the second version of our struct, the only | ||
122 | * difference is the addition of a third parameter of type @c int : | ||
123 | * @until V2_DESC | ||
124 | * @until } | ||
125 | * | ||
126 | * We'll now look at a function that sets the values of our structs. For | ||
127 | * simplicity's sake we initialize it we random values, a real world case would | ||
128 | * read these values from a file, a database or even from the network. The | ||
129 | * fundamental detail here is that this function works for both V1 and V2 | ||
130 | * structs, this is because setting a parameter that a struct that doesn't have | ||
131 | * does nothing without throwing any errors: | ||
132 | * @until } | ||
133 | * @note While using eina_value_struct_set() with an in-existing parameter | ||
134 | * causes no error, it does return #EINA_FALSE, to notify it was not possible | ||
135 | * to set the value. This could be used to determine that we're handling a V1 | ||
136 | * struct and take some action based on that. | ||
137 | * | ||
138 | * The next thing is to do is see what a function that uses the values of the | ||
139 | * struct looks like. We'll again be very simplistic in our usage, we'll just | ||
140 | * print the values, but a real world case, might send these values to another | ||
141 | * process use them to open a network/database connection or anything else. | ||
142 | * Since all versions of the struct have @c param1 and @c param2 we'll | ||
143 | * unconditionally use them: | ||
144 | * @until printf | ||
145 | * | ||
146 | * The next step is to conditionally use @c param3, which can fortunately be | ||
147 | * done in the same step in which we get it's value: | ||
148 | * @until } | ||
149 | * | ||
150 | * There we've now got functions that can both populate and use values from both | ||
151 | * our structs, so now let's actually use them in our main function by creating | ||
152 | * a struct of each type, initializing them and them using them: | ||
153 | * @until } | ||
154 | * | ||
155 | * This concludes our example. For the full source code see @ref | ||
156 | * eina_value_02_c. | ||
157 | */ | ||
158 | |||
159 | /** | ||
160 | * @page eina_value_02_c eina_value_02.c | ||
161 | * @include eina_value_02.c | ||
162 | * @example eina_value_02.c | ||
163 | */ | ||
164 | |||
165 | /** | ||
166 | * @page eina_value_example_03_page Eina value custom type example | ||
167 | * @dontinclude eina_value_03.c | ||
168 | * | ||
169 | * For this example we'll be creating our own custom type of eina value. Eina | ||
170 | * value can already store struct timeval(man gettimeofday for more information) | ||
171 | * but it has no type to store struct timezone, so that's what this example will | ||
172 | * do. | ||
173 | * @note struct timezone is actually obsolete, so using it in real world | ||
174 | * programs is probably not a good idea, but this is an example so, bear with | ||
175 | * us. | ||
176 | * | ||
177 | * To create our own custom eina value type we need to define functions to | ||
178 | * do the following operations on it: | ||
179 | * @li Setup | ||
180 | * @li Flush | ||
181 | * @li Copy | ||
182 | * @li Compare | ||
183 | * @li Set | ||
184 | * @li Get | ||
185 | * @li Conversion | ||
186 | * | ||
187 | * Most of this functions are very simple, so let's look at them, starting with | ||
188 | * setup which only clear the memory so that we can be certain we won't be using | ||
189 | * stale data: | ||
190 | * @until } | ||
191 | * | ||
192 | * Now the flush function, which is even simpler, it does nothing, that's | ||
193 | * because there is nothing we need to do, all the necessary steps are taken by | ||
194 | * eina value itself: | ||
195 | * @until } | ||
196 | * | ||
197 | * Our next function, copy, is a bit more interesting, but not much, it just | ||
198 | * casts our void pointers to struct timezone pointers and does the copy: | ||
199 | * @until } | ||
200 | * @note By now you might be wondering why our functions receive void pointers | ||
201 | * instead of pointers to struct timezone, and this is a good point. The reason | ||
202 | * for this is that eina value doesn't know anything about our type so it must | ||
203 | * use a generic void pointer, casting that pointer into a proper value is the | ||
204 | * job of the implementor of the new type. | ||
205 | * | ||
206 | * Next we have the comparison function, which compares the @c tz_minuteswest | ||
207 | * field of struct timezone, we don't compare @c tz_dsttime because that field | ||
208 | * is not used in linux: | ||
209 | * @until } | ||
210 | * | ||
211 | * Next we have setting, this however requires not one but rather two functions, | ||
212 | * the reason for this is because to be able to receive arguments of any type | ||
213 | * eina value uses @ref https://wikipedia.org/wiki/Variadic_functions "variadic | ||
214 | * functions", so we need a function to get the argument from a va_list and | ||
215 | * another to actually to the setting. | ||
216 | * | ||
217 | * Lets first look at the pset function which sets the received value to a | ||
218 | * pointer: | ||
219 | * @until } | ||
220 | * | ||
221 | * Next we have the vset function which get the argument from the va_list and | ||
222 | * passes it to the pset function: | ||
223 | * @until } | ||
224 | * | ||
225 | * And now the function to get the value, a very simple copying of the value to | ||
226 | * the given pointer: | ||
227 | * @until } | ||
228 | * | ||
229 | * And finally our conversion function, this is our longest and most interesting | ||
230 | * one. For numeric type we simply assign the value of @c tz_minuteswest to the | ||
231 | * new type and call a set function using it: | ||
232 | * @until EINA_VALUE_TYPE_DOUBLE | ||
233 | * @until return | ||
234 | * @note It would be a good idea to add checks for over and underflow for these | ||
235 | * types and return #EINA_FALSE in thoses cases, we omit this here for brevity. | ||
236 | * | ||
237 | * For string types we use @c snprintf() to format our @c tz_minuteswest field | ||
238 | * and put it in a string(again @c tz_dsttime is ignored because it's not used): | ||
239 | * @until } | ||
240 | * | ||
241 | * Finally we handle any other types by returning an error in that case: | ||
242 | * @until } | ||
243 | * | ||
244 | * Now that we have all the functions, we can populate an @c Eina_Value_Type to | ||
245 | * later use it with @c eina_value_setup(): | ||
246 | * @until } | ||
247 | * | ||
248 | * We can now finally use our new TZ_TYPE with eina value, so lets conclude our | ||
249 | * example by practicing that by setting its value and printing it: | ||
250 | * @until } | ||
251 | * | ||
252 | * For the full source code see @ref eina_value_03_c. | ||
253 | */ | ||
254 | |||
255 | /** | ||
256 | * @page eina_value_03_c eina_value_03.c | ||
257 | * @include eina_value_03.c | ||
258 | * @example eina_value_03.c | ||
259 | */ | ||
260 | |||
261 | /** | ||
262 | * @addtogroup Eina_Data_Types_Group Data Types | ||
263 | * | ||
264 | * @since 1.2 | ||
265 | * | ||
266 | * @{ | ||
267 | */ | ||
268 | |||
269 | /** | ||
270 | * @addtogroup Eina_Containers_Group Containers | ||
271 | * | ||
272 | * @{ | ||
273 | */ | ||
274 | |||
275 | /** | ||
276 | * @defgroup Eina_Value_Group Generic Value Storage | ||
277 | * | ||
278 | * Abstracts generic data storage and access to it in an extensible | ||
279 | * and efficient way. | ||
280 | * | ||
281 | * It comes with pre-defined types for numbers, array, list, hash, | ||
282 | * blob and structs. It is able to convert between data types, | ||
283 | * including to string. | ||
284 | * | ||
285 | * It is meant for simple data types, providing uniform access and | ||
286 | * release functions, useful to exchange data preserving their | ||
287 | * types. For more complex hierarchical data, with properties and | ||
288 | * children, reference counting, inheritance and interfaces, see @ref | ||
289 | * Eina_Model_Group. | ||
290 | * | ||
291 | * Examples of usage of the Eina_Value API: | ||
292 | * @li @ref eina_value_example_01_page | ||
293 | * @li @ref eina_value_example_02_page | ||
294 | * @li @ref eina_value_example_03_page | ||
295 | * | ||
296 | * @{ | ||
297 | */ | ||
298 | |||
299 | |||
300 | /** | ||
301 | * @typedef Eina_Value | ||
302 | * Store generic values. | ||
303 | * | ||
304 | * @since 1.2 | ||
305 | */ | ||
306 | typedef struct _Eina_Value Eina_Value; | ||
307 | |||
308 | /** | ||
309 | * @typedef Eina_Value_Type | ||
310 | * Describes the data contained by the value | ||
311 | * | ||
312 | * @since 1.2 | ||
313 | */ | ||
314 | typedef struct _Eina_Value_Type Eina_Value_Type; | ||
315 | |||
316 | /** | ||
317 | * @typedef Eina_Value_Union | ||
318 | * Union of all known value types. | ||
319 | * | ||
320 | * This is only used to specify the minimum payload memory for #Eina_Value. | ||
321 | * | ||
322 | * @internal | ||
323 | * @since 1.2 | ||
324 | */ | ||
325 | typedef union _Eina_Value_Union Eina_Value_Union; | ||
326 | |||
327 | /** | ||
328 | * @union _Eina_Value_Union | ||
329 | * All possible value types. | ||
330 | * | ||
331 | * This is only used to specify the minimum payload memory for #Eina_Value. | ||
332 | * | ||
333 | * @internal | ||
334 | * @since 1.2 | ||
335 | */ | ||
336 | union _Eina_Value_Union | ||
337 | { | ||
338 | unsigned char buf[8]; /**< just hold 8-bytes, more goes into ptr */ | ||
339 | void *ptr; /**< used as generic pointer */ | ||
340 | uint64_t _guarantee; /**< guarantees 8-byte alignment */ | ||
341 | }; | ||
342 | |||
343 | /** | ||
344 | * @var EINA_VALUE_TYPE_UCHAR | ||
345 | * manages unsigned char type. | ||
346 | * | ||
347 | * @since 1.2 | ||
348 | */ | ||
349 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UCHAR; | ||
350 | |||
351 | /** | ||
352 | * @var EINA_VALUE_TYPE_USHORT | ||
353 | * manages unsigned short type. | ||
354 | * | ||
355 | * @since 1.2 | ||
356 | */ | ||
357 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_USHORT; | ||
358 | |||
359 | /** | ||
360 | * @var EINA_VALUE_TYPE_UINT | ||
361 | * manages unsigned int type. | ||
362 | * | ||
363 | * @since 1.2 | ||
364 | */ | ||
365 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UINT; | ||
366 | |||
367 | /** | ||
368 | * @var EINA_VALUE_TYPE_ULONG | ||
369 | * manages unsigned long type. | ||
370 | * | ||
371 | * @since 1.2 | ||
372 | */ | ||
373 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ULONG; | ||
374 | |||
375 | /** | ||
376 | * @var EINA_VALUE_TYPE_TIMESTAMP | ||
377 | * manages unsigned long type used for timestamps. | ||
378 | * @note this is identical in function to EINA_VALUE_TYPE_ULONG | ||
379 | * | ||
380 | * @since 1.2 | ||
381 | */ | ||
382 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_TIMESTAMP; | ||
383 | |||
384 | /** | ||
385 | * @var EINA_VALUE_TYPE_UINT64 | ||
386 | * manages unsigned integer of 64 bits type. | ||
387 | * | ||
388 | * @since 1.2 | ||
389 | */ | ||
390 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UINT64; | ||
391 | |||
392 | /** | ||
393 | * @var EINA_VALUE_TYPE_CHAR | ||
394 | * manages char type. | ||
395 | * | ||
396 | * @since 1.2 | ||
397 | */ | ||
398 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_CHAR; | ||
399 | |||
400 | /** | ||
401 | * @var EINA_VALUE_TYPE_SHORT | ||
402 | * manages short type. | ||
403 | * | ||
404 | * @since 1.2 | ||
405 | */ | ||
406 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_SHORT; | ||
407 | |||
408 | /** | ||
409 | * @var EINA_VALUE_TYPE_INT | ||
410 | * manages int type. | ||
411 | * | ||
412 | * @since 1.2 | ||
413 | */ | ||
414 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_INT; | ||
415 | |||
416 | /** | ||
417 | * @var EINA_VALUE_TYPE_LONG | ||
418 | * manages long type. | ||
419 | * | ||
420 | * @since 1.2 | ||
421 | */ | ||
422 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_LONG; | ||
423 | |||
424 | /** | ||
425 | * @var EINA_VALUE_TYPE_INT64 | ||
426 | * manages integer of 64 bits type. | ||
427 | * | ||
428 | * @since 1.2 | ||
429 | */ | ||
430 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_INT64; | ||
431 | |||
432 | /** | ||
433 | * @var EINA_VALUE_TYPE_FLOAT | ||
434 | * manages float type. | ||
435 | * | ||
436 | * @since 1.2 | ||
437 | */ | ||
438 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_FLOAT; | ||
439 | |||
440 | /** | ||
441 | * @var EINA_VALUE_TYPE_DOUBLE | ||
442 | * manages double type. | ||
443 | * | ||
444 | * @since 1.2 | ||
445 | */ | ||
446 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_DOUBLE; | ||
447 | |||
448 | /** | ||
449 | * @var EINA_VALUE_TYPE_STRINGSHARE | ||
450 | * manages stringshared string type. | ||
451 | * | ||
452 | * @since 1.2 | ||
453 | */ | ||
454 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRINGSHARE; | ||
455 | |||
456 | /** | ||
457 | * @var EINA_VALUE_TYPE_STRING | ||
458 | * manages string type. | ||
459 | * | ||
460 | * @since 1.2 | ||
461 | */ | ||
462 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRING; | ||
463 | |||
464 | |||
465 | /** | ||
466 | * @var EINA_VALUE_TYPE_ARRAY | ||
467 | * | ||
468 | * manages array type. Use the value get/set for arrays: | ||
469 | * @li eina_value_array_get() and eina_value_array_set() | ||
470 | * @li eina_value_array_vget() and eina_value_array_vset() | ||
471 | * @li eina_value_array_pget() and eina_value_array_pset() | ||
472 | * | ||
473 | * eina_value_set() takes an #Eina_Value_Array where just @c subtype | ||
474 | * and @c step are used. If there is an @c array, it will be copied | ||
475 | * (including each item) and its contents must be properly | ||
476 | * configurable as @c subtype expects. eina_value_pset() takes a | ||
477 | * pointer to an #Eina_Value_Array. For your convenience, use | ||
478 | * eina_value_array_setup(). | ||
479 | * | ||
480 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
481 | * #Eina_Value_Array, it's an exact copy of the current structure in | ||
482 | * use by value, no copies are done. | ||
483 | * | ||
484 | * @since 1.2 | ||
485 | */ | ||
486 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ARRAY; | ||
487 | |||
488 | /** | ||
489 | * @var EINA_VALUE_TYPE_LIST | ||
490 | * | ||
491 | * manages list type. Use the value get/set for lists: | ||
492 | * @li eina_value_list_get() and eina_value_list_set() | ||
493 | * @li eina_value_list_vget() and eina_value_list_vset() | ||
494 | * @li eina_value_list_pget() and eina_value_list_pset() | ||
495 | * | ||
496 | * eina_value_set() takes an #Eina_Value_List where just @c subtype is | ||
497 | * used. If there is an @c list, it will be copied (including each | ||
498 | * item) and its contents must be properly configurable as @c | ||
499 | * subtype expects. eina_value_pset() takes a pointer to an | ||
500 | * #Eina_Value_List. For your convenience, use | ||
501 | * eina_value_list_setup(). | ||
502 | * | ||
503 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
504 | * #Eina_Value_List, it's an exact copy of the current structure in | ||
505 | * use by value, no copies are done. | ||
506 | * | ||
507 | * @since 1.2 | ||
508 | */ | ||
509 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_LIST; | ||
510 | |||
511 | /** | ||
512 | * @var EINA_VALUE_TYPE_HASH | ||
513 | * | ||
514 | * manages hash type. Use the value get/set for hashes: | ||
515 | * @li eina_value_hash_get() and eina_value_hash_set() | ||
516 | * @li eina_value_hash_vget() and eina_value_hash_vset() | ||
517 | * @li eina_value_hash_pget() and eina_value_hash_pset() | ||
518 | * | ||
519 | * eina_value_set() takes an #Eina_Value_Hash where just @c subtype | ||
520 | * and @c buckets_power_size are used. If there is an @c hash, it will | ||
521 | * be copied (including each item) and its contents must be | ||
522 | * properly configurable as @c subtype expects. eina_value_pset() | ||
523 | * takes a pointer to an #Eina_Value_Hash. For your convenience, use | ||
524 | * eina_value_hash_setup(). | ||
525 | * | ||
526 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
527 | * #Eina_Value_Hash, it's an exact copy of the current structure in | ||
528 | * use by value, no copies are done. | ||
529 | * | ||
530 | * @note be aware that hash data is always an allocated memory of size | ||
531 | * defined by @c subtype->value_size. If your @c subtype is an | ||
532 | * integer, add as data malloc(sizeof(int)). If your @c subtype | ||
533 | * is an string, add as data malloc(sizeof(char*)) and this data | ||
534 | * value must point to strdup(string)! | ||
535 | * | ||
536 | * @since 1.2 | ||
537 | */ | ||
538 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_HASH; | ||
539 | |||
540 | /** | ||
541 | * @var EINA_VALUE_TYPE_TIMEVAL | ||
542 | * manages 'struct timeval' type | ||
543 | * | ||
544 | * eina_value_set() takes a "struct timeval" from sys/time.h. | ||
545 | * eina_value_pset() takes a pointer to "struct timeval". | ||
546 | * | ||
547 | * eina_value_get() and eina_value_pget() takes a pointer to "struct | ||
548 | * timeval" and it's an exact copy of value. | ||
549 | * | ||
550 | * @since 1.2 | ||
551 | */ | ||
552 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_TIMEVAL; | ||
553 | |||
554 | /** | ||
555 | * @var EINA_VALUE_TYPE_BLOB | ||
556 | * manages blob of bytes type, see @ref Eina_Value_Blob | ||
557 | * | ||
558 | * eina_value_set() takes an #Eina_Value_Blob | ||
559 | * eina_value_pset() takes a pointer to #Eina_Value_Blob. | ||
560 | * | ||
561 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
562 | * #Eina_Value_Blob and it's an exact copy of value, no allocations | ||
563 | * are made. | ||
564 | * | ||
565 | * Memory is untouched unless you provide @c ops (operations) pointer. | ||
566 | * | ||
567 | * @since 1.2 | ||
568 | */ | ||
569 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_BLOB; | ||
570 | |||
571 | /** | ||
572 | * @var EINA_VALUE_TYPE_STRUCT | ||
573 | * | ||
574 | * manages struct type. Use the value get/set for structs: | ||
575 | * @li eina_value_struct_get() and eina_value_struct_set() | ||
576 | * @li eina_value_struct_vget() and eina_value_struct_vset() | ||
577 | * @li eina_value_struct_pget() and eina_value_struct_pset() | ||
578 | * | ||
579 | * eina_value_set() takes an #Eina_Value_Struct where just @c desc is | ||
580 | * used. If there is an @c memory, it will be copied (including each | ||
581 | * member) and its contents must be properly configurable as @c desc | ||
582 | * expects. eina_value_pset() takes a pointer to an | ||
583 | * #Eina_Value_Struct. For your convenience, use | ||
584 | * eina_value_struct_setup(). | ||
585 | * | ||
586 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
587 | * #Eina_Value_Struct, it's an exact copy of the current structure in | ||
588 | * use by value, no copies are done. | ||
589 | * | ||
590 | * @since 1.2 | ||
591 | */ | ||
592 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRUCT; | ||
593 | |||
594 | /** | ||
595 | * @var EINA_VALUE_TYPE_MODEL | ||
596 | * | ||
597 | * manages Eina_Model type. Use the value get/set to change the model | ||
598 | * in use, it will increase the reference while in use by the value. | ||
599 | * | ||
600 | * eina_value_set() takes a pointer to #Eina_Model, increasing the | ||
601 | * reference. | ||
602 | * | ||
603 | * eina_value_get() takes a pointer to pointer to #Eina_Model, it's an | ||
604 | * exact copy of the current model, no copies are done, no references | ||
605 | * are increased. | ||
606 | * | ||
607 | * @since 1.2 | ||
608 | */ | ||
609 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_MODEL; | ||
610 | |||
611 | /** | ||
612 | * @var EINA_ERROR_VALUE_FAILED | ||
613 | * Error identifier corresponding to value check failure. | ||
614 | * | ||
615 | * @since 1.2 | ||
616 | */ | ||
617 | EAPI extern int EINA_ERROR_VALUE_FAILED; | ||
618 | |||
619 | /** | ||
620 | * @defgroup Eina_Value_Value_Group Generic Value management | ||
621 | * | ||
622 | * @{ | ||
623 | */ | ||
624 | |||
625 | /** | ||
626 | * @struct _Eina_Value | ||
627 | * defines the contents of a value | ||
628 | * | ||
629 | * @since 1.2 | ||
630 | */ | ||
631 | struct _Eina_Value | ||
632 | { | ||
633 | const Eina_Value_Type *type; /**< how to access values */ | ||
634 | Eina_Value_Union value; /**< to be accessed with type descriptor */ | ||
635 | }; | ||
636 | |||
637 | /** | ||
638 | * @brief Create generic value storage. | ||
639 | * @param type how to manage this value. | ||
640 | * @return The new value or @c NULL on failure. | ||
641 | * | ||
642 | * Create a new generic value storage. The members are managed using | ||
643 | * the description specified by @a type. | ||
644 | * | ||
645 | * Some types may specify more operations: | ||
646 | * eg. #EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), | ||
647 | * eina_value_array_get() and so on. | ||
648 | * | ||
649 | * On failure, @c NULL is returned and either #EINA_ERROR_OUT_OF_MEMORY or | ||
650 | * #EINA_ERROR_VALUE_FAILED is set. | ||
651 | * | ||
652 | * @note this calls creates from mempool and then uses | ||
653 | * eina_value_setup(). Consider using eina_value_flush() and | ||
654 | * eina_value_setup() instead to avoid memory allocations. | ||
655 | * | ||
656 | * @see eina_value_free() | ||
657 | * | ||
658 | * @since 1.2 | ||
659 | */ | ||
660 | EAPI Eina_Value *eina_value_new(const Eina_Value_Type *type) EINA_ARG_NONNULL(1) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
661 | |||
662 | /** | ||
663 | * @brief Free value and its data. | ||
664 | * @param value value object | ||
665 | * | ||
666 | * @see eina_value_flush() | ||
667 | * | ||
668 | * @since 1.2 | ||
669 | */ | ||
670 | EAPI void eina_value_free(Eina_Value *value) EINA_ARG_NONNULL(1); | ||
671 | |||
672 | |||
673 | /** | ||
674 | * @brief Initialize generic value storage. | ||
675 | * @param value value object | ||
676 | * @param type how to manage this value. | ||
677 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
678 | * | ||
679 | * Initializes existing generic value storage. The members are managed using the | ||
680 | * description specified by @a type. | ||
681 | * | ||
682 | * Some types may specify more operations, as an example | ||
683 | * #EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), | ||
684 | * eina_value_array_get() and so on. | ||
685 | * | ||
686 | * @note Existing contents are ignored! If the value was previously used, then | ||
687 | * use eina_value_flush() first. | ||
688 | * | ||
689 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
690 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
691 | * | ||
692 | * @see eina_value_flush() | ||
693 | * | ||
694 | * @since 1.2 | ||
695 | */ | ||
696 | static inline Eina_Bool eina_value_setup(Eina_Value *value, | ||
697 | const Eina_Value_Type *type) EINA_ARG_NONNULL(1, 2); | ||
698 | |||
699 | /** | ||
700 | * @brief Create generic value storage. | ||
701 | * @param value value object | ||
702 | * | ||
703 | * Releases all the resources associated with an #Eina_Value. The | ||
704 | * value must be already set with eina_value_setup() or | ||
705 | * eina_value_new(). | ||
706 | * | ||
707 | * After this call returns, the contents of the value are undefined, | ||
708 | * but the value can be reused by calling eina_value_setup() again. | ||
709 | * | ||
710 | * @see eina_value_setup() | ||
711 | * @see eina_value_free() | ||
712 | * | ||
713 | * @since 1.2 | ||
714 | */ | ||
715 | static inline void eina_value_flush(Eina_Value *value) EINA_ARG_NONNULL(1); | ||
716 | |||
717 | /** | ||
718 | * @brief Copy generic value storage. | ||
719 | * @param value source value object | ||
720 | * @param copy destination value object | ||
721 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
722 | * | ||
723 | * The @a copy object is considered uninitialized and its existing | ||
724 | * contents are overwritten (just as if eina_value_flush() was called on | ||
725 | * it). | ||
726 | * | ||
727 | * The copy happens by calling eina_value_setup() on @a copy, followed | ||
728 | * by getting the contents of @a value and setting it to @a copy. | ||
729 | * | ||
730 | * @since 1.2 | ||
731 | */ | ||
732 | EAPI Eina_Bool eina_value_copy(const Eina_Value *value, | ||
733 | Eina_Value *copy) EINA_ARG_NONNULL(1, 2); | ||
734 | |||
735 | /** | ||
736 | * @brief Compare generic value storage. | ||
737 | * @param a left side of comparison | ||
738 | * @param b right side of comparison | ||
739 | * @return less than zero if a < b, greater than zero if a > b, zero | ||
740 | * if a == b | ||
741 | * | ||
742 | * @since 1.2 | ||
743 | */ | ||
744 | static inline int eina_value_compare(const Eina_Value *a, | ||
745 | const Eina_Value *b) EINA_ARG_NONNULL(1, 2); | ||
746 | |||
747 | /** | ||
748 | * @brief Set the generic value. | ||
749 | * @param value source value object | ||
750 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
751 | * | ||
752 | * The variable argument is dependent on chosen type. The list for | ||
753 | * basic types: | ||
754 | * | ||
755 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
756 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
757 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
758 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
759 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
760 | * @li EINA_VALUE_TYPE_CHAR: char | ||
761 | * @li EINA_VALUE_TYPE_SHORT: short | ||
762 | * @li EINA_VALUE_TYPE_INT: int | ||
763 | * @li EINA_VALUE_TYPE_LONG: long | ||
764 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
765 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
766 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
767 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
768 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
769 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
770 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
771 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
772 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
773 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
774 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
775 | * | ||
776 | * @code | ||
777 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
778 | * int x = 567; | ||
779 | * eina_value_set(value, 1234); | ||
780 | * eina_value_set(value, x); | ||
781 | * | ||
782 | * eina_value_flush(value); | ||
783 | * | ||
784 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
785 | * eina_value_set(value, "hello world!"); | ||
786 | * | ||
787 | * eina_value_free(value); | ||
788 | * @endcode | ||
789 | * | ||
790 | * @note for array member see eina_value_array_set() | ||
791 | * @note for list member see eina_value_list_set() | ||
792 | * @note for hash member see eina_value_hash_set() | ||
793 | * | ||
794 | * @see eina_value_get() | ||
795 | * @see eina_value_vset() | ||
796 | * @see eina_value_pset() | ||
797 | * | ||
798 | * @since 1.2 | ||
799 | */ | ||
800 | static inline Eina_Bool eina_value_set(Eina_Value *value, | ||
801 | ...) EINA_ARG_NONNULL(1); | ||
802 | |||
803 | /** | ||
804 | * @brief Get the generic value. | ||
805 | * @param value source value object | ||
806 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
807 | * | ||
808 | * The value is returned in the variable argument parameter, the | ||
809 | * actual value is type-dependent, but usually it will be what is | ||
810 | * stored inside the object. There shouldn't be any memory allocation, | ||
811 | * thus the contents should @b not be freed. | ||
812 | * | ||
813 | * The variable argument is dependent on chosen type. The list for | ||
814 | * basic types: | ||
815 | * | ||
816 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
817 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
818 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
819 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
820 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
821 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
822 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
823 | * @li EINA_VALUE_TYPE_INT: int* | ||
824 | * @li EINA_VALUE_TYPE_LONG: long* | ||
825 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
826 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
827 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
828 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
829 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
830 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
831 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
832 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
833 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
834 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
835 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
836 | * | ||
837 | * @code | ||
838 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
839 | * int x; | ||
840 | * const char *s; | ||
841 | * | ||
842 | * eina_value_set(value, 1234); | ||
843 | * eina_value_get(value, &x); | ||
844 | * | ||
845 | * eina_value_flush(value); | ||
846 | * | ||
847 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
848 | * eina_value_set(value, "hello world!"); | ||
849 | * eina_value_get(value, &s); | ||
850 | * | ||
851 | * eina_value_free(value); | ||
852 | * @endcode | ||
853 | * | ||
854 | * @note for array member see eina_value_array_get() | ||
855 | * @note for list member see eina_value_list_get() | ||
856 | * @note for hash member see eina_value_hash_get() | ||
857 | * | ||
858 | * @see eina_value_set() | ||
859 | * @see eina_value_vset() | ||
860 | * @see eina_value_pset() | ||
861 | * | ||
862 | * @since 1.2 | ||
863 | */ | ||
864 | static inline Eina_Bool eina_value_get(const Eina_Value *value, | ||
865 | ...) EINA_ARG_NONNULL(1); | ||
866 | |||
867 | /** | ||
868 | * @brief Set the generic value. | ||
869 | * @param value source value object | ||
870 | * @param args variable argument | ||
871 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
872 | * | ||
873 | * @note for array member see eina_value_array_vset() | ||
874 | * @note for list member see eina_value_list_vset() | ||
875 | * @note for hash member see eina_value_hash_vset() | ||
876 | * | ||
877 | * @see eina_value_vget() | ||
878 | * @see eina_value_set() | ||
879 | * @see eina_value_pset() | ||
880 | * | ||
881 | * @since 1.2 | ||
882 | */ | ||
883 | static inline Eina_Bool eina_value_vset(Eina_Value *value, | ||
884 | va_list args) EINA_ARG_NONNULL(1); | ||
885 | |||
886 | /** | ||
887 | * @brief Get the generic value. | ||
888 | * @param value source value object | ||
889 | * @param args variable argument | ||
890 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
891 | * | ||
892 | * The value is returned in the variable argument parameter, the | ||
893 | * actual value is type-dependent, but usually it will be what is | ||
894 | * stored inside the object. There shouldn't be any memory allocation, | ||
895 | * thus the contents should @b not be freed. | ||
896 | * | ||
897 | * @note for array member see eina_value_array_vget() | ||
898 | * @note for list member see eina_value_list_vget() | ||
899 | * @note for hash member see eina_value_hash_vget() | ||
900 | * | ||
901 | * @see eina_value_vset() | ||
902 | * @see eina_value_get() | ||
903 | * @see eina_value_pget() | ||
904 | * | ||
905 | * @since 1.2 | ||
906 | */ | ||
907 | static inline Eina_Bool eina_value_vget(const Eina_Value *value, | ||
908 | va_list args) EINA_ARG_NONNULL(1); | ||
909 | |||
910 | /** | ||
911 | * @brief Set the generic value from pointer. | ||
912 | * @param value source value object | ||
913 | * @param ptr pointer to specify the contents. | ||
914 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
915 | * | ||
916 | * The pointer type is dependent on chosen value type. The list for | ||
917 | * basic types: | ||
918 | * | ||
919 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
920 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
921 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
922 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
923 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
924 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
925 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
926 | * @li EINA_VALUE_TYPE_INT: int* | ||
927 | * @li EINA_VALUE_TYPE_LONG: long* | ||
928 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
929 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
930 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
931 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
932 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
933 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
934 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
935 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
936 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
937 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
938 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
939 | * | ||
940 | * @note the pointer contents are written using the size defined by | ||
941 | * type. It can be larger than void* or uint64_t. | ||
942 | * | ||
943 | * @code | ||
944 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
945 | * int x = 567; | ||
946 | * const char *s = "hello world!"; | ||
947 | * | ||
948 | * eina_value_pset(value, &x); | ||
949 | * | ||
950 | * eina_value_flush(value); | ||
951 | * | ||
952 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
953 | * eina_value_pset(value, &s); | ||
954 | * | ||
955 | * eina_value_free(value); | ||
956 | * @endcode | ||
957 | * | ||
958 | * @note for array member see eina_value_array_pset() | ||
959 | * @note for list member see eina_value_list_pset() | ||
960 | * @note for hash member see eina_value_hash_pset() | ||
961 | * | ||
962 | * @see eina_value_pget() | ||
963 | * @see eina_value_set() | ||
964 | * @see eina_value_vset() | ||
965 | * | ||
966 | * @since 1.2 | ||
967 | */ | ||
968 | static inline Eina_Bool eina_value_pset(Eina_Value *value, | ||
969 | const void *ptr) EINA_ARG_NONNULL(1, 2); | ||
970 | |||
971 | /** | ||
972 | * @brief Get the generic value to pointer. | ||
973 | * @param value source value object | ||
974 | * @param ptr pointer to receive the contents. | ||
975 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
976 | * | ||
977 | * The value is returned in pointer contents, the actual value is | ||
978 | * type-dependent, but usually it will be what is stored inside the | ||
979 | * object. There shouldn't be any memory allocation, thus the contents | ||
980 | * should @b not be freed. | ||
981 | * | ||
982 | * The pointer type is dependent on chosen value type. The list for | ||
983 | * basic types: | ||
984 | * | ||
985 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
986 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
987 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
988 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
989 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
990 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
991 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
992 | * @li EINA_VALUE_TYPE_INT: int* | ||
993 | * @li EINA_VALUE_TYPE_LONG: long* | ||
994 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
995 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
996 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
997 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
998 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
999 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1000 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1001 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1002 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1003 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1004 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1005 | * | ||
1006 | * @code | ||
1007 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
1008 | * int x; | ||
1009 | * const char *s; | ||
1010 | * | ||
1011 | * eina_value_set(value, 1234); | ||
1012 | * eina_value_pget(value, &x); | ||
1013 | * | ||
1014 | * eina_value_flush(value); | ||
1015 | * | ||
1016 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
1017 | * eina_value_set(value, "hello world!"); | ||
1018 | * eina_value_pget(value, &s); | ||
1019 | * | ||
1020 | * eina_value_free(value); | ||
1021 | * @endcode | ||
1022 | * | ||
1023 | * @note for array member see eina_value_array_get() | ||
1024 | * @note for list member see eina_value_list_get() | ||
1025 | * @note for hash member see eina_value_hash_get() | ||
1026 | * | ||
1027 | * @see eina_value_set() | ||
1028 | * @see eina_value_vset() | ||
1029 | * @see eina_value_pset() | ||
1030 | * | ||
1031 | * @since 1.2 | ||
1032 | */ | ||
1033 | static inline Eina_Bool eina_value_pget(const Eina_Value *value, | ||
1034 | void *ptr) EINA_ARG_NONNULL(1, 2); | ||
1035 | |||
1036 | /** | ||
1037 | * @brief Convert one value to another type. | ||
1038 | * @param value source value object. | ||
1039 | * @param convert destination value object. | ||
1040 | * @return #EINA_TRUE if converted, #EINA_FALSE otherwise. | ||
1041 | * | ||
1042 | * Converts one value to another trying first @a value type | ||
1043 | * @c convert_to() function. If unsuccessful, tries using @c convert_from() | ||
1044 | * function in @a convert. | ||
1045 | * | ||
1046 | * Conversion functions are type defined, and the basic types can convert | ||
1047 | * between themselves, but conversion is strict! That is, if | ||
1048 | * converting from negative value to unsigned type, it will fail. It | ||
1049 | * also fails on value overflow. | ||
1050 | * | ||
1051 | * It is recommended that all types implement at least convert to | ||
1052 | * string, used by eina_value_to_string(). | ||
1053 | * | ||
1054 | * @note Both objects must have eina_value_setup() called on them beforehand! | ||
1055 | * | ||
1056 | * @since 1.2 | ||
1057 | */ | ||
1058 | EAPI Eina_Bool eina_value_convert(const Eina_Value *value, | ||
1059 | Eina_Value *convert) EINA_ARG_NONNULL(1, 2); | ||
1060 | |||
1061 | |||
1062 | /** | ||
1063 | * @brief Convert value to string. | ||
1064 | * @param value value object. | ||
1065 | * @return newly allocated memory or @c NULL on failure. | ||
1066 | * | ||
1067 | * @see eina_value_convert() | ||
1068 | * @since 1.2 | ||
1069 | */ | ||
1070 | EAPI char *eina_value_to_string(const Eina_Value *value) EINA_ARG_NONNULL(1); | ||
1071 | |||
1072 | /** | ||
1073 | * @brief Query value type. | ||
1074 | * @param value value object. | ||
1075 | * @return type instance or @c NULL if type is invalid. | ||
1076 | * | ||
1077 | * Check if value type is valid and returns it. A type is invalid if | ||
1078 | * it does not exist or if it is using a different version field. | ||
1079 | * | ||
1080 | * @see eina_value_type_check() | ||
1081 | * | ||
1082 | * @since 1.2 | ||
1083 | */ | ||
1084 | static inline const Eina_Value_Type *eina_value_type_get(const Eina_Value *value) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
1085 | |||
1086 | /** | ||
1087 | * @} | ||
1088 | */ | ||
1089 | |||
1090 | |||
1091 | /** | ||
1092 | * @defgroup Eina_Value_Array_Group Generic Value Array management | ||
1093 | * | ||
1094 | * @{ | ||
1095 | */ | ||
1096 | |||
1097 | |||
1098 | /** | ||
1099 | * @typedef Eina_Value_Array | ||
1100 | * Value type for #EINA_VALUE_TYPE_ARRAY. | ||
1101 | * | ||
1102 | * @see #_Eina_Value_Array explains fields. | ||
1103 | * @since 1.2 | ||
1104 | */ | ||
1105 | typedef struct _Eina_Value_Array Eina_Value_Array; | ||
1106 | |||
1107 | /** | ||
1108 | * @struct _Eina_Value_Array | ||
1109 | * Used to store the array and its subtype. | ||
1110 | * @since 1.2 | ||
1111 | */ | ||
1112 | struct _Eina_Value_Array | ||
1113 | { | ||
1114 | const Eina_Value_Type *subtype; /**< how to allocate and access items */ | ||
1115 | unsigned int step; /**< how to grow the members array */ | ||
1116 | Eina_Inarray *array; /**< the array that holds data, members are of subtype->value_size bytes. */ | ||
1117 | }; | ||
1118 | |||
1119 | /** | ||
1120 | * @brief Create generic value storage of type array. | ||
1121 | * @param subtype how to manage this array members. | ||
1122 | * @param step how to grow the members array. | ||
1123 | * @return The new value or @c NULL on failure. | ||
1124 | * | ||
1125 | * Create a new generic value storage of type array. The members are | ||
1126 | * managed using the description specified by @a subtype. | ||
1127 | * | ||
1128 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
1129 | * #EINA_ERROR_VALUE_FAILED is set. | ||
1130 | * | ||
1131 | * @note this creates from mempool and then uses | ||
1132 | * eina_value_array_setup(). @see eina_value_free() @see | ||
1133 | * eina_value_array_setup() | ||
1134 | * | ||
1135 | * @since 1.2 | ||
1136 | */ | ||
1137 | EAPI Eina_Value *eina_value_array_new(const Eina_Value_Type *subtype, | ||
1138 | unsigned int step) EINA_ARG_NONNULL(1); | ||
1139 | |||
1140 | /** | ||
1141 | * @brief Initialize generic value storage of type array. | ||
1142 | * @param value value object | ||
1143 | * @param subtype how to manage array members. | ||
1144 | * @param step how to grow the members array. | ||
1145 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1146 | * | ||
1147 | * Initializes new generic value storage of type array with the given | ||
1148 | * @a subtype. | ||
1149 | * | ||
1150 | * This is the same as calling eina_value_set() with | ||
1151 | * #EINA_VALUE_TYPE_ARRAY followed by eina_value_pset() with the | ||
1152 | * #Eina_Value_Array description configured. | ||
1153 | * | ||
1154 | * @note Existing contents are ignored! If the value was previously used, then | ||
1155 | * use eina_value_flush() first. | ||
1156 | * | ||
1157 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
1158 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
1159 | * | ||
1160 | * @see eina_value_flush() | ||
1161 | * | ||
1162 | * @since 1.2 | ||
1163 | */ | ||
1164 | static inline Eina_Bool eina_value_array_setup(Eina_Value *value, | ||
1165 | const Eina_Value_Type *subtype, | ||
1166 | unsigned int step) EINA_ARG_NONNULL(1, 2); | ||
1167 | |||
1168 | /** | ||
1169 | * @brief Query number of elements in value of array type. | ||
1170 | * @param value value object. | ||
1171 | * @return number of child elements. | ||
1172 | * @since 1.2 | ||
1173 | */ | ||
1174 | static inline unsigned int eina_value_array_count(const Eina_Value *value); | ||
1175 | |||
1176 | /** | ||
1177 | * @brief Remove element at given position in value of array type. | ||
1178 | * @param value value object. | ||
1179 | * @param position index of the member | ||
1180 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1181 | * @since 1.2 | ||
1182 | */ | ||
1183 | static inline Eina_Bool eina_value_array_remove(Eina_Value *value, | ||
1184 | unsigned int position) EINA_ARG_NONNULL(1); | ||
1185 | |||
1186 | /** | ||
1187 | * @brief Set the generic value in an array member. | ||
1188 | * @param value source value object | ||
1189 | * @param position index of the member | ||
1190 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1191 | * | ||
1192 | * The variable argument is dependent on chosen subtype. The list for | ||
1193 | * basic types: | ||
1194 | * | ||
1195 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1196 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1197 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1198 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1199 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1200 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1201 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1202 | * @li EINA_VALUE_TYPE_INT: int | ||
1203 | * @li EINA_VALUE_TYPE_LONG: long | ||
1204 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1205 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1206 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1207 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1208 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1209 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
1210 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1211 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1212 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1213 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1214 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1215 | * | ||
1216 | * @code | ||
1217 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1218 | * int x; | ||
1219 | * | ||
1220 | * eina_value_array_append(value, 1234); | ||
1221 | * eina_value_array_set(value, 0, 5678); | ||
1222 | * eina_value_array_get(value, 0, &x); | ||
1223 | * eina_value_free(value); | ||
1224 | * @endcode | ||
1225 | * | ||
1226 | * @see eina_value_array_get() | ||
1227 | * @see eina_value_array_vset() | ||
1228 | * @see eina_value_array_pset() | ||
1229 | * @see eina_value_array_insert() | ||
1230 | * @see eina_value_array_vinsert() | ||
1231 | * @see eina_value_array_pinsert() | ||
1232 | * @see eina_value_array_append() | ||
1233 | * @see eina_value_array_vappend() | ||
1234 | * @see eina_value_array_pappend() | ||
1235 | * | ||
1236 | * @since 1.2 | ||
1237 | */ | ||
1238 | static inline Eina_Bool eina_value_array_set(Eina_Value *value, | ||
1239 | unsigned int position, | ||
1240 | ...) EINA_ARG_NONNULL(1); | ||
1241 | |||
1242 | /** | ||
1243 | * @brief Get the generic value from an array member. | ||
1244 | * @param value source value object | ||
1245 | * @param position index of the member | ||
1246 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1247 | * | ||
1248 | * The value is returned in the variable argument parameter, and the | ||
1249 | * actual value is type-dependent, but usually it will be what is | ||
1250 | * stored inside the object. There shouldn't be any memory allocation; | ||
1251 | * thus the contents should @b not be freed. | ||
1252 | * | ||
1253 | * The variable argument is dependent on chosen subtype. The list for | ||
1254 | * basic types: | ||
1255 | * | ||
1256 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1257 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1258 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1259 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1260 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1261 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1262 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1263 | * @li EINA_VALUE_TYPE_INT: int* | ||
1264 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1265 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1266 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1267 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1268 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1269 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1270 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1271 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1272 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1273 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1274 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1275 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1276 | * | ||
1277 | * @code | ||
1278 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1279 | * int x; | ||
1280 | * | ||
1281 | * eina_value_array_append(value, 1234); | ||
1282 | * eina_value_array_get(value, 0, &x); | ||
1283 | * eina_value_free(value); | ||
1284 | * @endcode | ||
1285 | * | ||
1286 | * @see eina_value_array_set() | ||
1287 | * @see eina_value_array_vset() | ||
1288 | * @see eina_value_array_pset() | ||
1289 | * | ||
1290 | * @since 1.2 | ||
1291 | */ | ||
1292 | static inline Eina_Bool eina_value_array_get(const Eina_Value *value, | ||
1293 | unsigned int position, | ||
1294 | ...) EINA_ARG_NONNULL(1); | ||
1295 | |||
1296 | /** | ||
1297 | * @brief Insert a generic value in an array member position. | ||
1298 | * @param value source value object | ||
1299 | * @param position index of the member | ||
1300 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1301 | * | ||
1302 | * The variable argument is dependent on chosen subtype. The list for | ||
1303 | * basic types: | ||
1304 | * | ||
1305 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1306 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1307 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1308 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1309 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1310 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1311 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1312 | * @li EINA_VALUE_TYPE_INT: int | ||
1313 | * @li EINA_VALUE_TYPE_LONG: long | ||
1314 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1315 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1316 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1317 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1318 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1319 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
1320 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1321 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1322 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1323 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1324 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1325 | * | ||
1326 | * @code | ||
1327 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1328 | * int x; | ||
1329 | * | ||
1330 | * eina_value_array_insert(value, 0, 1234); | ||
1331 | * eina_value_array_get(value, 0, &x); | ||
1332 | * eina_value_free(value); | ||
1333 | * @endcode | ||
1334 | * | ||
1335 | * @see eina_value_array_set() | ||
1336 | * @see eina_value_array_get() | ||
1337 | * @see eina_value_array_vset() | ||
1338 | * @see eina_value_array_pset() | ||
1339 | * @see eina_value_array_vinsert() | ||
1340 | * @see eina_value_array_pinsert() | ||
1341 | * @see eina_value_array_append() | ||
1342 | * @see eina_value_array_vappend() | ||
1343 | * @see eina_value_array_pappend() | ||
1344 | * | ||
1345 | * @since 1.2 | ||
1346 | */ | ||
1347 | static inline Eina_Bool eina_value_array_insert(Eina_Value *value, | ||
1348 | unsigned int position, | ||
1349 | ...) EINA_ARG_NONNULL(1); | ||
1350 | |||
1351 | |||
1352 | /** | ||
1353 | * @brief Append a generic value in an array. | ||
1354 | * @param value source value object | ||
1355 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1356 | * | ||
1357 | * The variable argument is dependent on chosen subtype. The list for | ||
1358 | * basic types: | ||
1359 | * | ||
1360 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1361 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1362 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1363 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1364 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1365 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1366 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1367 | * @li EINA_VALUE_TYPE_INT: int | ||
1368 | * @li EINA_VALUE_TYPE_LONG: long | ||
1369 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1370 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1371 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1372 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1373 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1374 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
1375 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1376 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1377 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1378 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1379 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1380 | * | ||
1381 | * @code | ||
1382 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1383 | * int x; | ||
1384 | * | ||
1385 | * eina_value_array_append(value, 1234); | ||
1386 | * eina_value_array_get(value, 0, &x); | ||
1387 | * eina_value_free(value); | ||
1388 | * @endcode | ||
1389 | * | ||
1390 | * @see eina_value_array_set() | ||
1391 | * @see eina_value_array_get() | ||
1392 | * @see eina_value_array_vset() | ||
1393 | * @see eina_value_array_pset() | ||
1394 | * @see eina_value_array_vinsert() | ||
1395 | * @see eina_value_array_pinsert() | ||
1396 | * @see eina_value_array_append() | ||
1397 | * @see eina_value_array_vappend() | ||
1398 | * @see eina_value_array_pappend() | ||
1399 | * | ||
1400 | * @since 1.2 | ||
1401 | */ | ||
1402 | static inline Eina_Bool eina_value_array_append(Eina_Value *value, | ||
1403 | ...) EINA_ARG_NONNULL(1); | ||
1404 | |||
1405 | /** | ||
1406 | * @brief Set a generic value to an array member. | ||
1407 | * @param value source value object | ||
1408 | * @param position index of the member | ||
1409 | * @param args variable argument | ||
1410 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1411 | * @see eina_value_array_set() | ||
1412 | * @see eina_value_array_get() | ||
1413 | * @see eina_value_array_pset() | ||
1414 | * @see eina_value_array_insert() | ||
1415 | * @see eina_value_array_vinsert() | ||
1416 | * @see eina_value_array_pinsert() | ||
1417 | * @see eina_value_array_append() | ||
1418 | * @see eina_value_array_vappend() | ||
1419 | * @see eina_value_array_pappend() | ||
1420 | * | ||
1421 | * @since 1.2 | ||
1422 | */ | ||
1423 | static inline Eina_Bool eina_value_array_vset(Eina_Value *value, | ||
1424 | unsigned int position, | ||
1425 | va_list args) EINA_ARG_NONNULL(1); | ||
1426 | |||
1427 | /** | ||
1428 | * @brief Get the generic value from an array member. | ||
1429 | * @param value source value object | ||
1430 | * @param position index of the member | ||
1431 | * @param args variable argument | ||
1432 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1433 | * | ||
1434 | * The value is returned in the variable argument parameter, the | ||
1435 | * actual value is type-dependent, but usually it will be what is | ||
1436 | * stored inside the object. There shouldn't be any memory allocation, | ||
1437 | * thus the contents should @b not be freed. | ||
1438 | * | ||
1439 | * @see eina_value_array_vset() | ||
1440 | * @see eina_value_array_get() | ||
1441 | * @see eina_value_array_pget() | ||
1442 | * | ||
1443 | * @since 1.2 | ||
1444 | */ | ||
1445 | static inline Eina_Bool eina_value_array_vget(const Eina_Value *value, | ||
1446 | unsigned int position, | ||
1447 | va_list args) EINA_ARG_NONNULL(1); | ||
1448 | /** | ||
1449 | * @brief Insert a generic value to an array member position. | ||
1450 | * @param value source value object | ||
1451 | * @param position index of the member | ||
1452 | * @param args variable argument | ||
1453 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1454 | * @see eina_value_array_set() | ||
1455 | * @see eina_value_array_get() | ||
1456 | * @see eina_value_array_vset() | ||
1457 | * @see eina_value_array_pset() | ||
1458 | * @see eina_value_array_insert() | ||
1459 | * @see eina_value_array_pinsert() | ||
1460 | * @see eina_value_array_append() | ||
1461 | * @see eina_value_array_vappend() | ||
1462 | * @see eina_value_array_pappend() | ||
1463 | * | ||
1464 | * @since 1.2 | ||
1465 | */ | ||
1466 | static inline Eina_Bool eina_value_array_vinsert(Eina_Value *value, | ||
1467 | unsigned int position, | ||
1468 | va_list args) EINA_ARG_NONNULL(1); | ||
1469 | |||
1470 | /** | ||
1471 | * @brief Append a generic value to an array. | ||
1472 | * @param value source value object | ||
1473 | * @param args variable argument | ||
1474 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1475 | * @see eina_value_array_set() | ||
1476 | * @see eina_value_array_get() | ||
1477 | * @see eina_value_array_vget() | ||
1478 | * @see eina_value_array_pset() | ||
1479 | * @see eina_value_array_insert() | ||
1480 | * @see eina_value_array_vinsert() | ||
1481 | * @see eina_value_array_pinsert() | ||
1482 | * @see eina_value_array_append() | ||
1483 | * @see eina_value_array_pappend() | ||
1484 | * | ||
1485 | * @since 1.2 | ||
1486 | */ | ||
1487 | static inline Eina_Bool eina_value_array_vappend(Eina_Value *value, | ||
1488 | va_list args) EINA_ARG_NONNULL(1); | ||
1489 | |||
1490 | |||
1491 | /** | ||
1492 | * @brief Set a generic value to an array member from a pointer. | ||
1493 | * @param value source value object | ||
1494 | * @param position index of the member | ||
1495 | * @param ptr pointer to specify the contents. | ||
1496 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1497 | * | ||
1498 | * The pointer type is dependent on chosen value type. The list for | ||
1499 | * basic types: | ||
1500 | * | ||
1501 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1502 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1503 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1504 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1505 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1506 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1507 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1508 | * @li EINA_VALUE_TYPE_INT: int* | ||
1509 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1510 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1511 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1512 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1513 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1514 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1515 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1516 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1517 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1518 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1519 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1520 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1521 | * | ||
1522 | * @note the pointer contents are written using the size defined by | ||
1523 | * type. It can be larger than void* or uint64_t. | ||
1524 | * | ||
1525 | * @code | ||
1526 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1527 | * int x = 1234; | ||
1528 | * | ||
1529 | * eina_value_array_append(value, 1234); | ||
1530 | * eina_value_array_pset(value, 0, &x); | ||
1531 | * eina_value_array_pget(value, 0, &x); | ||
1532 | * eina_value_free(value); | ||
1533 | * @endcode | ||
1534 | * | ||
1535 | * @see eina_value_array_set() | ||
1536 | * @see eina_value_array_get() | ||
1537 | * @see eina_value_array_vset() | ||
1538 | * @see eina_value_array_insert() | ||
1539 | * @see eina_value_array_vinsert() | ||
1540 | * @see eina_value_array_pinsert() | ||
1541 | * @see eina_value_array_append() | ||
1542 | * @see eina_value_array_vappend() | ||
1543 | * @see eina_value_array_pappend() | ||
1544 | * | ||
1545 | * @since 1.2 | ||
1546 | */ | ||
1547 | static inline Eina_Bool eina_value_array_pset(Eina_Value *value, | ||
1548 | unsigned int position, | ||
1549 | const void *ptr) EINA_ARG_NONNULL(1, 3); | ||
1550 | |||
1551 | /** | ||
1552 | * @brief Retrieve a generic value into a pointer from an array member. | ||
1553 | * @param value source value object | ||
1554 | * @param position index of the member | ||
1555 | * @param ptr pointer to receive the contents. | ||
1556 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1557 | * | ||
1558 | * The value is returned in pointer contents, the actual value is | ||
1559 | * type-dependent, but usually it will be what is stored inside the | ||
1560 | * object. There shouldn't be any memory allocation, thus the contents | ||
1561 | * should @b not be freed. | ||
1562 | * | ||
1563 | * The pointer type is dependent on chosen value type. The list for | ||
1564 | * basic types: | ||
1565 | * | ||
1566 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1567 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1568 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1569 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1570 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1571 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1572 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1573 | * @li EINA_VALUE_TYPE_INT: int* | ||
1574 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1575 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1576 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1577 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1578 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1579 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1580 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1581 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1582 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1583 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1584 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1585 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1586 | * | ||
1587 | * @code | ||
1588 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1589 | * int x; | ||
1590 | * | ||
1591 | * eina_value_array_append(value, 1234); | ||
1592 | * eina_value_array_pget(value, 0, &x); | ||
1593 | * eina_value_free(value); | ||
1594 | * @endcode | ||
1595 | * | ||
1596 | * @see eina_value_array_set() | ||
1597 | * @see eina_value_array_vset() | ||
1598 | * @see eina_value_array_pset() | ||
1599 | * | ||
1600 | * @since 1.2 | ||
1601 | */ | ||
1602 | static inline Eina_Bool eina_value_array_pget(const Eina_Value *value, | ||
1603 | unsigned int position, | ||
1604 | void *ptr) EINA_ARG_NONNULL(1, 3); | ||
1605 | |||
1606 | /** | ||
1607 | * @brief Insert a generic value to an array member position from a pointer. | ||
1608 | * @param value source value object | ||
1609 | * @param position index of the member | ||
1610 | * @param ptr pointer to specify the contents. | ||
1611 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1612 | * | ||
1613 | * The pointer type is dependent on chosen value type. The list for | ||
1614 | * basic types: | ||
1615 | * | ||
1616 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1617 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1618 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1619 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1620 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1621 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1622 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1623 | * @li EINA_VALUE_TYPE_INT: int* | ||
1624 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1625 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1626 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1627 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1628 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1629 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1630 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1631 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1632 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1633 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1634 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1635 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1636 | * | ||
1637 | * @note the pointer contents are written using the size defined by | ||
1638 | * type. It can be larger than void* or uint64_t. | ||
1639 | * | ||
1640 | * @code | ||
1641 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1642 | * int x = 1234; | ||
1643 | * | ||
1644 | * eina_value_array_pinsert(value, 0, &x); | ||
1645 | * eina_value_array_pget(value, 0, &x); | ||
1646 | * eina_value_free(value); | ||
1647 | * @endcode | ||
1648 | * | ||
1649 | * @see eina_value_array_set() | ||
1650 | * @see eina_value_array_get() | ||
1651 | * @see eina_value_array_vset() | ||
1652 | * @see eina_value_array_insert() | ||
1653 | * @see eina_value_array_vinsert() | ||
1654 | * @see eina_value_array_pinsert() | ||
1655 | * @see eina_value_array_append() | ||
1656 | * @see eina_value_array_vappend() | ||
1657 | * @see eina_value_array_pappend() | ||
1658 | * | ||
1659 | * @since 1.2 | ||
1660 | */ | ||
1661 | static inline Eina_Bool eina_value_array_pinsert(Eina_Value *value, | ||
1662 | unsigned int position, | ||
1663 | const void *ptr) EINA_ARG_NONNULL(1); | ||
1664 | |||
1665 | /** | ||
1666 | * @brief Append a generic value to an array from a pointer. | ||
1667 | * @param value source value object | ||
1668 | * @param ptr pointer to specify the contents. | ||
1669 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1670 | * | ||
1671 | * The pointer type is dependent on chosen value type. The list for | ||
1672 | * basic types: | ||
1673 | * | ||
1674 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1675 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1676 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1677 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1678 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1679 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1680 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1681 | * @li EINA_VALUE_TYPE_INT: int* | ||
1682 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1683 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1684 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1685 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1686 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1687 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1688 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1689 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1690 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1691 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1692 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1693 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1694 | * | ||
1695 | * @note the pointer contents are written using the size defined by | ||
1696 | * type. It can be larger than void* or uint64_t. | ||
1697 | * | ||
1698 | * @code | ||
1699 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1700 | * int x = 1234; | ||
1701 | * | ||
1702 | * eina_value_array_pappend(value, &x); | ||
1703 | * eina_value_array_pget(value, 0, &x); | ||
1704 | * eina_value_free(value); | ||
1705 | * @endcode | ||
1706 | * | ||
1707 | * @see eina_value_array_set() | ||
1708 | * @see eina_value_array_get() | ||
1709 | * @see eina_value_array_vset() | ||
1710 | * @see eina_value_array_insert() | ||
1711 | * @see eina_value_array_vinsert() | ||
1712 | * @see eina_value_array_pinsert() | ||
1713 | * @see eina_value_array_append() | ||
1714 | * @see eina_value_array_vappend() | ||
1715 | * @see eina_value_array_pappend() | ||
1716 | * | ||
1717 | * @since 1.2 | ||
1718 | */ | ||
1719 | static inline Eina_Bool eina_value_array_pappend(Eina_Value *value, | ||
1720 | const void *ptr) EINA_ARG_NONNULL(1); | ||
1721 | |||
1722 | /** | ||
1723 | * @brief Retrieves a value from the array as an Eina_Value copy. | ||
1724 | * @param value source value object | ||
1725 | * @param position index of the member | ||
1726 | * @param dst where to return the array member | ||
1727 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1728 | * | ||
1729 | * The argument @a dst is considered uninitialized and it's setup to | ||
1730 | * the type of the member. | ||
1731 | * | ||
1732 | * @since 1.2 | ||
1733 | */ | ||
1734 | static inline Eina_Bool eina_value_array_value_get(const Eina_Value *src, | ||
1735 | unsigned int position, | ||
1736 | Eina_Value *dst) EINA_ARG_NONNULL(1, 3); | ||
1737 | |||
1738 | /** | ||
1739 | * @} | ||
1740 | */ | ||
1741 | |||
1742 | |||
1743 | /** | ||
1744 | * @defgroup Eina_Value_List_Group Generic Value List management | ||
1745 | * | ||
1746 | * @{ | ||
1747 | */ | ||
1748 | |||
1749 | |||
1750 | /** | ||
1751 | * @typedef Eina_Value_List | ||
1752 | * Value type for #EINA_VALUE_TYPE_LIST. | ||
1753 | * | ||
1754 | * @see #_Eina_Value_List explains fields. | ||
1755 | * @since 1.2 | ||
1756 | */ | ||
1757 | typedef struct _Eina_Value_List Eina_Value_List; | ||
1758 | |||
1759 | /** | ||
1760 | * @struct _Eina_Value_List | ||
1761 | * Used to store the list and its subtype. | ||
1762 | * @since 1.2 | ||
1763 | */ | ||
1764 | struct _Eina_Value_List | ||
1765 | { | ||
1766 | const Eina_Value_Type *subtype; /**< how to allocate and access items */ | ||
1767 | Eina_List *list; /**< the list that holds data, members are of subtype->value_size bytes. */ | ||
1768 | }; | ||
1769 | |||
1770 | /** | ||
1771 | * @brief Create generic value storage of type list. | ||
1772 | * @param subtype how to manage this list members. | ||
1773 | * @return The new value or @c NULL on failure. | ||
1774 | * | ||
1775 | * Create a new generic value storage of type list. The members are | ||
1776 | * managed using the description specified by @a subtype. | ||
1777 | * | ||
1778 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
1779 | * #EINA_ERROR_VALUE_FAILED is set. | ||
1780 | * | ||
1781 | * @note this creates from mempool and then uses | ||
1782 | * eina_value_list_setup(). | ||
1783 | * | ||
1784 | * @see eina_value_free() | ||
1785 | * @see eina_value_list_setup() | ||
1786 | * | ||
1787 | * @since 1.2 | ||
1788 | */ | ||
1789 | EAPI Eina_Value *eina_value_list_new(const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1); | ||
1790 | |||
1791 | /** | ||
1792 | * @brief Initialize generic value storage of type list. | ||
1793 | * @param value value object | ||
1794 | * @param subtype how to manage this list members. | ||
1795 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1796 | * | ||
1797 | * Initializes new generic value storage of type list with the given | ||
1798 | * @a subtype. | ||
1799 | * | ||
1800 | * This is the same as calling eina_value_set() with | ||
1801 | * #EINA_VALUE_TYPE_LIST followed by eina_value_pset() with the | ||
1802 | * #Eina_Value_List description configured. | ||
1803 | * | ||
1804 | * @note Existing contents are ignored! If the value was previously used, then | ||
1805 | * use eina_value_flush() first. | ||
1806 | * | ||
1807 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
1808 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
1809 | * | ||
1810 | * @see eina_value_flush() | ||
1811 | * | ||
1812 | * @since 1.2 | ||
1813 | */ | ||
1814 | static inline Eina_Bool eina_value_list_setup(Eina_Value *value, | ||
1815 | const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1, 2); | ||
1816 | |||
1817 | /** | ||
1818 | * @brief Query number of elements in value of list type. | ||
1819 | * @param value value object. | ||
1820 | * @return number of child elements. | ||
1821 | * @since 1.2 | ||
1822 | */ | ||
1823 | static inline unsigned int eina_value_list_count(const Eina_Value *value); | ||
1824 | |||
1825 | /** | ||
1826 | * @brief Remove element at given position in value of list type. | ||
1827 | * @param value value object. | ||
1828 | * @param position index of the member | ||
1829 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1830 | * @since 1.2 | ||
1831 | */ | ||
1832 | static inline Eina_Bool eina_value_list_remove(Eina_Value *value, | ||
1833 | unsigned int position) EINA_ARG_NONNULL(1); | ||
1834 | |||
1835 | /** | ||
1836 | * @brief Set the generic value in an list member. | ||
1837 | * @param value source value object | ||
1838 | * @param position index of the member | ||
1839 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1840 | * | ||
1841 | * The variable argument is dependent on chosen subtype. The list for | ||
1842 | * basic types: | ||
1843 | * | ||
1844 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1845 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1846 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1847 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1848 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1849 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1850 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1851 | * @li EINA_VALUE_TYPE_INT: int | ||
1852 | * @li EINA_VALUE_TYPE_LONG: long | ||
1853 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1854 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1855 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1856 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1857 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1858 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1859 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1860 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1861 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1862 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1863 | * | ||
1864 | * @code | ||
1865 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1866 | * int x; | ||
1867 | * | ||
1868 | * eina_value_list_append(value, 1234); | ||
1869 | * eina_value_list_set(value, 0, 5678); | ||
1870 | * eina_value_list_get(value, 0, &x); | ||
1871 | * eina_value_free(value); | ||
1872 | * @endcode | ||
1873 | * | ||
1874 | * @see eina_value_list_get() | ||
1875 | * @see eina_value_list_vset() | ||
1876 | * @see eina_value_list_pset() | ||
1877 | * @see eina_value_list_insert() | ||
1878 | * @see eina_value_list_vinsert() | ||
1879 | * @see eina_value_list_pinsert() | ||
1880 | * @see eina_value_list_append() | ||
1881 | * @see eina_value_list_vappend() | ||
1882 | * @see eina_value_list_pappend() | ||
1883 | * | ||
1884 | * @since 1.2 | ||
1885 | */ | ||
1886 | static inline Eina_Bool eina_value_list_set(Eina_Value *value, | ||
1887 | unsigned int position, | ||
1888 | ...) EINA_ARG_NONNULL(1); | ||
1889 | |||
1890 | /** | ||
1891 | * @brief Get the generic value from an list member. | ||
1892 | * @param value source value object | ||
1893 | * @param position index of the member | ||
1894 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1895 | * | ||
1896 | * The value is returned in the variable argument parameter, the | ||
1897 | * actual value is type-dependent, but usually it will be what is | ||
1898 | * stored inside the object. There shouldn't be any memory allocation, | ||
1899 | * thus the contents should @b not be freed. | ||
1900 | * | ||
1901 | * The variable argument is dependent on chosen subtype. The list for | ||
1902 | * basic types: | ||
1903 | * | ||
1904 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1905 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1906 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1907 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1908 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1909 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1910 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1911 | * @li EINA_VALUE_TYPE_INT: int* | ||
1912 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1913 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1914 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1915 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1916 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1917 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1918 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1919 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1920 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1921 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1922 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1923 | * | ||
1924 | * @code | ||
1925 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1926 | * int x; | ||
1927 | * | ||
1928 | * eina_value_list_append(value, 1234); | ||
1929 | * eina_value_list_get(value, 0, &x); | ||
1930 | * eina_value_free(value); | ||
1931 | * @endcode | ||
1932 | * | ||
1933 | * @see eina_value_list_set() | ||
1934 | * @see eina_value_list_vset() | ||
1935 | * @see eina_value_list_pset() | ||
1936 | * | ||
1937 | * @since 1.2 | ||
1938 | */ | ||
1939 | static inline Eina_Bool eina_value_list_get(const Eina_Value *value, | ||
1940 | unsigned int position, | ||
1941 | ...) EINA_ARG_NONNULL(1); | ||
1942 | |||
1943 | /** | ||
1944 | * @brief Insert the generic value in an list member position. | ||
1945 | * @param value source value object | ||
1946 | * @param position index of the member | ||
1947 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1948 | * | ||
1949 | * The variable argument is dependent on chosen subtype. The list for | ||
1950 | * basic types: | ||
1951 | * | ||
1952 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1953 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1954 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1955 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1956 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1957 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1958 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1959 | * @li EINA_VALUE_TYPE_INT: int | ||
1960 | * @li EINA_VALUE_TYPE_LONG: long | ||
1961 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1962 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1963 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1964 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1965 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1966 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1967 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1968 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1969 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1970 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1971 | * | ||
1972 | * @code | ||
1973 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1974 | * int x; | ||
1975 | * | ||
1976 | * eina_value_list_insert(value, 0, 1234); | ||
1977 | * eina_value_list_get(value, 0, &x); | ||
1978 | * eina_value_free(value); | ||
1979 | * @endcode | ||
1980 | * | ||
1981 | * @see eina_value_list_set() | ||
1982 | * @see eina_value_list_get() | ||
1983 | * @see eina_value_list_vset() | ||
1984 | * @see eina_value_list_pset() | ||
1985 | * @see eina_value_list_vinsert() | ||
1986 | * @see eina_value_list_pinsert() | ||
1987 | * @see eina_value_list_append() | ||
1988 | * @see eina_value_list_vappend() | ||
1989 | * @see eina_value_list_pappend() | ||
1990 | * | ||
1991 | * @since 1.2 | ||
1992 | */ | ||
1993 | static inline Eina_Bool eina_value_list_insert(Eina_Value *value, | ||
1994 | unsigned int position, | ||
1995 | ...) EINA_ARG_NONNULL(1); | ||
1996 | |||
1997 | |||
1998 | /** | ||
1999 | * @brief Append the generic value in an list. | ||
2000 | * @param value source value object | ||
2001 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2002 | * | ||
2003 | * The variable argument is dependent on chosen subtype. The list for | ||
2004 | * basic types: | ||
2005 | * | ||
2006 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
2007 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
2008 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
2009 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
2010 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
2011 | * @li EINA_VALUE_TYPE_CHAR: char | ||
2012 | * @li EINA_VALUE_TYPE_SHORT: short | ||
2013 | * @li EINA_VALUE_TYPE_INT: int | ||
2014 | * @li EINA_VALUE_TYPE_LONG: long | ||
2015 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
2016 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
2017 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
2018 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
2019 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
2020 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
2021 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
2022 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
2023 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
2024 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
2025 | * | ||
2026 | * @code | ||
2027 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
2028 | * int x; | ||
2029 | * | ||
2030 | * eina_value_list_append(value, 1234); | ||
2031 | * eina_value_list_get(value, 0, &x); | ||
2032 | * eina_value_free(value); | ||
2033 | * @endcode | ||
2034 | * | ||
2035 | * @see eina_value_list_set() | ||
2036 | * @see eina_value_list_get() | ||
2037 | * @see eina_value_list_vset() | ||
2038 | * @see eina_value_list_pset() | ||
2039 | * @see eina_value_list_vinsert() | ||
2040 | * @see eina_value_list_pinsert() | ||
2041 | * @see eina_value_list_append() | ||
2042 | * @see eina_value_list_vappend() | ||
2043 | * @see eina_value_list_pappend() | ||
2044 | * | ||
2045 | * @since 1.2 | ||
2046 | */ | ||
2047 | static inline Eina_Bool eina_value_list_append(Eina_Value *value, | ||
2048 | ...) EINA_ARG_NONNULL(1); | ||
2049 | |||
2050 | /** | ||
2051 | * @brief Set the generic value in an list member. | ||
2052 | * @param value source value object | ||
2053 | * @param position index of the member | ||
2054 | * @param args variable argument | ||
2055 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2056 | * @see eina_value_list_set() | ||
2057 | * @see eina_value_list_get() | ||
2058 | * @see eina_value_list_pset() | ||
2059 | * @see eina_value_list_insert() | ||
2060 | * @see eina_value_list_vinsert() | ||
2061 | * @see eina_value_list_pinsert() | ||
2062 | * @see eina_value_list_append() | ||
2063 | * @see eina_value_list_vappend() | ||
2064 | * @see eina_value_list_pappend() | ||
2065 | * | ||
2066 | * @since 1.2 | ||
2067 | */ | ||
2068 | static inline Eina_Bool eina_value_list_vset(Eina_Value *value, | ||
2069 | unsigned int position, | ||
2070 | va_list args) EINA_ARG_NONNULL(1); | ||
2071 | |||
2072 | /** | ||
2073 | * @brief Get the generic value from an list member. | ||
2074 | * @param value source value object | ||
2075 | * @param position index of the member | ||
2076 | * @param args variable argument | ||
2077 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2078 | * | ||
2079 | * The value is returned in the variable argument parameter, the | ||
2080 | * actual value is type-dependent, but usually it will be what is | ||
2081 | * stored inside the object. There shouldn't be any memory allocation, | ||
2082 | * thus the contents should @b not be freed. | ||
2083 | * | ||
2084 | * @see eina_value_list_vset() | ||
2085 | * @see eina_value_list_get() | ||
2086 | * @see eina_value_list_pget() | ||
2087 | * | ||
2088 | * @since 1.2 | ||
2089 | */ | ||
2090 | static inline Eina_Bool eina_value_list_vget(const Eina_Value *value, | ||
2091 | unsigned int position, | ||
2092 | va_list args) EINA_ARG_NONNULL(1); | ||
2093 | /** | ||
2094 | * @brief Insert the generic value in an list member position. | ||
2095 | * @param value source value object | ||
2096 | * @param position index of the member | ||
2097 | * @param args variable argument | ||
2098 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2099 | * @see eina_value_list_set() | ||
2100 | * @see eina_value_list_get() | ||
2101 | * @see eina_value_list_vset() | ||
2102 | * @see eina_value_list_pset() | ||
2103 | * @see eina_value_list_insert() | ||
2104 | * @see eina_value_list_pinsert() | ||
2105 | * @see eina_value_list_append() | ||
2106 | * @see eina_value_list_vappend() | ||
2107 | * @see eina_value_list_pappend() | ||
2108 | * | ||
2109 | * @since 1.2 | ||
2110 | */ | ||
2111 | static inline Eina_Bool eina_value_list_vinsert(Eina_Value *value, | ||
2112 | unsigned int position, | ||
2113 | va_list args) EINA_ARG_NONNULL(1); | ||
2114 | |||
2115 | /** | ||
2116 | * @brief Append the generic value in an list. | ||
2117 | * @param value source value object | ||
2118 | * @param args variable argument | ||
2119 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2120 | * @see eina_value_list_set() | ||
2121 | * @see eina_value_list_get() | ||
2122 | * @see eina_value_list_vget() | ||
2123 | * @see eina_value_list_pset() | ||
2124 | * @see eina_value_list_insert() | ||
2125 | * @see eina_value_list_vinsert() | ||
2126 | * @see eina_value_list_pinsert() | ||
2127 | * @see eina_value_list_append() | ||
2128 | * @see eina_value_list_pappend() | ||
2129 | * | ||
2130 | * @since 1.2 | ||
2131 | */ | ||
2132 | static inline Eina_Bool eina_value_list_vappend(Eina_Value *value, | ||
2133 | va_list args) EINA_ARG_NONNULL(1); | ||
2134 | |||
2135 | |||
2136 | /** | ||
2137 | * @brief Set the generic value in an list member from pointer. | ||
2138 | * @param value source value object | ||
2139 | * @param position index of the member | ||
2140 | * @param ptr pointer to specify the contents. | ||
2141 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2142 | * | ||
2143 | * The pointer type is dependent on chosen value type. The list for | ||
2144 | * basic types: | ||
2145 | * | ||
2146 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2147 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2148 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2149 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2150 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2151 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2152 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2153 | * @li EINA_VALUE_TYPE_INT: int* | ||
2154 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2155 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2156 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2157 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2158 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2159 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2160 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
2161 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2162 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2163 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2164 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2165 | * | ||
2166 | * @note the pointer contents are written using the size defined by | ||
2167 | * type. It can be larger than void* or uint64_t. | ||
2168 | * | ||
2169 | * @code | ||
2170 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
2171 | * int x = 1234; | ||
2172 | * | ||
2173 | * eina_value_list_append(value, 1234); | ||
2174 | * eina_value_list_pset(value, 0, &x); | ||
2175 | * eina_value_list_pget(value, 0, &x); | ||
2176 | * eina_value_free(value); | ||
2177 | * @endcode | ||
2178 | * | ||
2179 | * @see eina_value_list_set() | ||
2180 | * @see eina_value_list_get() | ||
2181 | * @see eina_value_list_vset() | ||
2182 | * @see eina_value_list_insert() | ||
2183 | * @see eina_value_list_vinsert() | ||
2184 | * @see eina_value_list_pinsert() | ||
2185 | * @see eina_value_list_append() | ||
2186 | * @see eina_value_list_vappend() | ||
2187 | * @see eina_value_list_pappend() | ||
2188 | * | ||
2189 | * @since 1.2 | ||
2190 | */ | ||
2191 | static inline Eina_Bool eina_value_list_pset(Eina_Value *value, | ||
2192 | unsigned int position, | ||
2193 | const void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2194 | |||
2195 | /** | ||
2196 | * @brief Get the generic value to pointer from an list member. | ||
2197 | * @param value source value object | ||
2198 | * @param position index of the member | ||
2199 | * @param ptr pointer to receive the contents. | ||
2200 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2201 | * | ||
2202 | * The value is returned in pointer contents, the actual value is | ||
2203 | * type-dependent, but usually it will be what is stored inside the | ||
2204 | * object. There shouldn't be any memory allocation, thus the contents | ||
2205 | * should @b not be freed. | ||
2206 | * | ||
2207 | * The pointer type is dependent on chosen value type. The list for | ||
2208 | * basic types: | ||
2209 | * | ||
2210 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2211 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2212 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2213 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2214 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2215 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2216 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2217 | * @li EINA_VALUE_TYPE_INT: int* | ||
2218 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2219 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2220 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2221 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2222 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2223 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2224 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
2225 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2226 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2227 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2228 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2229 | * | ||
2230 | * @code | ||
2231 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
2232 | * int x; | ||
2233 | * | ||
2234 | * eina_value_list_append(value, 1234); | ||
2235 | * eina_value_list_pget(value, 0, &x); | ||
2236 | * eina_value_free(value); | ||
2237 | * @endcode | ||
2238 | * | ||
2239 | * @see eina_value_list_set() | ||
2240 | * @see eina_value_list_vset() | ||
2241 | * @see eina_value_list_pset() | ||
2242 | * | ||
2243 | * @since 1.2 | ||
2244 | */ | ||
2245 | static inline Eina_Bool eina_value_list_pget(const Eina_Value *value, | ||
2246 | unsigned int position, | ||
2247 | void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2248 | |||
2249 | /** | ||
2250 | * @brief Insert the generic value in an list member position from pointer. | ||
2251 | * @param value source value object | ||
2252 | * @param position index of the member | ||
2253 | * @param ptr pointer to specify the contents. | ||
2254 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2255 | * | ||
2256 | * The pointer type is dependent on chosen value type. The list for | ||
2257 | * basic types: | ||
2258 | * | ||
2259 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2260 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2261 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2262 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2263 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2264 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2265 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2266 | * @li EINA_VALUE_TYPE_INT: int* | ||
2267 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2268 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2269 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2270 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2271 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2272 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2273 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
2274 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2275 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2276 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2277 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2278 | * | ||
2279 | * @note the pointer contents are written using the size defined by | ||
2280 | * type. It can be larger than void* or uint64_t. | ||
2281 | * | ||
2282 | * @code | ||
2283 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
2284 | * int x = 1234; | ||
2285 | * | ||
2286 | * eina_value_list_pinsert(value, 0, &x); | ||
2287 | * eina_value_list_pget(value, 0, &x); | ||
2288 | * eina_value_free(value); | ||
2289 | * @endcode | ||
2290 | * | ||
2291 | * @see eina_value_list_set() | ||
2292 | * @see eina_value_list_get() | ||
2293 | * @see eina_value_list_vset() | ||
2294 | * @see eina_value_list_insert() | ||
2295 | * @see eina_value_list_vinsert() | ||
2296 | * @see eina_value_list_pinsert() | ||
2297 | * @see eina_value_list_append() | ||
2298 | * @see eina_value_list_vappend() | ||
2299 | * @see eina_value_list_pappend() | ||
2300 | * | ||
2301 | * @since 1.2 | ||
2302 | */ | ||
2303 | static inline Eina_Bool eina_value_list_pinsert(Eina_Value *value, | ||
2304 | unsigned int position, | ||
2305 | const void *ptr) EINA_ARG_NONNULL(1); | ||
2306 | |||
2307 | /** | ||
2308 | * @brief Append the generic value in an list from pointer. | ||
2309 | * @param value source value object | ||
2310 | * @param ptr pointer to specify the contents. | ||
2311 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2312 | * | ||
2313 | * The pointer type is dependent on chosen value type. The list for | ||
2314 | * basic types: | ||
2315 | * | ||
2316 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2317 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2318 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2319 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2320 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2321 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2322 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2323 | * @li EINA_VALUE_TYPE_INT: int* | ||
2324 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2325 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2326 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2327 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2328 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2329 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2330 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
2331 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2332 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2333 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2334 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2335 | * | ||
2336 | * @note the pointer contents are written using the size defined by | ||
2337 | * type. It can be larger than void* or uint64_t. | ||
2338 | * | ||
2339 | * @code | ||
2340 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
2341 | * int x = 1234; | ||
2342 | * | ||
2343 | * eina_value_list_pappend(value, &x); | ||
2344 | * eina_value_list_pget(value, 0, &x); | ||
2345 | * eina_value_free(value); | ||
2346 | * @endcode | ||
2347 | * | ||
2348 | * @see eina_value_list_set() | ||
2349 | * @see eina_value_list_get() | ||
2350 | * @see eina_value_list_vset() | ||
2351 | * @see eina_value_list_insert() | ||
2352 | * @see eina_value_list_vinsert() | ||
2353 | * @see eina_value_list_pinsert() | ||
2354 | * @see eina_value_list_append() | ||
2355 | * @see eina_value_list_vappend() | ||
2356 | * @see eina_value_list_pappend() | ||
2357 | * | ||
2358 | * @since 1.2 | ||
2359 | */ | ||
2360 | static inline Eina_Bool eina_value_list_pappend(Eina_Value *value, | ||
2361 | const void *ptr) EINA_ARG_NONNULL(1); | ||
2362 | |||
2363 | /** | ||
2364 | * @} | ||
2365 | */ | ||
2366 | |||
2367 | /** | ||
2368 | * @defgroup Eina_Value_Hash_Group Generic Value Hash management | ||
2369 | * | ||
2370 | * @{ | ||
2371 | */ | ||
2372 | |||
2373 | /** | ||
2374 | * @typedef Eina_Value_Hash | ||
2375 | * Value type for #EINA_VALUE_TYPE_HASH. | ||
2376 | * | ||
2377 | * @see #_Eina_Value_Hash explains fields. | ||
2378 | * @since 1.2 | ||
2379 | */ | ||
2380 | typedef struct _Eina_Value_Hash Eina_Value_Hash; | ||
2381 | |||
2382 | /** | ||
2383 | * @struct _Eina_Value_Hash | ||
2384 | * Used to store the hash and its subtype. | ||
2385 | * @since 1.2 | ||
2386 | */ | ||
2387 | struct _Eina_Value_Hash | ||
2388 | { | ||
2389 | const Eina_Value_Type *subtype; /**< how to allocate and access items */ | ||
2390 | unsigned int buckets_power_size; /**< how to allocate hash buckets, if zero a sane default is chosen. */ | ||
2391 | Eina_Hash *hash; /**< the hash that holds data, members are of subtype->value_size bytes. */ | ||
2392 | }; | ||
2393 | |||
2394 | /** | ||
2395 | * @brief Create generic value storage of type hash. | ||
2396 | * @param subtype how to manage this hash members. | ||
2397 | * @param buckets_power_size how to allocate hash buckets (2 ^ | ||
2398 | * buckets_power_size), if zero then a sane value is chosen. | ||
2399 | * @return The new value or @c NULL on failure. | ||
2400 | * | ||
2401 | * Create a new generic value storage of type hash. The members are | ||
2402 | * managed using the description specified by @a subtype. | ||
2403 | * | ||
2404 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
2405 | * #EINA_ERROR_VALUE_FAILED is set. | ||
2406 | * | ||
2407 | * @note this creates from mempool and then uses | ||
2408 | * eina_value_hash_setup(). | ||
2409 | * | ||
2410 | * @see eina_value_free() | ||
2411 | * @see eina_value_hash_setup() | ||
2412 | * | ||
2413 | * @since 1.2 | ||
2414 | */ | ||
2415 | EAPI Eina_Value *eina_value_hash_new(const Eina_Value_Type *subtype, unsigned int buckets_power_size) EINA_ARG_NONNULL(1); | ||
2416 | |||
2417 | /** | ||
2418 | * @brief Initialize generic value storage of type hash. | ||
2419 | * @param value value object | ||
2420 | * @param subtype how to manage this hash members. | ||
2421 | * @param buckets_power_size how to allocate hash buckets (2 ^ | ||
2422 | * buckets_power_size), if zero then a sane value is chosen. | ||
2423 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2424 | * | ||
2425 | * Initializes new generic value storage of type hash with the given | ||
2426 | * @a subtype. | ||
2427 | * | ||
2428 | * This is the same as calling eina_value_set() with | ||
2429 | * #EINA_VALUE_TYPE_HASH followed by eina_value_pset() with the | ||
2430 | * #Eina_Value_Hash description configured. | ||
2431 | * | ||
2432 | * @note Existing contents are ignored! If the value was previously used, then | ||
2433 | * use eina_value_flush() first. | ||
2434 | * | ||
2435 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
2436 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
2437 | * | ||
2438 | * @see eina_value_flush() | ||
2439 | * | ||
2440 | * @since 1.2 | ||
2441 | */ | ||
2442 | static inline Eina_Bool eina_value_hash_setup(Eina_Value *value, | ||
2443 | const Eina_Value_Type *subtype, | ||
2444 | unsigned int buckets_power_size) EINA_ARG_NONNULL(1, 2); | ||
2445 | |||
2446 | /** | ||
2447 | * @brief Query number of elements in value of hash type. | ||
2448 | * @param value value object. | ||
2449 | * @return number of child elements. | ||
2450 | * @since 1.2 | ||
2451 | */ | ||
2452 | static inline unsigned int eina_value_hash_population(const Eina_Value *value); | ||
2453 | |||
2454 | /** | ||
2455 | * @brief Remove element at given position in value of hash type. | ||
2456 | * @param value value object. | ||
2457 | * @param key key to find the member | ||
2458 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2459 | * @since 1.2 | ||
2460 | */ | ||
2461 | static inline Eina_Bool eina_value_hash_del(Eina_Value *value, | ||
2462 | const char *key) EINA_ARG_NONNULL(1); | ||
2463 | |||
2464 | /** | ||
2465 | * @brief Set the generic value in an hash member. | ||
2466 | * @param value source value object | ||
2467 | * @param key key to find the member | ||
2468 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2469 | * | ||
2470 | * The variable argument is dependent on chosen subtype. The list for | ||
2471 | * basic types: | ||
2472 | * | ||
2473 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
2474 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
2475 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
2476 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
2477 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
2478 | * @li EINA_VALUE_TYPE_CHAR: char | ||
2479 | * @li EINA_VALUE_TYPE_SHORT: short | ||
2480 | * @li EINA_VALUE_TYPE_INT: int | ||
2481 | * @li EINA_VALUE_TYPE_LONG: long | ||
2482 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
2483 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
2484 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
2485 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
2486 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
2487 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
2488 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2489 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2490 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2491 | * | ||
2492 | * @code | ||
2493 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2494 | * int x; | ||
2495 | * | ||
2496 | * eina_value_hash_set(value, "abc", 5678); | ||
2497 | * eina_value_hash_get(value, "abc", &x); | ||
2498 | * eina_value_free(value); | ||
2499 | * @endcode | ||
2500 | * | ||
2501 | * @see eina_value_hash_get() | ||
2502 | * @see eina_value_hash_vset() | ||
2503 | * @see eina_value_hash_pset() | ||
2504 | * @see eina_value_hash_del() | ||
2505 | * | ||
2506 | * @since 1.2 | ||
2507 | */ | ||
2508 | static inline Eina_Bool eina_value_hash_set(Eina_Value *value, | ||
2509 | const char *key, | ||
2510 | ...) EINA_ARG_NONNULL(1); | ||
2511 | |||
2512 | /** | ||
2513 | * @brief Get the generic value from an hash member. | ||
2514 | * @param value source value object | ||
2515 | * @param key key to find the member | ||
2516 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2517 | * | ||
2518 | * The value is returned in the variable argument parameter, the | ||
2519 | * actual value is type-dependent, but usually it will be what is | ||
2520 | * stored inside the object. There shouldn't be any memory allocation, | ||
2521 | * thus the contents should @b not be freed. | ||
2522 | * | ||
2523 | * The variable argument is dependent on chosen subtype. The list for | ||
2524 | * basic types: | ||
2525 | * | ||
2526 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2527 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2528 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2529 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2530 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2531 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2532 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2533 | * @li EINA_VALUE_TYPE_INT: int* | ||
2534 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2535 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2536 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2537 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2538 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2539 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2540 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2541 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2542 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2543 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2544 | * | ||
2545 | * @code | ||
2546 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2547 | * int x; | ||
2548 | * | ||
2549 | * eina_value_hash_set(value, "abc", 1234); | ||
2550 | * eina_value_hash_get(value, "abc", &x); | ||
2551 | * eina_value_free(value); | ||
2552 | * @endcode | ||
2553 | * | ||
2554 | * @see eina_value_hash_set() | ||
2555 | * @see eina_value_hash_vset() | ||
2556 | * @see eina_value_hash_pset() | ||
2557 | * | ||
2558 | * @since 1.2 | ||
2559 | */ | ||
2560 | static inline Eina_Bool eina_value_hash_get(const Eina_Value *value, | ||
2561 | const char *key, | ||
2562 | ...) EINA_ARG_NONNULL(1); | ||
2563 | |||
2564 | /** | ||
2565 | * @brief Set the generic value in an hash member. | ||
2566 | * @param value source value object | ||
2567 | * @param key key to find the member | ||
2568 | * @param args variable argument | ||
2569 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2570 | * @see eina_value_hash_set() | ||
2571 | * @see eina_value_hash_get() | ||
2572 | * @see eina_value_hash_pset() | ||
2573 | * | ||
2574 | * @since 1.2 | ||
2575 | */ | ||
2576 | static inline Eina_Bool eina_value_hash_vset(Eina_Value *value, | ||
2577 | const char *key, | ||
2578 | va_list args) EINA_ARG_NONNULL(1); | ||
2579 | |||
2580 | /** | ||
2581 | * @brief Get the generic value from an hash member. | ||
2582 | * @param value source value object | ||
2583 | * @param key key to find the member | ||
2584 | * @param args variable argument | ||
2585 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2586 | * | ||
2587 | * The value is returned in the variable argument parameter, the | ||
2588 | * actual value is type-dependent, but usually it will be what is | ||
2589 | * stored inside the object. There shouldn't be any memory allocation, | ||
2590 | * thus the contents should @b not be freed. | ||
2591 | * | ||
2592 | * @see eina_value_hash_vset() | ||
2593 | * @see eina_value_hash_get() | ||
2594 | * @see eina_value_hash_pget() | ||
2595 | * | ||
2596 | * @since 1.2 | ||
2597 | */ | ||
2598 | static inline Eina_Bool eina_value_hash_vget(const Eina_Value *value, | ||
2599 | const char *key, | ||
2600 | va_list args) EINA_ARG_NONNULL(1); | ||
2601 | |||
2602 | /** | ||
2603 | * @brief Set the generic value in an hash member from pointer. | ||
2604 | * @param value source value object | ||
2605 | * @param key key to find the member | ||
2606 | * @param ptr pointer to specify the contents. | ||
2607 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2608 | * | ||
2609 | * The pointer type is dependent on chosen value type. The list for | ||
2610 | * basic types: | ||
2611 | * | ||
2612 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2613 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2614 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2615 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2616 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2617 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2618 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2619 | * @li EINA_VALUE_TYPE_INT: int* | ||
2620 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2621 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2622 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2623 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2624 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2625 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2626 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2627 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2628 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2629 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2630 | * | ||
2631 | * @note the pointer contents are written using the size defined by | ||
2632 | * type. It can be larger than void* or uint64_t. | ||
2633 | * | ||
2634 | * @code | ||
2635 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2636 | * int x = 1234; | ||
2637 | * | ||
2638 | * eina_value_hash_pset(value, "abc", &x); | ||
2639 | * eina_value_hash_pget(value, "abc", &x); | ||
2640 | * eina_value_free(value); | ||
2641 | * @endcode | ||
2642 | * | ||
2643 | * @see eina_value_hash_set() | ||
2644 | * @see eina_value_hash_get() | ||
2645 | * @see eina_value_hash_vset() | ||
2646 | * | ||
2647 | * @since 1.2 | ||
2648 | */ | ||
2649 | static inline Eina_Bool eina_value_hash_pset(Eina_Value *value, | ||
2650 | const char *key, | ||
2651 | const void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2652 | |||
2653 | /** | ||
2654 | * @brief Get the generic value to pointer from an hash member. | ||
2655 | * @param value source value object | ||
2656 | * @param key key to find the member | ||
2657 | * @param ptr pointer to receive the contents. | ||
2658 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2659 | * | ||
2660 | * The value is returned in pointer contents, the actual value is | ||
2661 | * type-dependent, but usually it will be what is stored inside the | ||
2662 | * object. There shouldn't be any memory allocation, thus the contents | ||
2663 | * should @b not be freed. | ||
2664 | * | ||
2665 | * The pointer type is dependent on chosen value type. The list for | ||
2666 | * basic types: | ||
2667 | * | ||
2668 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2669 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2670 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2671 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2672 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2673 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2674 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2675 | * @li EINA_VALUE_TYPE_INT: int* | ||
2676 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2677 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2678 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2679 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2680 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2681 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2682 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2683 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2684 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2685 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2686 | * | ||
2687 | * @code | ||
2688 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2689 | * int x; | ||
2690 | * | ||
2691 | * eina_value_hash_set(value, "abc", 1234); | ||
2692 | * eina_value_hash_pget(value, "abc", &x); | ||
2693 | * eina_value_free(value); | ||
2694 | * @endcode | ||
2695 | * | ||
2696 | * @see eina_value_hash_set() | ||
2697 | * @see eina_value_hash_vset() | ||
2698 | * @see eina_value_hash_pset() | ||
2699 | * | ||
2700 | * @since 1.2 | ||
2701 | */ | ||
2702 | static inline Eina_Bool eina_value_hash_pget(const Eina_Value *value, | ||
2703 | const char *key, | ||
2704 | void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2705 | |||
2706 | /** | ||
2707 | * @} | ||
2708 | */ | ||
2709 | |||
2710 | /** | ||
2711 | * @defgroup Eina_Value_Blob_Group Generic Value Blob management | ||
2712 | * | ||
2713 | * @{ | ||
2714 | */ | ||
2715 | |||
2716 | /** | ||
2717 | * @typedef Eina_Value_Blob_Operations | ||
2718 | * How to manage blob. Any @c NULL callback is ignored. | ||
2719 | * @see #_Eina_Value_Blob_Operations explains fields. | ||
2720 | * @since 1.2 | ||
2721 | */ | ||
2722 | typedef struct _Eina_Value_Blob_Operations Eina_Value_Blob_Operations; | ||
2723 | |||
2724 | /** | ||
2725 | * @def EINA_VALUE_BLOB_OPERATIONS_VERSION | ||
2726 | * Current API version, used to validate #_Eina_Value_Blob_Operations. | ||
2727 | */ | ||
2728 | #define EINA_VALUE_BLOB_OPERATIONS_VERSION (1) | ||
2729 | |||
2730 | /** | ||
2731 | * @struct _Eina_Value_Blob_Operations | ||
2732 | * How to manage blob. Any @c NULL callback is ignored. | ||
2733 | * @since 1.2 | ||
2734 | */ | ||
2735 | struct _Eina_Value_Blob_Operations | ||
2736 | { | ||
2737 | unsigned int version; /**< must be #EINA_VALUE_BLOB_OPERATIONS_VERSION */ | ||
2738 | void (*free)(const Eina_Value_Blob_Operations *ops, void *memory, size_t size); | ||
2739 | void *(*copy)(const Eina_Value_Blob_Operations *ops, const void *memory, size_t size); | ||
2740 | int (*compare)(const Eina_Value_Blob_Operations *ops, const void *data1, size_t size_data1, const void *data2, size_t size_data2); | ||
2741 | char *(*to_string)(const Eina_Value_Blob_Operations *ops, const void *memory, size_t size); | ||
2742 | }; | ||
2743 | |||
2744 | /** | ||
2745 | * @var EINA_VALUE_BLOB_OPERATIONS_MALLOC | ||
2746 | * | ||
2747 | * Assumes @c memory was create with malloc() and applies free() to it | ||
2748 | * during flush (Eina_Value_Blob_Operations::free). Copy is done with | ||
2749 | * malloc() as well. | ||
2750 | * | ||
2751 | * No compare or to_string are provided, defaults will be used. | ||
2752 | */ | ||
2753 | EAPI extern const Eina_Value_Blob_Operations *EINA_VALUE_BLOB_OPERATIONS_MALLOC; | ||
2754 | |||
2755 | /** | ||
2756 | * @typedef Eina_Value_Blob | ||
2757 | * Value type for #EINA_VALUE_TYPE_BLOB. | ||
2758 | * | ||
2759 | * @see #_Eina_Value_Blob explains fields. | ||
2760 | * @since 1.2 | ||
2761 | */ | ||
2762 | typedef struct _Eina_Value_Blob Eina_Value_Blob; | ||
2763 | |||
2764 | /** | ||
2765 | * @struct _Eina_Value_Blob | ||
2766 | * Used to store the blob information and management operations. | ||
2767 | * @since 1.2 | ||
2768 | */ | ||
2769 | struct _Eina_Value_Blob | ||
2770 | { | ||
2771 | const Eina_Value_Blob_Operations *ops; /**< if @c NULL, nothing is freed, copy will just copy the memory pointer, not its value. */ | ||
2772 | const void *memory; | ||
2773 | unsigned int size; | ||
2774 | }; | ||
2775 | |||
2776 | /** | ||
2777 | * @} | ||
2778 | */ | ||
2779 | |||
2780 | /** | ||
2781 | * @defgroup Eina_Value_Struct_Group Generic Value Struct management | ||
2782 | * | ||
2783 | * @{ | ||
2784 | */ | ||
2785 | |||
2786 | /** | ||
2787 | * @typedef Eina_Value_Struct_Operations | ||
2788 | * How to manage struct. Any @c NULL callback is ignored. | ||
2789 | * | ||
2790 | * A structure can specify alternative methods to allocate, free and | ||
2791 | * copy itself. See structure definition for all methods. | ||
2792 | * | ||
2793 | * @see #_Eina_Value_Struct_Operations explains fields. | ||
2794 | * @since 1.2 | ||
2795 | */ | ||
2796 | typedef struct _Eina_Value_Struct_Operations Eina_Value_Struct_Operations; | ||
2797 | |||
2798 | /** | ||
2799 | * @typedef Eina_Value_Struct_Member | ||
2800 | * Describes a single member of struct. | ||
2801 | * | ||
2802 | * The member holds a name, type and its byte offset within the struct | ||
2803 | * memory. Most Eina_Value_Struct functions takes the member name as | ||
2804 | * parameter, as in eina_value_struct_set(). | ||
2805 | * | ||
2806 | * @see #_Eina_Value_Struct_Member explains fields. | ||
2807 | * @since 1.2 | ||
2808 | */ | ||
2809 | typedef struct _Eina_Value_Struct_Member Eina_Value_Struct_Member; | ||
2810 | |||
2811 | /** | ||
2812 | * @typedef Eina_Value_Struct_Desc | ||
2813 | * Describes the struct by listing its size, members and operations. | ||
2814 | * @see #_Eina_Value_Struct_Desc explains fields. | ||
2815 | * @since 1.2 | ||
2816 | */ | ||
2817 | typedef struct _Eina_Value_Struct_Desc Eina_Value_Struct_Desc; | ||
2818 | |||
2819 | /** | ||
2820 | * @typedef Eina_Value_Struct | ||
2821 | * Value type for #EINA_VALUE_TYPE_STRUCT. | ||
2822 | * | ||
2823 | * @see #_Eina_Value_Struct explains fields. | ||
2824 | * @since 1.2 | ||
2825 | */ | ||
2826 | typedef struct _Eina_Value_Struct Eina_Value_Struct; | ||
2827 | |||
2828 | /** | ||
2829 | * @def EINA_VALUE_STRUCT_OPERATIONS_VERSION | ||
2830 | * Current API version, used to validate #_Eina_Value_Struct_Operations. | ||
2831 | */ | ||
2832 | #define EINA_VALUE_STRUCT_OPERATIONS_VERSION (1) | ||
2833 | |||
2834 | /** | ||
2835 | * @struct _Eina_Value_Struct_Operations | ||
2836 | * How to manage struct. Any @c NULL callback is ignored. | ||
2837 | * @since 1.2 | ||
2838 | */ | ||
2839 | struct _Eina_Value_Struct_Operations | ||
2840 | { | ||
2841 | unsigned int version; /**< must be #EINA_VALUE_STRUCT_OPERATIONS_VERSION */ | ||
2842 | void *(*alloc)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc); /**< How to allocate struct memory to be managed by the Eina_Value */ | ||
2843 | void (*free)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, void *memory); /**< How to release memory managed by the Eina_Value */ | ||
2844 | void *(*copy)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *memory); /**< How to copy struct memory from an existing Eina_Value, if not provided alloc() will be used, then every member is copied using eina_value_type_copy() with member's type. */ | ||
2845 | int (*compare)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *data1, const void *data2); /**< How to compare two struct memories */ | ||
2846 | const Eina_Value_Struct_Member *(*find_member)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const char *name); /**< How to find description for member. For huge structures consider using binary search, stringshared, hash or gperf. The default function does linear search using strcmp(). */ | ||
2847 | }; | ||
2848 | |||
2849 | /** | ||
2850 | * @var EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH | ||
2851 | * | ||
2852 | * Assumes @c members is sorted by name and applies binary search for | ||
2853 | * names. | ||
2854 | * | ||
2855 | * Ideally the @c member_count field is set to speed it up. | ||
2856 | * | ||
2857 | * No other methods are set (alloc, free, copy, compare), then it uses | ||
2858 | * the default operations. | ||
2859 | */ | ||
2860 | EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH; | ||
2861 | |||
2862 | /** | ||
2863 | * @var EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE | ||
2864 | * | ||
2865 | * Assumes @c members name are stringshared and can be compared for | ||
2866 | * equality without using its contents (simple pointer comparison). | ||
2867 | * | ||
2868 | * Ideally the search @c name will be stringshared as well, but it | ||
2869 | * will do a second loop with a forced stringshare if it did not find | ||
2870 | * the member. | ||
2871 | * | ||
2872 | * No other methods are set (alloc, free, copy, compare), then it uses | ||
2873 | * the default operations. | ||
2874 | */ | ||
2875 | EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE; | ||
2876 | |||
2877 | /** | ||
2878 | * @struct _Eina_Value_Struct_Member | ||
2879 | * Describes a single member of struct. | ||
2880 | * | ||
2881 | * The name is used to lookup the member description. This is done as | ||
2882 | * specified as _Eina_Value_Struct_Operations::find_member(). For | ||
2883 | * structures with huge number of members, consider using a better | ||
2884 | * find_member function to quickly finding it! There are two helper | ||
2885 | * operations provided to help this: | ||
2886 | * #EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH and | ||
2887 | * #EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE, both depend on properly | ||
2888 | * set #_Eina_Value_Struct_Desc and #_Eina_Value_Struct_Member. | ||
2889 | * | ||
2890 | * @see #EINA_VALUE_STRUCT_MEMBER | ||
2891 | * @see #EINA_VALUE_STRUCT_MEMBER_SENTINEL | ||
2892 | * | ||
2893 | * @since 1.2 | ||
2894 | */ | ||
2895 | struct _Eina_Value_Struct_Member | ||
2896 | { | ||
2897 | const char *name; /**< member name, used in lookups such as eina_value_struct_get() */ | ||
2898 | const Eina_Value_Type *type; /**< how to use this member */ | ||
2899 | unsigned int offset; /**< where this member is located within the structure memory */ | ||
2900 | }; | ||
2901 | |||
2902 | /** | ||
2903 | * @def EINA_VALUE_STRUCT_DESC_VERSION | ||
2904 | * Current API version, used to validate #_Eina_Value_Struct_Desc. | ||
2905 | */ | ||
2906 | #define EINA_VALUE_STRUCT_DESC_VERSION (1) | ||
2907 | |||
2908 | /** | ||
2909 | * @struct _Eina_Value_Struct_Desc | ||
2910 | * Describes the struct by listing its size, members and operations. | ||
2911 | * | ||
2912 | * This is the root of Eina_Value knowledge about the memory it's | ||
2913 | * handling as a structure. It adds introspection, saying the byte | ||
2914 | * size of the structure, its members and how to manage such members. | ||
2915 | * | ||
2916 | * @since 1.2 | ||
2917 | */ | ||
2918 | struct _Eina_Value_Struct_Desc | ||
2919 | { | ||
2920 | unsigned int version; /**< must be #EINA_VALUE_STRUCT_DESC_VERSION */ | ||
2921 | const Eina_Value_Struct_Operations *ops; /**< operations, if @c NULL defaults will be used. You may use operations to optimize member lookup using binary search or gperf hash. */ | ||
2922 | const Eina_Value_Struct_Member *members; /**< array of member descriptions, if @c member_count is zero, then it must be @c NULL terminated. */ | ||
2923 | unsigned int member_count; /**< if > 0, specifies number of members. If zero then @c members must be NULL terminated. */ | ||
2924 | unsigned int size; /**< byte size to allocate, may be bigger than sum of members */ | ||
2925 | }; | ||
2926 | |||
2927 | /** | ||
2928 | * @def EINA_VALUE_STRUCT_MEMBER | ||
2929 | * | ||
2930 | * Helper to define Eina_Value_Struct_Member fields, uses offsetof() | ||
2931 | * with type and member. | ||
2932 | * | ||
2933 | * @since 1.2 | ||
2934 | */ | ||
2935 | #define EINA_VALUE_STRUCT_MEMBER(eina_value_type, type, member) \ | ||
2936 | {#member, eina_value_type, offsetof(type, member)} | ||
2937 | |||
2938 | /** | ||
2939 | * @def EINA_VALUE_STRUCT_MEMBER_SENTINEL | ||
2940 | * | ||
2941 | * Helper to define Eina_Value_Struct_Member fields for sentinel (last | ||
2942 | * item), useful if you did not define @c member_count. | ||
2943 | * | ||
2944 | * @since 1.2 | ||
2945 | */ | ||
2946 | #define EINA_VALUE_STRUCT_MEMBER_SENTINEL {NULL, NULL, 0} | ||
2947 | |||
2948 | |||
2949 | /** | ||
2950 | * @struct _Eina_Value_Struct | ||
2951 | * Used to store the memory and its description. | ||
2952 | * @since 1.2 | ||
2953 | */ | ||
2954 | struct _Eina_Value_Struct | ||
2955 | { | ||
2956 | const Eina_Value_Struct_Desc *desc; /**< How to manage the structure */ | ||
2957 | void *memory; /**< The managed structure memory */ | ||
2958 | }; | ||
2959 | |||
2960 | /** | ||
2961 | * @brief Create generic value storage of type struct. | ||
2962 | * @param desc how to manage this struct members. | ||
2963 | * @return The new value or @c NULL on failure. | ||
2964 | * | ||
2965 | * Create a new generic value storage of type struct. The members are | ||
2966 | * managed using the description specified by @a desc. | ||
2967 | * | ||
2968 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
2969 | * #EINA_ERROR_VALUE_FAILED is set. | ||
2970 | * | ||
2971 | * @note this creates from mempool and then uses | ||
2972 | * eina_value_struct_setup(). | ||
2973 | * | ||
2974 | * @see eina_value_free() | ||
2975 | * @see eina_value_struct_setup() | ||
2976 | * | ||
2977 | * @since 1.2 | ||
2978 | */ | ||
2979 | EAPI Eina_Value *eina_value_struct_new(const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1); | ||
2980 | |||
2981 | /** | ||
2982 | * @brief Initialize generic value storage of type struct. | ||
2983 | * @param value value object | ||
2984 | * @param desc how to manage this struct members. | ||
2985 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2986 | * | ||
2987 | * Initializes new generic value storage of type struct with the given | ||
2988 | * @a desc. | ||
2989 | * | ||
2990 | * This is the same as calling eina_value_set() with | ||
2991 | * #EINA_VALUE_TYPE_STRUCT followed by eina_value_pset() with the | ||
2992 | * #Eina_Value_Struct description configured. | ||
2993 | * | ||
2994 | * @note Existing contents are ignored! If the value was previously used, then | ||
2995 | * use eina_value_flush() first. | ||
2996 | * | ||
2997 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
2998 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
2999 | * | ||
3000 | * @see eina_value_flush() | ||
3001 | * | ||
3002 | * @since 1.2 | ||
3003 | */ | ||
3004 | static inline Eina_Bool eina_value_struct_setup(Eina_Value *value, | ||
3005 | const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1, 2); | ||
3006 | |||
3007 | /** | ||
3008 | * @brief Set the generic value in an struct member. | ||
3009 | * @param value source value object | ||
3010 | * @param name name to find the member | ||
3011 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3012 | * | ||
3013 | * The variable argument is dependent on chosen member type. The list | ||
3014 | * for basic types: | ||
3015 | * | ||
3016 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
3017 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
3018 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
3019 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
3020 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
3021 | * @li EINA_VALUE_TYPE_CHAR: char | ||
3022 | * @li EINA_VALUE_TYPE_SHORT: short | ||
3023 | * @li EINA_VALUE_TYPE_INT: int | ||
3024 | * @li EINA_VALUE_TYPE_LONG: long | ||
3025 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
3026 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
3027 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
3028 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
3029 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
3030 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
3031 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
3032 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
3033 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
3034 | * | ||
3035 | * @code | ||
3036 | * struct myst { | ||
3037 | * int i; | ||
3038 | * char c; | ||
3039 | * }; | ||
3040 | * const Eina_Value_Struct_Member myst_members[] = { | ||
3041 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
3042 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
3043 | * {NULL, NULL, 0} | ||
3044 | * }; | ||
3045 | * const Eina_Value_Struct_Desc myst_desc = { | ||
3046 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
3047 | * NULL, myst_members, 2, sizeof(struct myst) | ||
3048 | * }; | ||
3049 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
3050 | * int x; | ||
3051 | * char y; | ||
3052 | * | ||
3053 | * eina_value_struct_set(value, "i", 5678); | ||
3054 | * eina_value_struct_get(value, "i", &x); | ||
3055 | * eina_value_struct_set(value, "c", 0xf); | ||
3056 | * eina_value_struct_get(value, "c", &y); | ||
3057 | * eina_value_free(value); | ||
3058 | * @endcode | ||
3059 | * | ||
3060 | * @see eina_value_struct_get() | ||
3061 | * @see eina_value_struct_vset() | ||
3062 | * @see eina_value_struct_pset() | ||
3063 | * | ||
3064 | * @since 1.2 | ||
3065 | */ | ||
3066 | static inline Eina_Bool eina_value_struct_set(Eina_Value *value, | ||
3067 | const char *name, | ||
3068 | ...) EINA_ARG_NONNULL(1, 2); | ||
3069 | |||
3070 | /** | ||
3071 | * @brief Get the generic value from an struct member. | ||
3072 | * @param value source value object | ||
3073 | * @param name name to find the member | ||
3074 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3075 | * | ||
3076 | * The value is returned in the variable argument parameter, the | ||
3077 | * actual value is type-dependent, but usually it will be what is | ||
3078 | * stored inside the object. There shouldn't be any memory allocation, | ||
3079 | * thus the contents should @b not be freed. | ||
3080 | * | ||
3081 | * The variable argument is dependent on chosen member type. The list | ||
3082 | * for basic types: | ||
3083 | * | ||
3084 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
3085 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
3086 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
3087 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
3088 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
3089 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
3090 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
3091 | * @li EINA_VALUE_TYPE_INT: int* | ||
3092 | * @li EINA_VALUE_TYPE_LONG: long* | ||
3093 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
3094 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
3095 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
3096 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
3097 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
3098 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
3099 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
3100 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
3101 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
3102 | * | ||
3103 | * @code | ||
3104 | * struct myst { | ||
3105 | * int i; | ||
3106 | * char c; | ||
3107 | * }; | ||
3108 | * const Eina_Value_Struct_Member myst_members[] = { | ||
3109 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
3110 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
3111 | * {NULL, NULL, 0} | ||
3112 | * }; | ||
3113 | * const Eina_Value_Struct_Desc myst_desc = { | ||
3114 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
3115 | * NULL, myst_members, 2, sizeof(struct myst) | ||
3116 | * }; | ||
3117 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
3118 | * int x; | ||
3119 | * char y; | ||
3120 | * | ||
3121 | * eina_value_struct_set(value, "i", 5678); | ||
3122 | * eina_value_struct_get(value, "i", &x); | ||
3123 | * eina_value_struct_set(value, "c", 0xf); | ||
3124 | * eina_value_struct_get(value, "c", &y); | ||
3125 | * eina_value_free(value); | ||
3126 | * @endcode | ||
3127 | * | ||
3128 | * @see eina_value_struct_set() | ||
3129 | * @see eina_value_struct_vset() | ||
3130 | * @see eina_value_struct_pset() | ||
3131 | * | ||
3132 | * @since 1.2 | ||
3133 | */ | ||
3134 | static inline Eina_Bool eina_value_struct_get(const Eina_Value *value, | ||
3135 | const char *name, | ||
3136 | ...) EINA_ARG_NONNULL(1, 2); | ||
3137 | |||
3138 | /** | ||
3139 | * @brief Set the generic value in an struct member. | ||
3140 | * @param value source value object | ||
3141 | * @param name name to find the member | ||
3142 | * @param args variable argument | ||
3143 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3144 | * @see eina_value_struct_set() | ||
3145 | * @see eina_value_struct_get() | ||
3146 | * @see eina_value_struct_pset() | ||
3147 | * | ||
3148 | * @since 1.2 | ||
3149 | */ | ||
3150 | static inline Eina_Bool eina_value_struct_vset(Eina_Value *value, | ||
3151 | const char *name, | ||
3152 | va_list args) EINA_ARG_NONNULL(1, 2); | ||
3153 | |||
3154 | /** | ||
3155 | * @brief Get the generic value from an struct member. | ||
3156 | * @param value source value object | ||
3157 | * @param name name to find the member | ||
3158 | * @param args variable argument | ||
3159 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3160 | * | ||
3161 | * The value is returned in the variable argument parameter, the | ||
3162 | * actual value is type-dependent, but usually it will be what is | ||
3163 | * stored inside the object. There shouldn't be any memory allocation, | ||
3164 | * thus the contents should @b not be freed. | ||
3165 | * | ||
3166 | * @see eina_value_struct_vset() | ||
3167 | * @see eina_value_struct_get() | ||
3168 | * @see eina_value_struct_pget() | ||
3169 | * | ||
3170 | * @since 1.2 | ||
3171 | */ | ||
3172 | static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, | ||
3173 | const char *name, | ||
3174 | va_list args) EINA_ARG_NONNULL(1, 2); | ||
3175 | |||
3176 | /** | ||
3177 | * @brief Set the generic value in an struct member from pointer. | ||
3178 | * @param value source value object | ||
3179 | * @param name name to find the member | ||
3180 | * @param ptr pointer to specify the contents. | ||
3181 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3182 | * | ||
3183 | * The pointer type is dependent on chosen value type. The list for | ||
3184 | * basic types: | ||
3185 | * | ||
3186 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
3187 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
3188 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
3189 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
3190 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
3191 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
3192 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
3193 | * @li EINA_VALUE_TYPE_INT: int* | ||
3194 | * @li EINA_VALUE_TYPE_LONG: long* | ||
3195 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
3196 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
3197 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
3198 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
3199 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
3200 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
3201 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
3202 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
3203 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
3204 | * | ||
3205 | * @note the pointer contents are written using the size defined by | ||
3206 | * type. It can be larger than void* or uint64_t. | ||
3207 | * | ||
3208 | * @code | ||
3209 | * struct myst { | ||
3210 | * int i; | ||
3211 | * char c; | ||
3212 | * }; | ||
3213 | * const Eina_Value_Struct_Member myst_members[] = { | ||
3214 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
3215 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
3216 | * {NULL, NULL, 0} | ||
3217 | * }; | ||
3218 | * const Eina_Value_Struct_Desc myst_desc = { | ||
3219 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
3220 | * NULL, myst_members, 2, sizeof(struct myst) | ||
3221 | * }; | ||
3222 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
3223 | * int x = 5678; | ||
3224 | * char y = 0xf; | ||
3225 | * | ||
3226 | * eina_value_struct_pset(value, "i", &); | ||
3227 | * eina_value_struct_pget(value, "i", &x); | ||
3228 | * eina_value_struct_pset(value, "c", &y); | ||
3229 | * eina_value_struct_pget(value, "c", &y); | ||
3230 | * eina_value_free(value); | ||
3231 | * @endcode | ||
3232 | * | ||
3233 | * @see eina_value_struct_set() | ||
3234 | * @see eina_value_struct_get() | ||
3235 | * @see eina_value_struct_vset() | ||
3236 | * | ||
3237 | * @since 1.2 | ||
3238 | */ | ||
3239 | static inline Eina_Bool eina_value_struct_pset(Eina_Value *value, | ||
3240 | const char *name, | ||
3241 | const void *ptr) EINA_ARG_NONNULL(1, 2, 3); | ||
3242 | |||
3243 | /** | ||
3244 | * @brief Get the generic value to pointer from an struct member. | ||
3245 | * @param value source value object | ||
3246 | * @param name name to find the member | ||
3247 | * @param ptr pointer to receive the contents. | ||
3248 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3249 | * | ||
3250 | * The value is returned in pointer contents, the actual value is | ||
3251 | * type-dependent, but usually it will be what is stored inside the | ||
3252 | * object. There shouldn't be any memory allocation, thus the contents | ||
3253 | * should @b not be freed. | ||
3254 | * | ||
3255 | * The pointer type is dependent on chosen value type. The list for | ||
3256 | * basic types: | ||
3257 | * | ||
3258 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
3259 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
3260 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
3261 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
3262 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
3263 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
3264 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
3265 | * @li EINA_VALUE_TYPE_INT: int* | ||
3266 | * @li EINA_VALUE_TYPE_LONG: long* | ||
3267 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
3268 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
3269 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
3270 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
3271 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
3272 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
3273 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
3274 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
3275 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
3276 | * | ||
3277 | * @code | ||
3278 | * struct myst { | ||
3279 | * int i; | ||
3280 | * char c; | ||
3281 | * }; | ||
3282 | * const Eina_Value_Struct_Member myst_members[] = { | ||
3283 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
3284 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
3285 | * {NULL, NULL, 0} | ||
3286 | * }; | ||
3287 | * const Eina_Value_Struct_Desc myst_desc = { | ||
3288 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
3289 | * NULL, myst_members, 2, sizeof(struct myst) | ||
3290 | * }; | ||
3291 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
3292 | * int x = 5678; | ||
3293 | * char y = 0xf; | ||
3294 | * | ||
3295 | * eina_value_struct_pset(value, "i", &); | ||
3296 | * eina_value_struct_pget(value, "i", &x); | ||
3297 | * eina_value_struct_pset(value, "c", &y); | ||
3298 | * eina_value_struct_pget(value, "c", &y); | ||
3299 | * eina_value_free(value); | ||
3300 | * @endcode | ||
3301 | * | ||
3302 | * @see eina_value_struct_set() | ||
3303 | * @see eina_value_struct_vset() | ||
3304 | * @see eina_value_struct_pset() | ||
3305 | * | ||
3306 | * @since 1.2 | ||
3307 | */ | ||
3308 | static inline Eina_Bool eina_value_struct_pget(const Eina_Value *value, | ||
3309 | const char *name, | ||
3310 | void *ptr) EINA_ARG_NONNULL(1, 2, 3); | ||
3311 | |||
3312 | /** | ||
3313 | * @brief Get the member as Eina_Value copy | ||
3314 | * @param src source value object | ||
3315 | * @param name name to find the member | ||
3316 | * @param dst where to return the member value. | ||
3317 | * | ||
3318 | * The argument @a dst is considered uninitialized and it's setup to | ||
3319 | * the type of the member. | ||
3320 | * | ||
3321 | * @since 1.2 | ||
3322 | */ | ||
3323 | static inline Eina_Bool eina_value_struct_value_get(const Eina_Value *src, | ||
3324 | const char *name, | ||
3325 | Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3); | ||
3326 | |||
3327 | /** | ||
3328 | * @brief Set the member from Eina_Value source | ||
3329 | * @param dst destination value object | ||
3330 | * @param name name to find the member | ||
3331 | * @param src source value | ||
3332 | * | ||
3333 | * @since 1.2 | ||
3334 | */ | ||
3335 | static inline Eina_Bool eina_value_struct_value_set(Eina_Value *dst, | ||
3336 | const char *name, | ||
3337 | const Eina_Value *src) EINA_ARG_NONNULL(1, 2, 3); | ||
3338 | |||
3339 | /** | ||
3340 | * @brief Get the member as Eina_Value copy given its member description. | ||
3341 | * @param src source value object | ||
3342 | * @param member the member description to use | ||
3343 | * @param dst where to return the member value. | ||
3344 | * | ||
3345 | * The argument @a dst is considered uninitialized and it's setup to | ||
3346 | * the type of the member. | ||
3347 | * | ||
3348 | * @since 1.2 | ||
3349 | */ | ||
3350 | static inline Eina_Bool eina_value_struct_member_value_get(const Eina_Value *src, | ||
3351 | const Eina_Value_Struct_Member *member, | ||
3352 | Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3); | ||
3353 | |||
3354 | /** | ||
3355 | * @brief Set the member from Eina_Value source | ||
3356 | * @param dst destination value object | ||
3357 | * @param member the member description to use | ||
3358 | * @param src source value | ||
3359 | * | ||
3360 | * @since 1.2 | ||
3361 | */ | ||
3362 | static inline Eina_Bool eina_value_struct_member_value_set(Eina_Value *dst, | ||
3363 | const Eina_Value_Struct_Member *member, | ||
3364 | const Eina_Value *src) EINA_ARG_NONNULL(1, 2, 3); | ||
3365 | |||
3366 | |||
3367 | /** | ||
3368 | * @} | ||
3369 | */ | ||
3370 | |||
3371 | |||
3372 | /** | ||
3373 | * @defgroup Eina_Value_Type_Group Generic Value Type management | ||
3374 | * | ||
3375 | * @{ | ||
3376 | */ | ||
3377 | |||
3378 | /** | ||
3379 | * @def EINA_VALUE_TYPE_VERSION | ||
3380 | * Current API version, used to validate type. | ||
3381 | */ | ||
3382 | #define EINA_VALUE_TYPE_VERSION (1) | ||
3383 | |||
3384 | /** | ||
3385 | * @struct _Eina_Value_Type | ||
3386 | * API to access values. | ||
3387 | * | ||
3388 | * @since 1.2 | ||
3389 | */ | ||
3390 | struct _Eina_Value_Type | ||
3391 | { | ||
3392 | unsigned int version; /**< must be #EINA_VALUE_TYPE_VERSION */ | ||
3393 | unsigned int value_size; /**< byte size of value */ | ||
3394 | const char *name; /**< name for debug and introspection */ | ||
3395 | Eina_Bool (*setup)(const Eina_Value_Type *type, void *mem); /**< mem will be malloc(value_size) and should be configured */ | ||
3396 | Eina_Bool (*flush)(const Eina_Value_Type *type, void *mem); /**< clear any values from mem */ | ||
3397 | Eina_Bool (*copy)(const Eina_Value_Type *type, const void *src, void *dst); /**< how to copy values, both memory are @c value_size */ | ||
3398 | int (*compare)(const Eina_Value_Type *type, const void *a, const void *b); /**< how to compare values, both memory are @c value_size */ | ||
3399 | Eina_Bool (*convert_to)(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem); /**< how to convert values, both memory are @c value_size */ | ||
3400 | Eina_Bool (*convert_from)(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem); /**< how to convert values, both memory are @c value_size */ | ||
3401 | Eina_Bool (*vset)(const Eina_Value_Type *type, void *mem, va_list args); /**< how to set memory from variable argument */ | ||
3402 | Eina_Bool (*pset)(const Eina_Value_Type *type, void *mem, const void *ptr); /**< how to set memory from pointer */ | ||
3403 | Eina_Bool (*pget)(const Eina_Value_Type *type, const void *mem, void *ptr); /**< how to read memory */ | ||
3404 | }; | ||
3405 | |||
3406 | /** | ||
3407 | * @brief Query type name. | ||
3408 | * @param type type reference. | ||
3409 | * @return string or @c NULL if type is invalid. | ||
3410 | * @since 1.2 | ||
3411 | */ | ||
3412 | EAPI const char *eina_value_type_name_get(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
3413 | |||
3414 | /** | ||
3415 | * @brief Check if type is valid. | ||
3416 | * @param type type reference. | ||
3417 | * @return #EINA_TRUE if valid, #EINA_FALSE otherwise. | ||
3418 | * | ||
3419 | * A type is invalid if it's NULL or if version field is not the same | ||
3420 | * as runtime #EINA_VALUE_TYPE_VERSION. | ||
3421 | * | ||
3422 | * @since 1.2 | ||
3423 | */ | ||
3424 | EAPI Eina_Bool eina_value_type_check(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
3425 | |||
3426 | /** | ||
3427 | * @brief Initialize memory using type descriptor. | ||
3428 | * @param type type reference. | ||
3429 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3430 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3431 | * @since 1.2 | ||
3432 | */ | ||
3433 | static inline Eina_Bool eina_value_type_setup(const Eina_Value_Type *type, void *mem); | ||
3434 | |||
3435 | /** | ||
3436 | * @brief Flush (clear) memory using type descriptor. | ||
3437 | * @param type type reference. | ||
3438 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3439 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3440 | * @since 1.2 | ||
3441 | */ | ||
3442 | static inline Eina_Bool eina_value_type_flush(const Eina_Value_Type *type, void *mem); | ||
3443 | |||
3444 | /** | ||
3445 | * @brief Copy memory using type descriptor. | ||
3446 | * @param type type reference. | ||
3447 | * @param src memory to operate, must be of size @c type->value_size. | ||
3448 | * @param dst memory to operate, must be of size @c type->value_size. | ||
3449 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3450 | * @since 1.2 | ||
3451 | */ | ||
3452 | static inline Eina_Bool eina_value_type_copy(const Eina_Value_Type *type, const void *src, void *dst); | ||
3453 | |||
3454 | /** | ||
3455 | * @brief Compare memory using type descriptor. | ||
3456 | * @param type type reference. | ||
3457 | * @param a memory to operate, must be of size @c type->value_size. | ||
3458 | * @param b memory to operate, must be of size @c type->value_size. | ||
3459 | * @return less than zero if a < b, greater than zero if a > b, zero if equal. | ||
3460 | * @since 1.2 | ||
3461 | */ | ||
3462 | static inline int eina_value_type_compare(const Eina_Value_Type *type, const void *a, const void *b); | ||
3463 | |||
3464 | /** | ||
3465 | * @brief Convert memory using type descriptor. | ||
3466 | * @param type type reference of the source. | ||
3467 | * @param convert type reference of the destination. | ||
3468 | * @param type_mem memory to operate, must be of size @c type->value_size. | ||
3469 | * @param convert_mem memory to operate, must be of size @c convert->value_size. | ||
3470 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3471 | * @since 1.2 | ||
3472 | */ | ||
3473 | static inline Eina_Bool eina_value_type_convert_to(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem); | ||
3474 | |||
3475 | /** | ||
3476 | * @brief Convert memory using type descriptor. | ||
3477 | * @param type type reference of the destination. | ||
3478 | * @param convert type reference of the source. | ||
3479 | * @param type_mem memory to operate, must be of size @c type->value_size. | ||
3480 | * @param convert_mem memory to operate, must be of size @c convert->value_size. | ||
3481 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3482 | * @since 1.2 | ||
3483 | */ | ||
3484 | static inline Eina_Bool eina_value_type_convert_from(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem); | ||
3485 | |||
3486 | /** | ||
3487 | * @brief Set memory using type descriptor and variable argument. | ||
3488 | * @param type type reference of the source. | ||
3489 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3490 | * @param args input value. | ||
3491 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3492 | * @since 1.2 | ||
3493 | */ | ||
3494 | static inline Eina_Bool eina_value_type_vset(const Eina_Value_Type *type, void *mem, va_list args); | ||
3495 | |||
3496 | /** | ||
3497 | * @brief Set memory using type descriptor and pointer. | ||
3498 | * @param type type reference of the source. | ||
3499 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3500 | * @param ptr pointer to input value. | ||
3501 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3502 | * @since 1.2 | ||
3503 | */ | ||
3504 | static inline Eina_Bool eina_value_type_pset(const Eina_Value_Type *type, void *mem, const void *ptr); | ||
3505 | |||
3506 | /** | ||
3507 | * @brief Get memory using type descriptor. | ||
3508 | * @param type type reference of the source. | ||
3509 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3510 | * @param ptr pointer to output. | ||
3511 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3512 | * @since 1.2 | ||
3513 | */ | ||
3514 | static inline Eina_Bool eina_value_type_pget(const Eina_Value_Type *type, const void *mem, void *ptr); | ||
3515 | |||
3516 | /** | ||
3517 | * @} | ||
3518 | */ | ||
3519 | |||
3520 | #include "eina_inline_value.x" | ||
3521 | |||
3522 | /** | ||
3523 | * @} | ||
3524 | */ | ||
3525 | |||
3526 | /** | ||
3527 | * @} | ||
3528 | */ | ||
3529 | |||
3530 | /** | ||
3531 | * @} | ||
3532 | */ | ||
3533 | #endif | ||