Eet Data Serialization

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

Modules | Data Structures | Macros | Typedefs | Functions
Eet Data Serialization
Eet

Convenience functions to serialize and parse complex data structures to binary blobs. More...

## Modules
| Eet Data Serialization using A Ciphers
| Most of the Eet Data Serialization have alternative versions that accounts for ciphers to protect their content.

## Data Structures
struct | _Eet_Data_Descriptor_Class
| Instructs Eet about memory management for different needs under serialization and parse process. More...

## Macros
#define | EET_T_UNKNOW 0
| Unknown data encoding type.
#define | EET_T_CHAR 1
| Data type: char.
#define | EET_T_SHORT 2
| Data type: short.
#define | EET_T_INT 3
| Data type: int.
#define | EET_T_LONG_LONG 4
| Data type: long long.
#define | EET_T_FLOAT 5
| Data type: float.
#define | EET_T_DOUBLE 6
| Data type: double.
#define | EET_T_UCHAR 7
| Data type: unsigned char.
#define | EET_T_USHORT 8
| Data type: unsigned short.
#define | EET_T_UINT 9
| Data type: unsigned int.
#define | EET_T_ULONG_LONG 10
| Data type: unsigned long long.
#define | EET_T_STRING 11
| Data type: char *.
#define | EET_T_INLINED_STRING 12
| Data type: char * (but compressed inside the resulting eet)
#define | EET_T_NULL 13
| Data type: (void *) (only use it if you know why)
#define | EET_T_F32P32 14
| Data type: fixed point 32.32.
#define | EET_T_F16P16 15
| Data type: fixed point 16.16.
#define | EET_T_F8P24 16
| Data type: fixed point 8.24.
#define | EET_T_VALUE 17
| Data type: pointer to Eina_Value.
#define | EET_T_LAST 18
| Last data type.
#define | EET_G_UNKNOWN 100
| Unknown group data encoding type.
#define | EET_G_ARRAY 101
| Fixed size array group type.
#define | EET_G_VAR_ARRAY 102
| Variable size array group type.
#define | EET_G_LIST 103
| Linked list group type.
#define | EET_G_HASH 104
| Hash table group type.
#define | EET_G_UNION 105
| Union group type.
#define | EET_G_VARIANT 106
| Selectable subtype group.
#define | EET_G_UNKNOWN_NESTED 107
| Unknown nested group type.
#define | EET_G_LAST 108
| Last group type.
#define | EET_I_LIMIT 128
| Other type exist but are reserved for internal purpose.
#define | EET_DATA_DESCRIPTOR_CLASS_VERSION 4
| The version of Eet_Data_Descriptor_Class at the time of the distribution of the sources.
#define | EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
| This macro is an helper that set all the parameter of an Eet_Data_Descriptor_Class correctly when you use Eina data type with stream.
#define | EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
| This macro is an helper that set all the parameter of an Eet_Data_Descriptor_Class correctly when you use Eina data type with file.
#define | EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type)
| Adds a basic data element to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype)
| Adds a sub-element type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_SUB_NESTED(edd, struct_type, name, member, subtype)
| Adds a nested sub-element type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype)
| Adds a linked list type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member)
| Adds a linked list of string to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_LIST_UINT(edd, struct_type, name, member)
| Adds a linked list of unsigned integers to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype)
| Adds a hash type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member)
| Adds a hash of string to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_HASH_VALUE(edd, struct_type, name, member)
| Adds a hash of generic value storage to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member, type)
| Adds an array of basic data elements to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, member, type)
| Adds a variable array of basic data elements to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype)
| Adds a fixed size array type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype)
| Adds a variable size array type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member)
| Adds a variable size array type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type)
| Adds an union type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type)
| Adds a automatically selectable type to a data descriptor.
#define | EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype)
| Adds a mapping to a data descriptor that will be used by union, variant or inherited type.
#define | EET_DATA_DESCRIPTOR_ADD_MAPPING_BASIC(unified_type, name, basic_type)
| Adds a mapping of a basic type to a data descriptor that will be used by a union type.

## Typedefs
typedef struct _Eet_Data_Descriptor | Eet_Data_Descriptor
| Opaque handle that have information on a type members.
typedef struct _Eet_Data_Descriptor_Class | Eet_Data_Descriptor_Class
| Instructs Eet about memory management for different needs under serialization and parse process.
typedef int(* | Eet_Descriptor_Hash_Foreach_Callback_Callback) (void *h, const char *k, void *dt, void *fdt)
| Callback prototype for Eet_Descriptor_Hash_Foreach_Callback.
typedef void *(* | Eet_Descriptor_Mem_Alloc_Callback) (size_t size)
| Callback prototype for Eet_Descriptor_Mem_Alloc.
typedef void(* | Eet_Descriptor_Mem_Free_Callback) (void *mem)
| Callback prototype for Eet_Descriptor_Mem_Alloc.
typedef char *(* | Eet_Descriptor_Str_Alloc_Callback) (const char *str)
| Callback prototype for Eet_Descriptor_Str_Alloc.
typedef void(* | Eet_Descriptor_Str_Free_Callback) (const char *str)
| Callback prototype for Eet_Descriptor_Str_Free.
typedef void *(* | Eet_Descriptor_List_Next_Callback) (void *l)
| Callback prototype for Eet_Descriptor_List_Next.
typedef void *(* | Eet_Descriptor_List_Append_Callback) (void *l, void *d)
| Callback prototype for Eet_Descriptor_List_Append.
typedef void *(* | Eet_Descriptor_List_Data_Callback) (void *l)
| Callback prototype for Eet_Descriptor_List_Data.
typedef void *(* | Eet_Descriptor_List_Free_Callback) (void *l)
| Callback prototype for Eet_Descriptor_List_Free.
typedef void(* | Eet_Descriptor_Hash_Foreach_Callback) (void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt)
| Callback for Eet_Descriptor_Hash_Foreach.
typedef void *(* | Eet_Descriptor_Hash_Add_Callback) (void *h, const char *k, void *d)
| Callback prototype for Eet_Descriptor_Hash_Add.
typedef void(* | Eet_Descriptor_Hash_Free_Callback) (void *h)
| Callback prototype for Eet_Descriptor_Hash_Free.
typedef char *(* | Eet_Descriptor_Str_Direct_Alloc_Callback) (const char *str)
typedef void(* | Eet_Descriptor_Str_Direct_Free_Callback) (const char *str)
typedef const char *(* | Eet_Descriptor_Type_Get_Callback) (const void *data, Eina_Bool *unknow)
| Callback prototype for Eet_Descriptor_Type_Get.
typedef Eina_Bool(* | Eet_Descriptor_Type_Set_Callback) (const char *type, void *data, Eina_Bool unknow)
| Callback prototype for Eet_Descriptor_Type_Set.
typedef void *(* | Eet_Descriptor_Array_Alloc_Callback) (size_t size)
| Callback prototype for Eet_Descriptor_Array_Alloc.
typedef void(* | Eet_Descriptor_Array_Free_Callback) (void *mem)
| Callback prototype for Eet_Descriptor_Array_Free.

