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