Man Linux: Main Page and Category List

NAME

       Eet Data Serialization -

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

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

   Modules
       Eet Data Serialization using A Ciphers

       Most of the Eet Data Serialization have alternative versions that
       accounts for ciphers to protect their content.

   Defines
       #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_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_LAST   107
           Last group type.
       #define EET_I_LIMIT   128
           Other type exist but are reserved for internal purpose.
       #define EET_DATA_DESCRIPTOR_CLASS_VERSION   3
           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, #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, #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)
           Add a basic data element to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member,
           subtype)
           Add a sub-element type to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member,
           subtype)
           Add a linked list type to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member,
           subtype)
           Add a hash type to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member,
           subtype)
           Add a fixed size array type to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name,
           member, subtype)
           Add a variable size array type to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member,
           type_member, unified_type)
           Add an union type to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member,
           type_member, unified_type)
           Add a automatically selectable type to a data descriptor.
       #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype)
           eet_data_descriptor_element_add(unified_type, name, EET_T_UNKNOW,
           EET_G_UNKNOWN, 0, 0, NULL, subtype);
           Add a mapping to a data descriptor that will be used by union,
           variant or inherited 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.

   Functions
       EINA_DEPRECATED EAPI Eet_Data_Descriptor * eet_data_descriptor_new
           (const char *name, int size, void *(*func_list_next)(void *l), void
           *(*func_list_append)(void *l, void *d), void
           *(*func_list_data)(void *l), void *(*func_list_free)(void *l),
           void(*func_hash_foreach)(void *h, int(*func)(void *h, const char
           *k, void *dt, void *fdt), void *fdt), void *(*func_hash_add)(void
           *h, const char *k, void *d), void(*func_hash_free)(void *h))
           Create 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 descriptore 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 descriptore and returns a handle
           to the new data descriptor.
       EAPI Eina_Bool eet_eina_stream_data_descriptor_class_set
           (Eet_Data_Descriptor_Class *eddc, 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 stream.
       EAPI Eina_Bool eet_eina_file_data_descriptor_class_set
           (Eet_Data_Descriptor_Class *eddc, 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 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)
           Read 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)
           Write a data structure from memory and store in an eet file.
       EAPI int eet_data_text_dump (const void *data_in, int size_in,
           void(*dumpfunc)(void *data, const char *str), void *dumpdata)
           Dump an eet encoded data structure into ascii text.
       EAPI void * eet_data_text_undump (const char *text, int textlen, int
           *size_ret)
           Take an ascii encoding from eet_data_text_dump() and re-encode in
           binary.
       EAPI int eet_data_dump (Eet_File *ef, const char *name,
           void(*dumpfunc)(void *data, const char *str), void *dumpdata)
           Dump 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)
           Take 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)
           Decode a data structure from an arbitary location in memory.
       EAPI void * eet_data_descriptor_encode (Eet_Data_Descriptor *edd, const
           void *data_in, int *size_ret)
           Encode 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:

       o 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.

       o 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.

       Example:

        #include <Eet.h>
        #include <Evas.h>

        typedef struct _blah2
        {
           char *string;
        } Blah2;

        typedef struct _blah3
        {
           char *string;
        } Blah3;

        typedef struct _blah
        {
           char character;
           short sixteen;
           int integer;
           long long lots;
           float floating;
           double floating_lots;
           char *string;
           Blah2 *blah2;
           Eina_List *blah3;
        } Blah;

        int
        main(int argc, char **argv)
        {
           Blah blah;
           Blah2 blah2;
           Blah3 blah3;
           Eet_Data_Descriptor *edd, *edd2, *edd3;
           Eet_Data_Descriptor_Class eddc, eddc2, eddc3;
           void *data;
           int size;
           FILE *f;
           Blah *blah_in;

           eet_init();

           EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc3, Blah3);
           edd3 = eet_data_descriptor_stream_new(&eddc3);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd3, Blah3, 'string3', string, EET_T_STRING);

           EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc2, Blah2);
           edd2 = eet_data_descriptor_stream_new(&eddc2);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd2, Blah2, 'string2', string, EET_T_STRING);

           EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc, Blah);
           edd = eet_data_descriptor_stream_new(&eddc);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, 'character', character, EET_T_CHAR);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, 'sixteen', sixteen, EET_T_SHORT);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, 'integer', integer, EET_T_INT);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, 'lots', lots, EET_T_LONG_LONG);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, 'floating', floating, EET_T_FLOAT);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, 'floating_lots', floating_lots, EET_T_DOUBLE);
           EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, 'string', string, EET_T_STRING);
           EET_DATA_DESCRIPTOR_ADD_SUB(edd, Blah, 'blah2', blah2, edd2);
           EET_DATA_DESCRIPTOR_ADD_LIST(edd, Blah, 'blah3', blah3, edd3);

           blah3.string = 'PANTS';

           blah2.string = 'subtype string here!';

           blah.character = '7';
           blah.sixteen = 0x7777;
           blah.integer = 0xc0def00d;
           blah.lots = 0xdeadbeef31337777;
           blah.floating = 3.141592654;
           blah.floating_lots = 0.777777777777777;
           blah.string = 'bite me like a turnip';
           blah.blah2 = &blah2;
           blah.blah3 = eina_list_append(NULL, &blah3);
           blah.blah3 = eina_list_append(blah.blah3, &blah3);
           blah.blah3 = eina_list_append(blah.blah3, &blah3);
           blah.blah3 = eina_list_append(blah.blah3, &blah3);
           blah.blah3 = eina_list_append(blah.blah3, &blah3);
           blah.blah3 = eina_list_append(blah.blah3, &blah3);
           blah.blah3 = eina_list_append(blah.blah3, &blah3);

           data = eet_data_descriptor_encode(edd, &blah, &size);
           printf('-----DECODING0);
           blah_in = eet_data_descriptor_decode(edd, data, size);

           printf('-----DECODED!0);
           printf('%c0, blah_in->character);
           printf('%x0, (int)blah_in->sixteen);
           printf('%x0, blah_in->integer);
           printf('%lx0, blah_in->lots);
           printf('%f0, (double)blah_in->floating);
           printf('%f0, (double)blah_in->floating_lots);
           printf('%s0, blah_in->string);
           printf('%p0, blah_in->blah2);
           printf('  %s0, blah_in->blah2->string);
             {
                Eina_List *l;
                Blah3 *blah3_in;

                EINA_LIST_FOREACH(blah_in->blah3, l, blah3_in)
                  {
                     printf('%p0, blah3_in);
                     printf('  %s0, blah3_in->string);
                  }
             }
           eet_data_descriptor_free(edd);
           eet_data_descriptor_free(edd2);
           eet_data_descriptor_free(edd3);

           eet_shutdown();

          return 0;
        }

Define Documentation

   #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member,
       subtype) Value:
       {         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);      }

       Add 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 hash to be stored.

       Since:
           1.0.2

   #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type)
       Value:
       {         struct_type ___ett;                 eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN,                                         (char *)(&(___ett.member)) - (char *)(&(___ett)),                                         0, /* 0,  */NULL, NULL);      }

       Add 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
       eet_dictionary_string_check 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

   #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member,
       subtype) Value:
       {         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);      }

       Add 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.

       Since:
           1.0.0

   #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member,
       subtype) Value:
       {         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);      }

       Add 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

   #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype)
       eet_data_descriptor_element_add(unified_type, name, EET_T_UNKNOW,
       EET_G_UNKNOWN, 0, 0, NULL, subtype);
       Add 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

   #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member,
       subtype) Value:
       {         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);      }

       Add 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

   #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member,
       type_member, unified_type) Value:
       {         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);      }

       Add 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

   #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member,
       subtype) Value:
       {         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);      }

       Add 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 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 hash to be stored.

       Since:
           1.0.2

   #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member,
       type_member, unified_type) Value:
       {         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);      }

       Add 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

   #define EET_DATA_DESCRIPTOR_CLASS_VERSION   3
       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.

   #define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(Clas, Type)
       (eet_eina_file_data_descriptor_class_set(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).

       Since:
           1.2.3

   #define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(Clas, Type)
       (eet_eina_stream_data_descriptor_class_set(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).

       Since:
           1.2.3

   #define EET_I_LIMIT   128
       Other type exist but are reserved for internal purpose.

Typedef Documentation

   Eet_Data_Descriptor
       Opaque handle that have information on a type members. 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()

Function Documentation

   EAPI void* eet_data_descriptor_decode (Eet_Data_Descriptor * edd, const
       void * data_in, int size_in)
       Decode a data structure from an arbitary 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, ande 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().

   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 speficy 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_LAST, EET_T_NULL,
       EET_T_STRING, and EET_T_UNKNOW.

       Referenced by eet_data_descriptor_element_add().

   EAPI void* eet_data_descriptor_encode (Eet_Data_Descriptor * edd, const
       void * data_in, int * size_ret)
       Encode 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 structutre 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, endianess
       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().

   EAPI Eet_Data_Descriptor* eet_data_descriptor_file_new (const
       Eet_Data_Descriptor_Class * eddc)
       This function creates a new data descriptore 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 data descriptor to free.

       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-independant serialised data chunks for transmission across a a
       network or more.

       This function use str_direct_alloc and str_direct_free. It is usefull
       when the eet_data you are reading come from a file and have a
       dictionnary. This will reduce memory use, improve the possibility for
       the OS to page this string out. But be carrefull all EET_T_STRING are
       pointer to a mmapped area and it will point to nowhere if you close the
       file. So as long as you use this strings, you need to have the Eet_File
       open.

       Since:
           1.2.3

   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

   EINA_DEPRECATED EAPI Eet_Data_Descriptor* eet_data_descriptor_new (const
       char * name, int size, void *(*)(void *l) func_list_next, void
       *(*)(void *l, void *d) func_list_append, void *(*)(void *l)
       func_list_data, void *(*)(void *l) func_list_free, void(*)(void *h,
       int(*func)(void *h, const char *k, void *dt, void *fdt), void *fdt)
       func_hash_foreach, void *(*)(void *h, const char *k, void *d)
       func_hash_add, void(*)(void *h) func_hash_free)
       Create a new empty data structure descriptor. 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 descriptore 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-independant 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

       Deprecated
           use eet_data_descriptor_stream_new() or
           eet_data_descriptor_file_new()

       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.

   EAPI Eet_Data_Descriptor* eet_data_descriptor_stream_new (const
       Eet_Data_Descriptor_Class * eddc)
       This function creates a new data descriptore 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 data descriptor to free.

       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-independant serialised data chunks for transmission across a a
       network or more.

       This function specially ignore str_direct_alloc and str_direct_free. It
       is usefull when the eet_data you are reading don't have a dictionnary
       like network stream or ipc. It also mean that all string will be
       allocated and duplicated in memory.

       Since:
           1.2.3

   EAPI int eet_data_dump (Eet_File * ef, const char * name, void(*)(void
       *data, const char *str) dumpfunc, void * dumpdata)
       Dump 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().

   EAPI void* eet_data_read (Eet_File * ef, Eet_Data_Descriptor * edd, const
       char * name)
       Read 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

       References eet_data_read_cipher().

   EAPI int eet_data_text_dump (const void * data_in, int size_in,
       void(*)(void *data, const char *str) dumpfunc, void * dumpdata)
       Dump 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, 'r');
          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);
        }

       See also:
           eet_data_text_dump_cipher()

       Since:
           1.0.0

       References eet_data_text_dump_cipher().

   EAPI void* eet_data_text_undump (const char * text, int textlen, int *
       size_ret)
       Take 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().

   EAPI int eet_data_undump (Eet_File * ef, const char * name, const char *
       text, int textlen, int compress)
       Take 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().

   EAPI int eet_data_write (Eet_File * ef, Eet_Data_Descriptor * edd, const
       char * name, const void * data, int compress)
       Write 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 ssave 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.

       See also:
           eet_data_write_cipher()

       Since:
           1.0.0

       References eet_data_write_cipher().

   EAPI Eina_Bool eet_eina_file_data_descriptor_class_set
       (Eet_Data_Descriptor_Class * eddc, 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.
           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).

       Since:
           1.2.3

       References eet_eina_stream_data_descriptor_class_set(),
       _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.

   EAPI Eina_Bool eet_eina_stream_data_descriptor_class_set
       (Eet_Data_Descriptor_Class * eddc, 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
       stream. Parameters:
           eddc The Eet_Data_Descriptor_Class you want to set.
           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).

       Since:
           1.2.3

       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::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_free, and
       _Eet_Data_Descriptor_Class::version.

       Referenced by eet_eina_file_data_descriptor_class_set().

Author

       Generated automatically by Doxygen for Eet from the source code.