## Functions
EINA_DEPRECATED EAPI Eet_Data_Descriptor * | eet_data_descriptor_new (const char *name, int size, Eet_Descriptor_List_Next_Callback func_list_next, Eet_Descriptor_List_Append_Callback func_list_append, Eet_Descriptor_List_Data_Callback func_list_data, Eet_Descriptor_List_Free_Callback func_list_free, Eet_Descriptor_Hash_Foreach_Callback func_hash_foreach, Eet_Descriptor_Hash_Add_Callback func_hash_add, Eet_Descriptor_Hash_Free_Callback func_hash_free)
| Creates a new empty data structure descriptor.
EAPI Eet_Data_Descriptor * | eet_data_descriptor_stream_new (const Eet_Data_Descriptor_Class *eddc)
| This function creates a new data descriptor and returns a handle to the new data descriptor.
EAPI Eet_Data_Descriptor * | eet_data_descriptor_file_new (const Eet_Data_Descriptor_Class *eddc)
| This function creates a new data descriptor and returns a handle to the new data descriptor.
EAPI Eina_Bool | eet_eina_stream_data_descriptor_class_set (Eet_Data_Descriptor_Class *eddc, unsigned int eddc_size, const char *name, int size)
| This function is an helper that set all the parameters of an Eet_Data_Descriptor_Class correctly when you use Eina data type with a stream.
EAPI Eina_Bool | eet_eina_file_data_descriptor_class_set (Eet_Data_Descriptor_Class *eddc, unsigned int eddc_size, const char *name, int size)
| This function is an helper that set all the parameter of an Eet_Data_Descriptor_Class correctly when you use Eina data type with a file.
EAPI void | eet_data_descriptor_free (Eet_Data_Descriptor *edd)
| This function frees a data descriptor when it is not needed anymore.
EAPI const char * | eet_data_descriptor_name_get (const Eet_Data_Descriptor *edd)
| This function returns the name of a data descriptor.
EAPI void | eet_data_descriptor_element_add (Eet_Data_Descriptor *edd, const char *name, int type, int group_type, int offset, int count, const char *counter_name, Eet_Data_Descriptor *subtype)
| This function is an internal used by macros.
EAPI void * | eet_data_read (Eet_File *ef, Eet_Data_Descriptor *edd, const char *name)
| Reads a data structure from an eet file and decodes it.
EAPI int | eet_data_write (Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const void *data, int compress)
| Writes a data structure from memory and store in an eet file.
EAPI int | eet_data_text_dump (const void *data_in, int size_in, Eet_Dump_Callback dumpfunc, void *dumpdata)
| Dumps an eet encoded data structure into ascii text.
EAPI void * | eet_data_text_undump (const char *text, int textlen, int *size_ret)
| Takes an ascii encoding from eet_data_text_dump() and re-encode in binary.
EAPI int | eet_data_dump (Eet_File *ef, const char *name, Eet_Dump_Callback dumpfunc, void *dumpdata)
| Dumps an eet encoded data structure from an eet file into ascii text.
EAPI int | eet_data_undump (Eet_File *ef, const char *name, const char *text, int textlen, int compress)
| Takes an ascii encoding from eet_data_dump() and re-encode in binary.
EAPI void * | eet_data_descriptor_decode (Eet_Data_Descriptor *edd, const void *data_in, int size_in)
| Decodes a data structure from an arbitrary location in memory.
EAPI void * | eet_data_descriptor_encode (Eet_Data_Descriptor *edd, const void *data_in, int *size_ret)
| Encodes a dsata struct to memory and return that encoded data.

## Detailed Description

Convenience functions to serialize and parse complex data structures to binary blobs.

While Eet core just handles binary blobs, it is often required to save some structured data of different types, such as strings, integers, lists, hashes and so on.

Eet can serialize and then parse data types given some construction instructions. These are defined in two levels:

- Eet_Data_Descriptor_Class to tell generic memory handling, such as the size of the type, how to allocate memory, strings, lists, hashes and so on.
- Eet_Data_Descriptor to tell inside such type, the members and their offsets inside the memory blob, their types and names. These members can be simple types or other Eet_Data_Descriptor, allowing hierarchical types to be defined.

Given that C provides no introspection, this process can be quite cumbersome, so we provide lots of macros and convenience functions to aid creating the types.

We make now a quick overview of some of the most commonly used elements of this part of the library. A simple example of a configuration system will work as a somewhat real life example that is still simple enough to follow. Only the relevant sections will be shown here, but you can get the full code here.

Ignoring the included headers, we'll begin by defining our configuration struct.

typedef struct
{
unsigned int version; // it is recommended to use versioned configuration!
const char *name;
int id;
int not_saved_value; // example of not saved data inside!
Eina_Bool enabled;
} My_Conf_Type;
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527

When using Eet, you don't think in matters of what data the program needs to run and which you would like to store. It's all the same and if it makes more sense to keep them together, it's perfectly fine to do so. At the time of telling Eet how your data is comprised you can leave out the things that are runtime only and let Eet take care of the rest for you.

The key used to store the config follows, as well as the variable used to store our data descriptor. This last one is very important. It's the one thing that Eet will use to identify your data, both at the time of writing it to the file and when loading from it.

static const char MY_CONF_FILE_ENTRY[] = "config";
static Eet_Data_Descriptor *_my_conf_descriptor;
Eet_Data_Descriptor
struct _Eet_Data_Descriptor Eet_Data_Descriptor
Opaque handle that have information on a type members.
Definition: Eet.h:2631

Now we'll see how to create this descriptor, so Eet knows how to handle our data later on. Begin our function by declaring an Eet_Data_Descriptor_Class, which is used to create the actual descriptor. This class contains the name of our data type, its size and several functions that dictate how Eet should handle memory to allocate the necessary bits to bring our data to life. You, as a user, will very hardly set this class' contents directly. The most common scenario is to use one of the provided macros that set it using the Eina data types, so that's what we'll be doing across all our examples.

static void
_my_conf_descriptor_init(void)
{
Eet_Data_Descriptor_Class eddc;
// The class describe the functions to use to create the type and its
// full allocated size.
//
// Eina types are very convenient, so use them to create the descriptor,
// so we get eina_list, eina_hash and eina_stringshare automatically!
//
// The STREAM variant is better for configuration files as the values
// will likely change a lot.
//
// The other variant, FILE, is good for caches and things that are just
// appended, but needs to take care when changing strings and files must
// be kept open so mmap()ed strings will be kept alive.
EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc, My_Conf_Type);
_my_conf_descriptor = eet_data_descriptor_stream_new(&eddc);
eet_data_descriptor_stream_new
EAPI Eet_Data_Descriptor * eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc)
This function creates a new data descriptor and returns a handle to the new data descriptor.
Definition: eet_data.c:2084
EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET
#define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type)
This macro is an helper that set all the parameter of an Eet_Data_Descriptor_Class correctly when you...
Definition: Eet.h:3034
_Eet_Data_Descriptor_Class
Instructs Eet about memory management for different needs under serialization and parse process.
Definition: Eet.h:2828

Now that we have our descriptor, we need to make it describe something. We do so by telling it which members of our struct we want it to know about and their types. The eet_data_descriptor_element_add() function takes care of this, but it's too cumbersome for normal use, so several macros are provided that make it easier to handle. Even with them, however, code can get very repetitive and it's not uncommon to define custom macros using them to save on typing.

#define MY_CONF_ADD_BASIC(member, eet_type) \
EET_DATA_DESCRIPTOR_ADD_BASIC \
(_my_conf_descriptor, My_Conf_Type, # member, member, eet_type)
MY_CONF_ADD_BASIC(version, EET_T_UINT);
MY_CONF_ADD_BASIC(name, EET_T_STRING);
MY_CONF_ADD_BASIC(id, EET_T_INT);
MY_CONF_ADD_BASIC(enabled, EET_T_UCHAR);
#undef MY_CONF_ADD_BASIC
} /* _my_conf_descriptor_init */
EET_T_UCHAR
#define EET_T_UCHAR
Data type: unsigned char.
Definition: Eet.h:2585
EET_T_STRING
#define EET_T_STRING
Data type: char *.
Definition: Eet.h:2589
EET_T_INT
#define EET_T_INT
Data type: int.
Definition: Eet.h:2581
EET_T_UINT
#define EET_T_UINT
Data type: unsigned int.
Definition: Eet.h:2587

