src/include/eina_value.h

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