Now our descriptor knows about the parts of our structure that we are interesting in saving. You can see that not all of them are there, yet Eet will find those that need saving and do the right thing. When loading our data, any non-described fields in the structure will be zeroed, so there's no need to worry about garbage memory in them. Refer to the documentation of EET_DATA_DESCRIPTOR_ADD_BASIC to understand what our macro does.

We are done with our descriptor init function and it's proper to have the relevant shutdown. Proper coding guidelines indiciate that all memory allocated should be freed when the program ends, and since you will most likely keep your descriptor around for the life or your application, it's only right to free it at the end.

static void
_my_conf_descriptor_shutdown(void)
{
eet_data_descriptor_free(_my_conf_descriptor);
} /* _my_conf_descriptor_shutdown */
eet_data_descriptor_free
EAPI void eet_data_descriptor_free(Eet_Data_Descriptor *edd)
This function frees a data descriptor when it is not needed anymore.
Definition: eet_data.c:2104

Not listed here, but included in the full example are functions to create a blank configuration and free it. The first one will only be used when no file exists to load from, or nothing is found in it, but the latter is used regardless of where our data comes from. Unless you are reading direct data from the Eet file, you will be in charge of freeing anything loaded from it.

Now it's time to look at how we can load our config from some file. Begin by opening the Eet file normally.

static My_Conf_Type *
_my_conf_new(void)
{
My_Conf_Type *my_conf = calloc(1, sizeof(My_Conf_Type));
if (!my_conf)
{
fprintf(stderr, "ERROR: could not calloc My_Conf_Type\n");
return NULL;
}

And now we need to read the data from the file and decode it using our descriptor. Fortunately, that's all done in one single step.

my_conf->version = 0x112233;
my_conf->enabled = EINA_TRUE;
return my_conf;
} /* _my_conf_new */
static void
_my_conf_free(My_Conf_Type *my_conf)
{
eina_stringshare_del(my_conf->name);
free(my_conf);
} /* _my_conf_free */
static My_Conf_Type *
_my_conf_load(const char *filename)
{
My_Conf_Type *my_conf;
Eet_File *ef = eet_open(filename, EET_FILE_MODE_READ);
if (!ef)
{
fprintf(stderr, "ERROR: could not open '%s' for read\n", filename);
return NULL;
}
my_conf = eet_data_read(ef, _my_conf_descriptor, MY_CONF_FILE_ENTRY);
if (!my_conf)
goto end;
eet_data_read
EAPI void * eet_data_read(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name)
Reads a data structure from an eet file and decodes it.
Definition: eet_data.c:2379
eet_open
EAPI Eet_File * eet_open(const char *file, Eet_File_Mode mode)
Opens an eet file on disk, and returns a handle to it.
Definition: eet_lib.c:1499
Eet_File
struct _Eet_File Eet_File
Opaque handle that defines an Eet file (or memory).
Definition: Eet.h:527
EET_FILE_MODE_READ
@ EET_FILE_MODE_READ
File is read-only.
Definition: Eet.h:479
eina_stringshare_del
EINA_API void eina_stringshare_del(Eina_Stringshare *str)
Notes that the given string has lost an instance.
Definition: eina_stringshare.c:533
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539

And that's it for all Eet cares about. But since we are dealing with a common case, as is save and load of user configurations, the next fragment of code shows why we have a version field in our struct, and how you can use it to load older configuration files and update them as needed.

if (my_conf->version < 0x112233)
{
fprintf(stderr,
"WARNING: version %#x was too old, upgrading it to %#x\n",
my_conf->version, 0x112233);
my_conf->version = 0x112233;
my_conf->enabled = EINA_TRUE;
}

Finally, close the file and return the newly loaded config data.

end:
eet_close(ef);
return my_conf;
} /* _my_conf_load */
eet_close
EAPI Eet_Error eet_close(Eet_File *ef)
Closes an eet file handle and flush pending writes.
Definition: eet_lib.c:1899

Saving data is just as easy. The full version of the following function includes code to save to a temporary file first, so you can be sure not to lose all your data in the case of a failure mid-writing. You can look at it here.

static Eina_Bool
_my_conf_save(const My_Conf_Type *my_conf,
const char *filename)
{
Eina_Bool ret;
ef = eet_open(tmp, EET_FILE_MODE_WRITE);
if (!ef)
{
fprintf(stderr, "ERROR: could not open '%s' for write\n", tmp);
return EINA_FALSE;
}
ret = eet_data_write
(ef, _my_conf_descriptor, MY_CONF_FILE_ENTRY, my_conf, EINA_TRUE);
eet_close(ef);
eet_data_write
EAPI int eet_data_write(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const void *data, int compress)
Writes a data structure from memory and store in an eet file.
Definition: eet_data.c:2416
EET_FILE_MODE_WRITE
@ EET_FILE_MODE_WRITE
File is write-only.
Definition: Eet.h:480
EINA_FALSE
#define EINA_FALSE
boolean value FALSE (numerical value 0)
Definition: eina_types.h:533
return ret;
} /* _my_conf_save */

To close, our main function, which doesn't do much. Just take some arguments from the command line with the name of the file to load and another one where to save again. If input file doesn't exist, a new config structure will be created and saved to our output file.

The following is a list of more advanced and detailed examples.

- Nested structures and Eet Data Descriptors
- Advanced use of Eet Data Descriptors
- File descriptor data example, with Eet unions and variants
- Eet data cipher/decipher example

## Macro Definition Documentation

## ◆ EET_T_VALUE

#define EET_T_VALUE 17

Data type: pointer to Eina_Value.

Since
  1.8

## ◆ EET_G_UNKNOWN_NESTED

#define EET_G_UNKNOWN_NESTED 107

Unknown nested group type.

Since
  1.8

## ◆ EET_DATA_DESCRIPTOR_CLASS_VERSION

#define EET_DATA_DESCRIPTOR_CLASS_VERSION 4

The version of Eet_Data_Descriptor_Class at the time of the distribution of the sources.

One should define this to its version member so it is compatible with abi changes, or at least will not crash with them.

Examples
  eet-data-file_descriptor_02.c.

## ◆ EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET

#define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET | ( |  | clas,
|  |  | type
| ) |  | (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))

This macro is an helper that set all the parameter of an Eet_Data_Descriptor_Class correctly when you use Eina data type with stream.

Parameters

  clas | The Eet_Data_Descriptor_Class you want to set.
  type | The type of the structure described by this class.

Returns
  EINA_TRUE if the structure was correctly set (The only reason that could make it fail is if you did give wrong parameter).

See also
  eet_data_descriptor_stream_new

Since
  1.2.3

Examples
  eet-data-nested.c, and eet-data-simple.c.

## ◆ EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET

#define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET | ( |  | clas,
|  |  | type
| ) |  | (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))

This macro is an helper that set all the parameter of an Eet_Data_Descriptor_Class correctly when you use Eina data type with file.

Parameters

  clas | The Eet_Data_Descriptor_Class you want to set.
  type | The type of the structure described by this class.

Returns
  `EINA_TRUE` if the structure was correctly set (The only reason that could make it fail is if you did give wrong parameter).

See also
  eet_data_descriptor_file_new

Since
  1.2.3

Examples
  eet-data-file_descriptor_01.c, and eet-data-file_descriptor_02.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_BASIC

#define EET_DATA_DESCRIPTOR_ADD_BASIC | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | type
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, NULL); \
} while(0)
EET_G_UNKNOWN
#define EET_G_UNKNOWN
Unknown group data encoding type.
Definition: Eet.h:2598

Adds a basic data element to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  type | The type of the member to encode.

This macro is a convenience macro provided to add a member to the data descriptor `edd`. The type of the structure is provided as the `struct_type` parameter (for example: struct my_struct). The `name` parameter defines a string that will be used to uniquely name that member of the struct (it is suggested to use the struct member itself). The `member` parameter is the actual struct member itself (for example: values), and `type` is the basic data type of the member which must be one of: EET_T_CHAR, EET_T_SHORT, EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR, EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING.

Since
  1.0.0

Examples
  eet-data-file_descriptor_02.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_SUB

#define EET_DATA_DESCRIPTOR_ADD_SUB | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | subtype
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, subtype); \
} while (0)
EET_T_UNKNOW
#define EET_T_UNKNOW
Unknown data encoding type.
Definition: Eet.h:2578

Adds a sub-element type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  subtype | The type of sub-type struct to add.

This macro lets you easily add a sub-type (a struct that's pointed to by this one). All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the `subtype` being the exception. This must be the data descriptor of the struct that is pointed to by this element.

Since
  1.0.0

## ◆ EET_DATA_DESCRIPTOR_ADD_SUB_NESTED

#define EET_DATA_DESCRIPTOR_ADD_SUB_NESTED | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | subtype
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN_NESTED, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, subtype); \
} while (0)
EET_G_UNKNOWN_NESTED
#define EET_G_UNKNOWN_NESTED
Unknown nested group type.
Definition: Eet.h:2605

Adds a nested sub-element type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  subtype | The type of sub-type struct to add.

This macro lets you easily add a sub-type: a struct that is nested into this one. If your data is pointed by this element instead of being nested, you should use EET_DATA_DESCRIPTOR_ADD_SUB(). All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_SUB().

Since
  1.8.0

## ◆ EET_DATA_DESCRIPTOR_ADD_LIST

#define EET_DATA_DESCRIPTOR_ADD_LIST | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | subtype
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, subtype); \
} while (0)
EET_G_LIST
#define EET_G_LIST
Linked list group type.
Definition: Eet.h:2601

Adds a linked list type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  subtype | The type of linked list member to add.

This macro lets you easily add a linked list of other data types. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the `subtype` being the exception. This must be the data descriptor of the element that is in each member of the linked list to be stored.

Since
  1.0.0

Examples
  eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, and eet-data-nested.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_LIST_STRING

#define EET_DATA_DESCRIPTOR_ADD_LIST_STRING | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_LIST, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, NULL); \
} while (0)

Adds a linked list of string to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.

This macro lets you easily add a linked list of char *. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().

Since
  1.5.0

## ◆ EET_DATA_DESCRIPTOR_ADD_LIST_UINT

#define EET_DATA_DESCRIPTOR_ADD_LIST_UINT | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UINT, EET_G_LIST, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, NULL); \
} while (0)

Adds a linked list of unsigned integers to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.

This macro lets you easily add a linked list of unsigned int. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().

Since
  1.24.0

## ◆ EET_DATA_DESCRIPTOR_ADD_HASH

#define EET_DATA_DESCRIPTOR_ADD_HASH | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | subtype
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, subtype); \
} while (0)
EET_G_HASH
#define EET_G_HASH
Hash table group type.
Definition: Eet.h:2602

Adds a hash type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  subtype | The type of hash member to add.

This macro lets you easily add a hash of other data types. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the `subtype` being the exception. This must be the data descriptor of the element that is in each member of the hash to be stored. The hash keys must be strings.

Since
  1.0.0

Examples
  eet-data-file_descriptor_01.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_HASH_STRING

#define EET_DATA_DESCRIPTOR_ADD_HASH_STRING | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, NULL); \
} while (0)

Adds a hash of string to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.

This macro lets you easily add a hash of string elements. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH().

Since
  1.3.4

## ◆ EET_DATA_DESCRIPTOR_ADD_HASH_VALUE

#define EET_DATA_DESCRIPTOR_ADD_HASH_VALUE | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_VALUE, EET_G_HASH, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
0, /* 0, */ NULL, NULL); \
} while (0)
EET_T_VALUE
#define EET_T_VALUE
Data type: pointer to Eina_Value.
Definition: Eet.h:2595

Adds a hash of generic value storage to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.

This macro lets you easily add a hash of value elements. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH().

Since
  1.18

## ◆ EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY

#define EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | type
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
sizeof(___ett.member) / \
sizeof(___ett.member[0]), \
NULL, NULL); \
} while(0)
EET_G_ARRAY
#define EET_G_ARRAY
Fixed size array group type.
Definition: Eet.h:2599

Adds an array of basic data elements to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  type | The type of the member to encode.

This macro lets you easily add a fixed size array of basic data types. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). The array must be defined with a fixed size in the declaration of the struct containing it.

Since
  1.5.0

## ◆ EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY

#define EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | type
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, type, EET_G_VAR_ARRAY, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
(char *)(& (___ett.member ## _count)) - \
(char *)(& (___ett)), \
NULL, \
NULL); \
} while(0)
EET_G_VAR_ARRAY
#define EET_G_VAR_ARRAY
Variable size array group type.
Definition: Eet.h:2600

Adds a variable array of basic data elements to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  type | The type of the member to encode.

This macro lets you easily add a variable size array of basic data types. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have a struct member (of type EET_T_INT) called member_count (note the _count appended to the member) that holds the number of items in the array. This array will be allocated separately to the struct it is in.

Since
  1.6.0

## ◆ EET_DATA_DESCRIPTOR_ADD_ARRAY

#define EET_DATA_DESCRIPTOR_ADD_ARRAY | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | subtype
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
/* 0, */ sizeof(___ett.member) / \
sizeof(___ett.member[0]), NULL, subtype); \
} while (0)

Adds a fixed size array type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  subtype | The type of hash member to add.

This macro lets you easily add a fixed size array of other data types. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the `subtype` being the exception. This must be the data descriptor of the element that is in each member of the array to be stored. The array must be defined with a fixed size in the declaration of the struct containing it.

Since
  1.0.2

## ◆ EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY

#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | subtype
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, \
name, \
EET_T_UNKNOW, \
EET_G_VAR_ARRAY, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
(char *)(& (___ett.member ## _count)) - \
(char *)(& (___ett)), \
/* 0, */ NULL, \
subtype); \
} while (0)

Adds a variable size array type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  subtype | The type of hash member to add.

This macro lets you easily add a variable size array of other data types. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the `subtype` being the exception. This must be the data descriptor of the element that is in each member of the array to be stored. This assumes you have a struct member (of type EET_T_INT) called member_count (note the _count appended to the member) that holds the number of items in the array. This array will be allocated separately to the struct it is in.

Since
  1.0.2

Examples
  eet-data-file_descriptor_01.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING

#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, \
name, \
EET_T_STRING, \
EET_G_VAR_ARRAY, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
(char *)(& (___ett.member ## _count)) - \
(char *)(& (___ett)), \
/* 0, */ NULL, \
NULL); \
} while (0)

Adds a variable size array type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.

This macro lets you easily add a variable size array of strings. All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().

Note
  The strings in this array will be loaded as a single blob of memory.

Since
  1.4.0

## ◆ EET_DATA_DESCRIPTOR_ADD_UNION

#define EET_DATA_DESCRIPTOR_ADD_UNION | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | type_member,
|  |  | unified_type
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
(char *)(& (___ett.type_member)) - \
(char *)(& (___ett)), \
NULL, unified_type); \
} while (0)
EET_G_UNION
#define EET_G_UNION
Union group type.
Definition: Eet.h:2603

Adds an union type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  type_member | The member that give hints on what is in the union.
  unified_type | Describe all possible type the union could handle.

This macro lets you easily add an union with a member that specify what is inside. The `unified_type` is an Eet_Data_Descriptor, but only the entry that match the name returned by type_get will be used for each serialized data. The type_get and type_set callback of unified_type should be defined.

Since
  1.2.4

See also
  Eet_Data_Descriptor_Class

Examples
  eet-data-file_descriptor_02.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_VARIANT

#define EET_DATA_DESCRIPTOR_ADD_VARIANT | ( |  | edd,
|  |  | struct_type,
|  |  | name,
|  |  | member,
|  |  | type_member,
|  |  | unified_type
| ) |  |

Value:
do { \
struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT, \
(char *)(& (___ett.member)) - \
(char *)(& (___ett)), \
(char *)(& (___ett.type_member)) - \
(char *)(& (___ett)), \
NULL, unified_type); \
} while (0)
EET_G_VARIANT
#define EET_G_VARIANT
Selectable subtype group.
Definition: Eet.h:2604

Adds a automatically selectable type to a data descriptor.

Parameters

  edd | The data descriptor to add the type to.
  struct_type | The type of the struct.
  name | The string name to use to encode/decode this member (must be a constant global and never change).
  member | The struct member itself to be encoded.
  type_member | The member that give hints on what is in the union.
  unified_type | Describe all possible type the union could handle.

This macro lets you easily define what the content of `member` points to depending of the content of `type_member`. The type_get and type_set callback of unified_type should be defined. If the the type is not know at the time of restoring it, eet will still call type_set of `unified_type` but the pointer will be set to a serialized binary representation of what eet know. This make it possible, to save this pointer again by just returning the string given previously and telling it by setting unknow to EINA_TRUE.

Since
  1.2.4

See also
  Eet_Data_Descriptor_Class

Examples
  eet-data-file_descriptor_02.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_MAPPING

#define EET_DATA_DESCRIPTOR_ADD_MAPPING | ( |  | unified_type,
|  |  | name,
|  |  | subtype
| ) |  |

Value:
eet_data_descriptor_element_add(unified_type, \
name, \
EET_T_UNKNOW, \
EET_G_UNKNOWN, \
0, \
0, \
NULL, \
subtype)
eet_data_descriptor_element_add
EAPI void eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, const char *name, int type, int group_type, int offset, int count, const char *counter_name, Eet_Data_Descriptor *subtype)
This function is an internal used by macros.
Definition: eet_data.c:2125

Adds a mapping to a data descriptor that will be used by union, variant or inherited type.

Parameters

  unified_type | The data descriptor to add the mapping to.
  name | The string name to get/set type.
  subtype | The matching data descriptor.

Since
  1.2.4

See also
  Eet_Data_Descriptor_Class

Examples
  eet-data-file_descriptor_02.c.

## ◆ EET_DATA_DESCRIPTOR_ADD_MAPPING_BASIC

#define EET_DATA_DESCRIPTOR_ADD_MAPPING_BASIC | ( |  | unified_type,
|  |  | name,
|  |  | basic_type
| ) |  |

Value:
eet_data_descriptor_element_add(unified_type, \
name, \
basic_type, \
EET_G_UNKNOWN, \
0, \
0, \
NULL, \
NULL)

Adds a mapping of a basic type to a data descriptor that will be used by a union type.

Parameters

  unified_type | The data descriptor to add the mapping to.
  name | The string name to get/set type.
  basic_type | The matching basic type.

Since
  1.8

See also
  Eet_Data_Descriptor_Class

Examples
  eet-data-file_descriptor_02.c.

## Typedef Documentation

## ◆ Eet_Data_Descriptor

Eet_Data_Descriptor

Opaque handle that have information on a type members.

Descriptors are created using an Eet_Data_Descriptor_Class, and they describe the contents of the structure that will be serialized by Eet. Not all members need be described by it, just those that should be handled by Eet. This way it's possible to have one structure with both data to be saved to a file, like application configuration, and runtime information that would be meaningless to store, but is appropriate to keep together during the program execution. The members are added by means of EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(), EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH() or eet_data_descriptor_element_add().

See also
  eet_data_descriptor_stream_new()
  eet_data_descriptor_file_new()
  eet_data_descriptor_free()

## ◆ Eet_Data_Descriptor_Class

Eet_Data_Descriptor_Class

Instructs Eet about memory management for different needs under serialization and parse process.

Callback protoype for Eet_Dump.

Parameters

  data | To passe to the callback
  str | The string to dump

## ◆ Eet_Descriptor_Hash_Foreach_Callback_Callback

Eet_Descriptor_Hash_Foreach_Callback_Callback

Callback prototype for Eet_Descriptor_Hash_Foreach_Callback.

Parameters

  h | The hash
  k | The key
  dt | The data
  fdt | The data passed to the callback

Returns
  An integer

## ◆ Eet_Descriptor_Mem_Alloc_Callback

Eet_Descriptor_Mem_Alloc_Callback

Callback prototype for Eet_Descriptor_Mem_Alloc.

Parameters

  size | Is the size of memory to alloc on call of the callback

## ◆ Eet_Descriptor_Mem_Free_Callback

Eet_Descriptor_Mem_Free_Callback

Callback prototype for Eet_Descriptor_Mem_Alloc.

Parameters

  mem | Must be a pointer to free on call of the callback

## ◆ Eet_Descriptor_Str_Alloc_Callback

Eet_Descriptor_Str_Alloc_Callback

Callback prototype for Eet_Descriptor_Str_Alloc.

Parameters

  str | Must be the string to alloc

Returns
  have Must be an allocated char * for the given string

Parameters

  str | The string to allocate

Returns
  An allocated pointer to the string

## ◆ Eet_Descriptor_Str_Free_Callback

Eet_Descriptor_Str_Free_Callback

Callback prototype for Eet_Descriptor_Str_Free.

Parameters

  str | Must be an allocated string to free
  str | The string to free

## ◆ Eet_Descriptor_List_Next_Callback

Eet_Descriptor_List_Next_Callback

Callback prototype for Eet_Descriptor_List_Next.

Parameters

  l | Must be a pointer to the list

Returns
  Must be a pointer to the list

## ◆ Eet_Descriptor_List_Append_Callback

Eet_Descriptor_List_Append_Callback

Callback prototype for Eet_Descriptor_List_Append.

Parameters

  l | Must be a pointer to the list
  d | The data to append to the list

Returns
  Must be a pointer to the list

## ◆ Eet_Descriptor_List_Data_Callback

Eet_Descriptor_List_Data_Callback

Callback prototype for Eet_Descriptor_List_Data.

Parameters

  l | Must be a pointer to the list

Returns
  Must be a pointer to the list

## ◆ Eet_Descriptor_List_Free_Callback

Eet_Descriptor_List_Free_Callback

Callback prototype for Eet_Descriptor_List_Free.

Parameters

  l | Must be a pointer to the list to free

## ◆ Eet_Descriptor_Hash_Foreach_Callback

Eet_Descriptor_Hash_Foreach_Callback

Callback for Eet_Descriptor_Hash_Foreach.

Parameters

  h | The hash
  func | The function callback to call on each iteration
  fdt | The data to pass to the callbac setted in param func

## ◆ Eet_Descriptor_Hash_Add_Callback

Eet_Descriptor_Hash_Add_Callback

Callback prototype for Eet_Descriptor_Hash_Add.

Parameters

  h | The hash
  k | The key
  d | The data to associate with the 'k' key

## ◆ Eet_Descriptor_Hash_Free_Callback

Eet_Descriptor_Hash_Free_Callback

Callback prototype for Eet_Descriptor_Hash_Free.

Parameters

  h | The hash to free

## ◆ Eet_Descriptor_Type_Get_Callback

Eet_Descriptor_Type_Get_Callback

Callback prototype for Eet_Descriptor_Type_Get.

Parameters

  data | Data to pass to the callback
  unknow | Eina_Bool FIXME

## ◆ Eet_Descriptor_Type_Set_Callback

Eet_Descriptor_Type_Set_Callback

Callback prototype for Eet_Descriptor_Type_Set.

Parameters

  type | The type to set
  data | To pass to the callback
  unknow | Eina_Bool FIXME

## ◆ Eet_Descriptor_Array_Alloc_Callback

Eet_Descriptor_Array_Alloc_Callback

Callback prototype for Eet_Descriptor_Array_Alloc.

Parameters

  size | The size of the array

## ◆ Eet_Descriptor_Array_Free_Callback

Eet_Descriptor_Array_Free_Callback

Callback prototype for Eet_Descriptor_Array_Free.

Parameters

  size | The size of the array

## Function Documentation

## ◆ eet_data_descriptor_new()

EINA_DEPRECATED EAPI Eet_Data_Descriptor * eet_data_descriptor_new | ( | const char * | name,
|  | int | size,
|  | Eet_Descriptor_List_Next_Callback | func_list_next,
|  | Eet_Descriptor_List_Append_Callback | func_list_append,
|  | Eet_Descriptor_List_Data_Callback | func_list_data,
|  | Eet_Descriptor_List_Free_Callback | func_list_free,
|  | Eet_Descriptor_Hash_Foreach_Callback | func_hash_foreach,
|  | Eet_Descriptor_Hash_Add_Callback | func_hash_add,
|  | Eet_Descriptor_Hash_Free_Callback | func_hash_free
| ) |  |

Creates a new empty data structure descriptor.

Deprecated:
  use eet_data_descriptor_stream_new() or eet_data_descriptor_file_new()

Parameters

  name | The string name of this data structure (most be a global constant and never change).
  size | The size of the struct (in bytes).
  func_list_next | The function to get the next list node.
  func_list_append | The function to append a member to a list.
  func_list_data | The function to get the data from a list node.
  func_list_free | The function to free an entire linked list.
  func_hash_foreach | The function to iterate through all hash table entries.
  func_hash_add | The function to add a member to a hash table.
  func_hash_free | The function to free an entire hash table.

Returns
  A new empty data descriptor.

This function creates a new data descriptor and returns a handle to the new data descriptor. On creation it will be empty, containing no contents describing anything other than the shell of the data structure.

You add structure members to the data descriptor using the macros EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are adding to the description.

Once you have described all the members of a struct you want loaded, or saved eet can load and save those members for you, encode them into endian-independent serialised data chunks for transmission across a a network or more.

The function pointers to the list and hash table functions are only needed if you use those data types, else you can pass NULL instead.

Since
  1.0.0

References _Eet_Data_Descriptor_Class::hash_add, _Eet_Data_Descriptor_Class::hash_foreach, _Eet_Data_Descriptor_Class::hash_free, _Eet_Data_Descriptor_Class::list_append, _Eet_Data_Descriptor_Class::list_data, _Eet_Data_Descriptor_Class::list_free, _Eet_Data_Descriptor_Class::list_next, _Eet_Data_Descriptor_Class::name, _Eet_Data_Descriptor_Class::size, and _Eet_Data_Descriptor_Class::version.

## ◆ eet_data_descriptor_stream_new()

EAPI Eet_Data_Descriptor * eet_data_descriptor_stream_new | ( | const Eet_Data_Descriptor_Class * | eddc | ) |

This function creates a new data descriptor and returns a handle to the new data descriptor.

On creation it will be empty, containing no contents describing anything other than the shell of the data structure.

Parameters

  eddc | The class from where to create the data descriptor.

Returns
  A handle to the new data descriptor.

You add structure members to the data descriptor using the macros EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are adding to the description.

Once you have described all the members of a struct you want loaded or saved, eet can load and save those members for you, encode them into endian-independent serialised data chunks for transmission across a network or more.

This function specially ignores str_direct_alloc and str_direct_free. It is useful when the eet_data you are reading doesn't have a dictionary, like network stream or IPC. It also mean that all string will be allocated and duplicated in memory.

Since
  1.2.3

Examples
  eet-data-file_descriptor_02.c, eet-data-nested.c, and eet-data-simple.c.

## ◆ eet_data_descriptor_file_new()

EAPI Eet_Data_Descriptor * eet_data_descriptor_file_new | ( | const Eet_Data_Descriptor_Class * | eddc | ) |

This function creates a new data descriptor and returns a handle to the new data descriptor.

On creation it will be empty, containing no contents describing anything other than the shell of the data structure.

Parameters

  eddc | The class from where to create the data descriptor.

Returns
  A handle to the new data descriptor.

You add structure members to the data descriptor using the macros EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are adding to the description.

Once you have described all the members of a struct you want loaded or saved, eet can load and save those members for you, encode them into endian-independent serialised data chunks for transmission across a a network or more.

This function uses str_direct_alloc and str_direct_free. It is useful when the eet_data you are reading come from a file and have a dictionary. This will reduce memory use and improve the possibility for the OS to page this string out. However, the load speed and memory saving comes with some drawbacks to keep in mind. If you never modify the contents of the structures loaded from the file, all you need to remember is that closing the eet file will make the strings go away. On the other hand, should you need to free a string, before doing so you have to verify that it's not part of the eet dictionary. You can do this in the following way, assuming `ef` is a valid Eet_File and `str` is a string loaded from said file.

void eet_string_free(Eet_File *ef, const char *str)
{
Eet_Dictionary *dict = eet_dictionary_get(ef);
if (dict && eet_dictionary_string_check(dict, str))
{
// The file contains a dictionary and the given string is a part of
// of it, so we can't free it, just return.
return;
}
// We assume eina_stringshare was used on the descriptor
eina_stringshare_del(str);
}
eet_dictionary_string_check
EAPI int eet_dictionary_string_check(Eet_Dictionary *ed, const char *string)
Checks if a given string comes from a given dictionary.
Definition: eet_dictionary.c:598
eet_dictionary_get
EAPI Eet_Dictionary * eet_dictionary_get(Eet_File *ef)
Returns a handle to the shared string dictionary of the Eet file.
Definition: eet_lib.c:2564
Eet_Dictionary
struct _Eet_Dictionary Eet_Dictionary
Opaque handle that defines a file-backed (mmaped) dictionary of strings.
Definition: Eet.h:533

Since
  1.2.3

Examples
  eet-data-file_descriptor_01.c, and eet-data-file_descriptor_02.c.

## ◆ eet_eina_stream_data_descriptor_class_set()

EAPI Eina_Bool eet_eina_stream_data_descriptor_class_set | ( | Eet_Data_Descriptor_Class * | eddc,
|  | unsigned int | eddc_size,
|  | const char * | name,
|  | int | size
| ) |  |

This function is an helper that set all the parameters of an Eet_Data_Descriptor_Class correctly when you use Eina data type with a stream.

Parameters

  eddc | The Eet_Data_Descriptor_Class you want to set.
  eddc_size | The size of the Eet_Data_Descriptor_Class at the compilation time.
  name | The name of the structure described by this class.
  size | The size of the structure described by this class.

Returns
  `EINA_TRUE` if the structure was correctly set (The only reason that could make it fail is if you did give wrong parameter).

Note
  Unless there's a very specific reason to use this function directly, the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended.

Since
  1.2.3

References _Eet_Data_Descriptor_Class::array_alloc, _Eet_Data_Descriptor_Class::array_free, EET_DATA_DESCRIPTOR_CLASS_VERSION, EINA_FALSE, eina_list_append(), eina_list_free(), eina_stringshare_add(), eina_stringshare_del(), EINA_TRUE, _Eet_Data_Descriptor_Class::hash_add, _Eet_Data_Descriptor_Class::hash_foreach, _Eet_Data_Descriptor_Class::hash_free, _Eet_Data_Descriptor_Class::list_append, _Eet_Data_Descriptor_Class::list_data, _Eet_Data_Descriptor_Class::list_free, _Eet_Data_Descriptor_Class::list_next, _Eet_Data_Descriptor_Class::mem_alloc, _Eet_Data_Descriptor_Class::mem_free, _Eet_Data_Descriptor_Class::name, _Eet_Data_Descriptor_Class::size, _Eet_Data_Descriptor_Class::str_alloc, _Eet_Data_Descriptor_Class::str_direct_alloc, _Eet_Data_Descriptor_Class::str_direct_free, _Eet_Data_Descriptor_Class::str_free, _Eet_Data_Descriptor_Class::type_get, _Eet_Data_Descriptor_Class::type_set, and _Eet_Data_Descriptor_Class::version.

Referenced by eet_eina_file_data_descriptor_class_set().

## ◆ eet_eina_file_data_descriptor_class_set()

EAPI Eina_Bool eet_eina_file_data_descriptor_class_set | ( | Eet_Data_Descriptor_Class * | eddc,
|  | unsigned int | eddc_size,
|  | const char * | name,
|  | int | size
| ) |  |

This function is an helper that set all the parameter of an Eet_Data_Descriptor_Class correctly when you use Eina data type with a file.

Parameters

  eddc | The Eet_Data_Descriptor_Class you want to set.
  eddc_size | The size of the Eet_Data_Descriptor_Class at the compilation time.
  name | The name of the structure described by this class.
  size | The size of the structure described by this class.

Returns
  `EINA_TRUE` if the structure was correctly set (The only reason that could make it fail is if you did give wrong parameter).

Note
  Unless there's a very specific reason to use this function directly, the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended.

Since
  1.2.3

References EET_DATA_DESCRIPTOR_CLASS_VERSION, eet_eina_stream_data_descriptor_class_set(), EINA_FALSE, EINA_TRUE, _Eet_Data_Descriptor_Class::hash_add, _Eet_Data_Descriptor_Class::str_direct_alloc, _Eet_Data_Descriptor_Class::str_direct_free, and _Eet_Data_Descriptor_Class::version.

## ◆ eet_data_descriptor_free()

EAPI void eet_data_descriptor_free | ( | Eet_Data_Descriptor * | edd | ) |

This function frees a data descriptor when it is not needed anymore.

Parameters

  edd | The data descriptor to free.

This function takes a data descriptor handle as a parameter and frees all data allocated for the data descriptor and the handle itself. After this call the descriptor is no longer valid.

Since
  1.0.0

Examples
  eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, and eet-data-simple.c.

References eet_data_descriptor_free().

Referenced by eet_data_descriptor_free().

## ◆ eet_data_descriptor_name_get()

EAPI const char * eet_data_descriptor_name_get | ( | const Eet_Data_Descriptor * | edd | ) |

This function returns the name of a data descriptor.

Parameters

  edd | The data descriptor to get name.

Returns
  The name of the data descriptor.

Since
  1.8.0

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## ◆ eet_data_descriptor_element_add()

EAPI void eet_data_descriptor_element_add | ( | Eet_Data_Descriptor * | edd,
|  | const char * | name,
|  | int | type,
|  | int | group_type,
|  | int | offset,
|  | int | count,
|  | const char * | counter_name,
|  | Eet_Data_Descriptor * | subtype
| ) |  |

This function is an internal used by macros.

This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is complex to use by hand and should be left to be used by the macros, and thus is not documented.

Parameters

  edd | The data descriptor handle to add element (member).
  name | The name of element to be serialized.
  type | The type of element to be serialized, like EET_T_INT. If EET_T_UNKNOW, then it is considered to be a group, list or hash.
  group_type | If element type is EET_T_UNKNOW, then the `group_type` will specify if it is a list (EET_G_LIST), array (EET_G_ARRAY) and so on. If EET_G_UNKNOWN, then the member is a subtype (pointer to another type defined by another Eet_Data_Descriptor).
  offset | byte offset inside the source memory to be serialized.
  count | number of elements (if EET_G_ARRAY or EET_G_VAR_ARRAY).
  counter_name | variable that defines the name of number of elements.
  subtype | If contains a subtype, then its data descriptor.

Since
  1.0.0

References eet_data_descriptor_element_add(), EET_G_LAST, EET_G_UNION, EET_G_UNKNOWN, EET_G_VAR_ARRAY, EET_G_VARIANT, EET_T_CHAR, EET_T_F32P32, EET_T_F8P24, EET_T_LAST, EET_T_ULONG_LONG, EET_T_UNKNOW, EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN, and EINA_TRUE.

Referenced by eet_data_descriptor_element_add().

## ◆ eet_data_read()

EAPI void * eet_data_read | ( | Eet_File * | ef,
|  | Eet_Data_Descriptor * | edd,
|  | const char * | name
| ) |  |

Reads a data structure from an eet file and decodes it.

Parameters

  ef | The eet file handle to read from.
  edd | The data descriptor handle to use when decoding.
  name | The key the data is stored under in the eet file.

Returns
  A pointer to the decoded data structure.

This function decodes a data structure stored in an eet file, returning a pointer to it if it decoded successfully, or NULL on failure. This can save a programmer dozens of hours of work in writing configuration file parsing and writing code, as eet does all that work for the program and presents a program-friendly data structure, just as the programmer likes. Eet can handle members being added or deleted from the data in storage and safely zero-fills unfilled members if they were not found in the data. It checks sizes and headers whenever it reads data, allowing the programmer to not worry about corrupt data.

Once a data structure has been described by the programmer with the fields they wish to save or load, storing or retrieving a data structure from an eet file, or from a chunk of memory is as simple as a single function call.

See also
  eet_data_read_cipher()

Since
  1.0.0

Examples
  eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, and eet-data-simple.c.

References eet_data_read_cipher().

Referenced by edje_edit_group_copy(), and edje_mmap_color_class_used_list().

## ◆ eet_data_write()

EAPI int eet_data_write | ( | Eet_File * | ef,
|  | Eet_Data_Descriptor * | edd,
|  | const char * | name,
|  | const void * | data,
|  | int | compress
| ) |  |

Writes a data structure from memory and store in an eet file.

Parameters

  ef | The eet file handle to write to.
  edd | The data descriptor to use when encoding.
  name | The key to store the data under in the eet file.
  data | A pointer to the data structure to save and encode.
  compress | Compression flags for storage.

Returns
  bytes Written on successful write, `0` on failure.

This function is the reverse of eet_data_read(), saving a data structure to an eet file. The file must have been opening in write mode and the data will be kept in memory until the file is either closed or eet_sync() is called to flush any unwritten changes.

See also
  eet_data_write_cipher()

Since
  1.0.0

Examples
  eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, and eet-data-simple.c.

References eet_data_write_cipher().

Referenced by edje_edit_group_copy(), and edje_edit_without_source_save().

## ◆ eet_data_text_dump()

EAPI int eet_data_text_dump | ( | const void * | data_in,
|  | int | size_in,
|  | Eet_Dump_Callback | dumpfunc,
|  | void * | dumpdata
| ) |  |

Dumps an eet encoded data structure into ascii text.

Parameters

  data_in | The pointer to the data to decode into a struct.
  size_in | The size of the data pointed to in bytes.
  dumpfunc | The function to call passed a string when new data is converted to text
  dumpdata | The data to pass to the `dumpfunc` callback.

Returns
  `1` on success, `0` on failure

This function will take a chunk of data encoded by eet_data_descriptor_encode() and convert it into human readable ascii text. It does this by calling the `dumpfunc` callback for all new text that is generated. This callback should append to any existing text buffer and will be passed the pointer `dumpdata` as a parameter as well as a string with new text to be appended.

Example:

void output(void *data, const char *string)
{
printf("%s", string);
}
void dump(const char *file)
{
FILE *f;
int len;
void *data;
f = fopen(file, "rb");
fseek(f, 0, SEEK_END);
len = ftell(f);
rewind(f);
data = malloc(len);
fread(data, len, 1, f);
fclose(f);
eet_data_text_dump(data, len, output, NULL);
}
eet_data_text_dump
EAPI int eet_data_text_dump(const void *data_in, int size_in, Eet_Dump_Callback dumpfunc, void *dumpdata)
Dumps an eet encoded data structure into ascii text.
Definition: eet_data.c:4931

See also
  eet_data_text_dump_cipher()

Since
  1.0.0

References eet_data_text_dump_cipher().

## ◆ eet_data_text_undump()

EAPI void * eet_data_text_undump | ( | const char * | text,
|  | int | textlen,
|  | int * | size_ret
| ) |  |

Takes an ascii encoding from eet_data_text_dump() and re-encode in binary.

Parameters

  text | The pointer to the string data to parse and encode.
  textlen | The size of the string in bytes (not including 0 byte terminator).
  size_ret | This gets filled in with the encoded data blob size in bytes.

Returns
  The encoded data on success, NULL on failure.

This function will parse the string pointed to by `text` and return an encoded data lump the same way eet_data_descriptor_encode() takes an in-memory data struct and encodes into a binary blob. `text` is a normal C string.

See also
  eet_data_text_undump_cipher()

Since
  1.0.0

References eet_data_text_undump_cipher().

## ◆ eet_data_dump()

EAPI int eet_data_dump | ( | Eet_File * | ef,
|  | const char * | name,
|  | Eet_Dump_Callback | dumpfunc,
|  | void * | dumpdata
| ) |  |

Dumps an eet encoded data structure from an eet file into ascii text.

Parameters

  ef | A valid eet file handle.
  name | Name of the entry. eg: "/base/file_i_want".
  dumpfunc | The function to call passed a string when new data is converted to text
  dumpdata | The data to pass to the `dumpfunc` callback.

Returns
  `1` on success, `0` on failure

This function will take an open and valid eet file from eet_open() request the data encoded by eet_data_descriptor_encode() corresponding to the key `name` and convert it into human readable ascii text. It does this by calling the `dumpfunc` callback for all new text that is generated. This callback should append to any existing text buffer and will be passed the pointer `dumpdata` as a parameter as well as a string with new text to be appended.

See also
  eet_data_dump_cipher()

Since
  1.0.0

References eet_data_dump_cipher().

## ◆ eet_data_undump()

EAPI int eet_data_undump | ( | Eet_File * | ef,
|  | const char * | name,
|  | const char * | text,
|  | int | textlen,
|  | int | compress
| ) |  |

Takes an ascii encoding from eet_data_dump() and re-encode in binary.

Parameters

  ef | A valid eet file handle.
  name | Name of the entry. eg: "/base/file_i_want".
  text | The pointer to the string data to parse and encode.
  textlen | The size of the string in bytes (not including 0 byte terminator).
  compress | Compression flags (1 == compress, 0 = don't compress).

Returns
  `1` on success, `0` on failure

This function will parse the string pointed to by `text`, encode it the same way eet_data_descriptor_encode() takes an in-memory data struct and encodes into a binary blob.

The data (optionally compressed) will be in ram, pending a flush to disk (it will stay in ram till the eet file handle is closed though).

See also
  eet_data_undump_cipher()

Since
  1.0.0

References eet_data_undump_cipher().

## ◆ eet_data_descriptor_decode()

EAPI void * eet_data_descriptor_decode | ( | Eet_Data_Descriptor * | edd,
|  | const void * | data_in,
|  | int | size_in
| ) |  |

Decodes a data structure from an arbitrary location in memory.

Parameters

  edd | The data descriptor to use when decoding.
  data_in | The pointer to the data to decode into a struct.
  size_in | The size of the data pointed to in bytes.

Returns
  NULL on failure, or a valid decoded struct pointer on success.

This function will decode a data structure that has been encoded using eet_data_descriptor_encode(), and return a data structure with all its elements filled out, if successful, or NULL on failure.

The data to be decoded is stored at the memory pointed to by `data_in`, and is described by the descriptor pointed to by `edd`. The data size is passed in as the value to `size_in`, and must be greater than 0 to succeed.

This function is useful for decoding data structures delivered to the application by means other than an eet file, such as an IPC or socket connection, raw files, shared memory etc.

Please see eet_data_read() for more information.

See also
  eet_data_descriptor_decode_cipher()

Since
  1.0.0

References eet_data_descriptor_decode_cipher().

## ◆ eet_data_descriptor_encode()

EAPI void * eet_data_descriptor_encode | ( | Eet_Data_Descriptor * | edd,
|  | const void * | data_in,
|  | int * | size_ret
| ) |  |

Encodes a dsata struct to memory and return that encoded data.

Parameters

  edd | The data descriptor to use when encoding.
  data_in | The pointer to the struct to encode into data.
  size_ret | pointer to the an int to be filled with the decoded size.

Returns
  NULL on failure, or a valid encoded data chunk on success.

This function takes a data structure in memory and encodes it into a serialised chunk of data that can be decoded again by eet_data_descriptor_decode(). This is useful for being able to transmit data structures across sockets, pipes, IPC or shared file mechanisms, without having to worry about memory space, machine type, endianness etc.

The parameter `edd` must point to a valid data descriptor, and `data_in` must point to the right data structure to encode. If not, the encoding may fail.

On success a non NULL valid pointer is returned and what `size_ret` points to is set to the size of this decoded data, in bytes. When the encoded data is no longer needed, call free() on it. On failure NULL is returned and what `size_ret` points to is set to 0.

Please see eet_data_write() for more information.

See also
  eet_data_descriptor_encode_cipher()

Since
  1.0.0

References eet_data_descriptor_encode_cipher().