Home
News
About
Download
Main Page API Reference Globals Related Pages
Support
Contribute
Contact
Tracker

Eet.h File Reference

The file that provides the eet functions. More...


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_LAST   13
 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_LAST   105
 Last group type.
#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.

Functions

EAPI int eet_init (void)
 Initialize the EET library.
EAPI int eet_shutdown (void)
 Shut down the EET library.
EAPI void eet_clearcache (void)
 Clear eet cache.
EAPI Eet_File * eet_open (const char *file, Eet_File_Mode mode)
 Open an eet file on disk, and returns a handle to it.
EAPI Eet_File_Mode eet_mode_get (Eet_File *ef)
 Get the mode an Eet_File was opened with.
EAPI Eet_Error eet_close (Eet_File *ef)
 Close an eet file handle and flush and writes pending.
EAPI Eet_Dictionary * eet_dictionary_get (Eet_File *ef)
 Return a handle to the shared string dictionary of the Eet file.
EAPI int eet_dictionary_string_check (Eet_Dictionary *ed, const char *string)
 Check if a given string comes from a given dictionary.
EAPI void * eet_read (Eet_File *ef, const char *name, int *size_ret)
 Read a specified entry from an eet file and return data.
EAPI const void * eet_read_direct (Eet_File *ef, const char *name, int *size_ret)
 Read a specified entry from an eet file and return data.
EAPI int eet_write (Eet_File *ef, const char *name, const void *data, int size, int compress)
 Write a specified entry to an eet file handle.
EAPI int eet_delete (Eet_File *ef, const char *name)
 Delete a specified entry from an Eet file being written or re-written.
EAPI char ** eet_list (Eet_File *ef, const char *glob, int *count_ret)
 List all entries in eet file matching shell glob.
EAPI int eet_num_entries (Eet_File *ef)
 Return the number of entries in the specified eet file.
EAPI int eet_data_image_header_read (Eet_File *ef, const char *name, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy)
 Read just the header data for an image and dont decode the pixels.
EAPI void * eet_data_image_read (Eet_File *ef, const char *name, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy)
 Read image data from the named key in the eet file.
EAPI int eet_data_image_write (Eet_File *ef, const char *name, const void *data, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy)
 Write image data to the named key in an eet file.
EAPI int eet_data_image_header_decode (const void *data, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy)
 Decode Image data header only to get information.
EAPI void * eet_data_image_decode (const void *data, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy)
 Decode Image data into pixel data.
EAPI void * eet_data_image_encode (const void *data, int *size_ret, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy)
 Encode image data for storage or transmission.
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 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

The file that provides the eet functions.

This header provides the Eet management functions.

Define Documentation

#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, 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, 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, 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_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, 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

Function Documentation

EAPI void eet_clearcache ( void   ) 

Clear eet cache.

Eet didn't free items by default. If you are under memory presure, just call this function to recall all memory that are not yet referenced anymore. The cache take care of modification on disk.

Since:
1.0.0

EAPI Eet_Error eet_close ( Eet_File *  ef  ) 

Close an eet file handle and flush and writes pending.

Parameters:
ef A valid eet file handle.
This function will flush any pending writes to disk if the eet file was opened for write, and free all data associated with the file handle and file, and close the file.

If the eet file handle is not valid nothing will be done.

Since:
1.0.0

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.

Since:
1.0.0

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.

Since:
1.0.0

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

Since:
1.0.0

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

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.

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;
    Evas_List *blah3;
 }
 Blah;

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

    edd3 = eet_data_descriptor_new("blah3", sizeof(Blah3),
                                   evas_list_next,
                                   evas_list_append,
                                   evas_list_data,
                                   evas_list_free,
                                   evas_hash_foreach,
                                   evas_hash_add,
                                   evas_hash_free);
    EET_DATA_DESCRIPTOR_ADD_BASIC(edd3, Blah3, "string3", string, EET_T_STRING);

    edd2 = eet_data_descriptor_new("blah2", sizeof(Blah2),
                                   evas_list_next,
                                   evas_list_append,
                                   evas_list_data,
                                   evas_list_free,
                                   evas_hash_foreach,
                                   evas_hash_add,
                                   evas_hash_free);
    EET_DATA_DESCRIPTOR_ADD_BASIC(edd2, Blah2, "string2", string, EET_T_STRING);

    edd = eet_data_descriptor_new("blah", sizeof(Blah),
                                   evas_list_next,
                                   evas_list_append,
                                   evas_list_data,
                                   evas_list_free,
                                   evas_hash_foreach,
                                   evas_hash_add,
                                   evas_hash_free);
    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 = evas_list_append(NULL, &blah3);
    blah.blah3 = evas_list_append(blah.blah3, &blah3);
    blah.blah3 = evas_list_append(blah.blah3, &blah3);
    blah.blah3 = evas_list_append(blah.blah3, &blah3);
    blah.blah3 = evas_list_append(blah.blah3, &blah3);
    blah.blah3 = evas_list_append(blah.blah3, &blah3);
    blah.blah3 = evas_list_append(blah.blah3, &blah3);

    data = eet_data_descriptor_encode(edd, &blah, &size);
    printf("-----DECODING\n");
    blah_in = eet_data_descriptor_decode(edd, data, size);

    printf("-----DECODED!\n");
    printf("%c\n", blah_in->character);
    printf("%x\n", (int)blah_in->sixteen);
    printf("%x\n", blah_in->integer);
    printf("%lx\n", blah_in->lots);
    printf("%f\n", (double)blah_in->floating);
    printf("%f\n", (double)blah_in->floating_lots);
    printf("%s\n", blah_in->string);
    printf("%p\n", blah_in->blah2);
    printf("  %s\n", blah_in->blah2->string);
      {
         Evas_List *l;

         for (l = blah_in->blah3; l; l = l->next)
           {
              Blah3 *blah3_in;

              blah3_in = l->data;
              printf("%p\n", blah3_in);
              printf("  %s\n", blah3_in->string);
           }
      }
    eet_data_descriptor_free(edd);
    eet_data_descriptor_free(edd2);
    eet_data_descriptor_free(edd3);

   return 0;
 }

Since:
1.0.0

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.

Since:
1.0.0

EAPI void* eet_data_image_decode ( const void *  data,
int  size,
unsigned int *  w,
unsigned int *  h,
int *  alpha,
int *  compress,
int *  quality,
int *  lossy 
)

Decode Image data into pixel data.

Parameters:
data The encoded pixel data.
size The size, in bytes, of the encoded pixel data.
w A pointer to the unsigned int to hold the width in pixels.
h A pointer to the unsigned int to hold the height in pixels.
alpha A pointer to the int to hold the alpha flag.
compress A pointer to the int to hold the compression amount.
quality A pointer to the int to hold the quality amount.
lossy A pointer to the int to hold the lossiness flag.
Returns:
The image pixel data decoded
This function takes encoded pixel data and decodes it into raw RGBA pixels on success.

The other parameters of the image (width, height etc.) are placed into the values pointed to (they must be supplied). The pixel data is a linear array of pixels starting from the top-left of the image scanning row by row from left to right. Each pixel is a 32bit value, with the high byte being the alpha channel, the next being red, then green, and the low byte being blue. The width and height are measured in pixels and will be greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes that the alpha channel is not used. 1 denotes that it is significant. Compress is filled with the compression value/amount the image was stored with. The quality value is filled with the quality encoding of the image file (0 - 100). The lossy flags is either 0 or 1 as to if the image was encoded lossily or not.

On success the function returns a pointer to the image data decoded. The calling application is responsible for calling free() on the image data when it is done with it. On failure NULL is returned and the parameter values may not contain any sensible data.

Since:
1.0.0

EAPI void* eet_data_image_encode ( const void *  data,
int *  size_ret,
unsigned int  w,
unsigned int  h,
int  alpha,
int  compress,
int  quality,
int  lossy 
)

Encode image data for storage or transmission.

Parameters:
data A pointer to the image pixel data.
size_ret A pointer to an int to hold the size of the returned data.
w The width of the image in pixels.
h The height of the image in pixels.
alpha The alpha channel flag.
compress The compression amount.
quality The quality encoding amount.
lossy The lossiness flag.
Returns:
The encoded image data.
This function stakes image pixel data and encodes it with compression and possible loss of quality (as a trade off for size) for storage or transmission to another system.

The data expected is the same format as returned by eet_data_image_read. If this is not the case weird things may happen. Width and height must be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning the alpha values are not useful and 1 meaning they are). Compress can be from 0 to 9 (0 meaning no compression, 9 meaning full compression). This is only used if the image is not lossily encoded. Quality is used on lossy compression and should be a value from 0 to 100. The lossy flag can be 0 or 1. 0 means encode losslessly and 1 means to encode with image quality loss (but then have a much smaller encoding).

On success this function returns a pointer to the encoded data that you can free with free() when no longer needed.

Since:
1.0.0

EAPI int eet_data_image_header_decode ( const void *  data,
int  size,
unsigned int *  w,
unsigned int *  h,
int *  alpha,
int *  compress,
int *  quality,
int *  lossy 
)

Decode Image data header only to get information.

Parameters:
data The encoded pixel data.
size The size, in bytes, of the encoded pixel data.
w A pointer to the unsigned int to hold the width in pixels.
h A pointer to the unsigned int to hold the height in pixels.
alpha A pointer to the int to hold the alpha flag.
compress A pointer to the int to hold the compression amount.
quality A pointer to the int to hold the quality amount.
lossy A pointer to the int to hold the lossiness flag.
Returns:
1 on success, 0 on failure.
This function takes encoded pixel data and decodes it into raw RGBA pixels on success.

The other parameters of the image (width, height etc.) are placed into the values pointed to (they must be supplied). The pixel data is a linear array of pixels starting from the top-left of the image scanning row by row from left to right. Each pixel is a 32bit value, with the high byte being the alpha channel, the next being red, then green, and the low byte being blue. The width and height are measured in pixels and will be greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes that the alpha channel is not used. 1 denotes that it is significant. Compress is filled with the compression value/amount the image was stored with. The quality value is filled with the quality encoding of the image file (0 - 100). The lossy flags is either 0 or 1 as to if the image was encoded lossily or not.

On success the function returns 1 indicating the header was read and decoded properly, or 0 on failure.

Since:
1.0.0

EAPI int eet_data_image_header_read ( Eet_File *  ef,
const char *  name,
unsigned int *  w,
unsigned int *  h,
int *  alpha,
int *  compress,
int *  quality,
int *  lossy 
)

Read just the header data for an image and dont decode the pixels.

Parameters:
ef A valid eet file handle opened for reading.
name Name of the entry. eg: "/base/file_i_want".
w A pointer to the unsigned int to hold the width in pixels.
h A pointer to the unsigned int to hold the height in pixels.
alpha A pointer to the int to hold the alpha flag.
compress A pointer to the int to hold the compression amount.
quality A pointer to the int to hold the quality amount.
lossy A pointer to the int to hold the lossiness flag.
Returns:
1 on successfull decode, 0 otherwise
This function reads an image from an eet file stored under the named key in the eet file and return a pointer to the decompressed pixel data.

The other parameters of the image (width, height etc.) are placed into the values pointed to (they must be supplied). The pixel data is a linear array of pixels starting from the top-left of the image scanning row by row from left to right. Each pile is a 32bit value, with the high byte being the alpha channel, the next being red, then green, and the low byte being blue. The width and height are measured in pixels and will be greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes that the alpha channel is not used. 1 denotes that it is significant. Compress is filled with the compression value/amount the image was stored with. The quality value is filled with the quality encoding of the image file (0 - 100). The lossy flags is either 0 or 1 as to if the image was encoded lossily or not.

On success the function returns 1 indicating the header was read and decoded properly, or 0 on failure.

Since:
1.0.0

EAPI void* eet_data_image_read ( Eet_File *  ef,
const char *  name,
unsigned int *  w,
unsigned int *  h,
int *  alpha,
int *  compress,
int *  quality,
int *  lossy 
)

Read image data from the named key in the eet file.

Parameters:
ef A valid eet file handle opened for reading.
name Name of the entry. eg: "/base/file_i_want".
w A pointer to the unsigned int to hold the width in pixels.
h A pointer to the unsigned int to hold the height in pixels.
alpha A pointer to the int to hold the alpha flag.
compress A pointer to the int to hold the compression amount.
quality A pointer to the int to hold the quality amount.
lossy A pointer to the int to hold the lossiness flag.
Returns:
The image pixel data decoded
This function reads an image from an eet file stored under the named key in the eet file and return a pointer to the decompressed pixel data.

The other parameters of the image (width, height etc.) are placed into the values pointed to (they must be supplied). The pixel data is a linear array of pixels starting from the top-left of the image scanning row by row from left to right. Each pile is a 32bit value, with the high byte being the alpha channel, the next being red, then green, and the low byte being blue. The width and height are measured in pixels and will be greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes that the alpha channel is not used. 1 denotes that it is significant. Compress is filled with the compression value/amount the image was stored with. The quality value is filled with the quality encoding of the image file (0 - 100). The lossy flags is either 0 or 1 as to if the image was encoded lossily or not.

On success the function returns a pointer to the image data decoded. The calling application is responsible for calling free() on the image data when it is done with it. On failure NULL is returned and the parameter values may not contain any sensible data.

Since:
1.0.0

EAPI int eet_data_image_write ( Eet_File *  ef,
const char *  name,
const void *  data,
unsigned int  w,
unsigned int  h,
int  alpha,
int  compress,
int  quality,
int  lossy 
)

Write image data to the named key in an eet file.

Parameters:
ef A valid eet file handle opened for writing.
name Name of the entry. eg: "/base/file_i_want".
data A pointer to the image pixel data.
w The width of the image in pixels.
h The height of the image in pixels.
alpha The alpha channel flag.
compress The compression amount.
quality The quality encoding amount.
lossy The lossiness flag.
Returns:
Success if the data was encoded and written or not.
This function takes image pixel data and encodes it in an eet file stored under the supplied name key, and returns how many bytes were actually written to encode the image data.

The data expected is the same format as returned by eet_data_image_read. If this is not the case weird things may happen. Width and height must be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning the alpha values are not useful and 1 meaning they are). Compress can be from 0 to 9 (0 meaning no compression, 9 meaning full compression). This is only used if the image is not lossily encoded. Quality is used on lossy compression and should be a value from 0 to 100. The lossy flag can be 0 or 1. 0 means encode losslessly and 1 means to encode with image quality loss (but then have a much smaller encoding).

On success this function returns the number of bytes that were required to encode the image data, or on failure it returns 0.

Since:
1.0.0

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.

Since:
1.0.0

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);
 }

Since:
1.0.0

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.

Since:
1.0.0

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

Since:
1.0.0

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:
1 on successful write, 0 on failure.
This function is the reverse of eet_data_read(), saving a data structure to an eet file.

Since:
1.0.0

EAPI int eet_delete ( Eet_File *  ef,
const char *  name 
)

Delete a specified entry from an Eet file being written or re-written.

Parameters:
ef A valid eet file handle opened for writing.
name Name of the entry. eg: "/base/file_i_want".
Returns:
Success or failure of the delete.
This function will delete the specified chunk of data from the eet file and return greater than 0 on success. 0 will be returned on failure.

The eet file handle must be a valid file handle for an eet file opened for writing. If it is not, 0 will be returned and no action will be performed.

Name, must not be NULL, otherwise 0 will be returned.

Since:
1.0.0

EAPI Eet_Dictionary* eet_dictionary_get ( Eet_File *  ef  ) 

Return a handle to the shared string dictionary of the Eet file.

Parameters:
ef A valid eet file handle.
Returns:
A handle to the dictionary of the file
This function returns a handle to the dictionary of an Eet file whose handle is ef, if a dictionary exists. NULL is returned otherwise or if the file handle is known to be invalid.

Since:
1.0.0

EAPI int eet_dictionary_string_check ( Eet_Dictionary *  ed,
const char *  string 
)

Check if a given string comes from a given dictionary.

Parameters:
ed A valid dictionary handle
string A valid 0 byte terminated C string
Returns:
1 if it is in the dictionary, 0 otherwise
This checks the given dictionary to see if the given string is actually inside that dictionary (i.e. comes from it) and returns 1 if it does. If the dictionary handle is invlide, the string is NULL or the string is not in the dictionary, 0 is returned.

Since:
1.0.0

EAPI int eet_init ( void   ) 

Initialize the EET library.

Returns:
The new init count.
Since:
1.0.0

EAPI char** eet_list ( Eet_File *  ef,
const char *  glob,
int *  count_ret 
)

List all entries in eet file matching shell glob.

Parameters:
ef A valid eet file handle.
glob A shell glob to match against.
count_ret Number of entries found to match.
Returns:
Pointer to an array of strings.
This function will list all entries in the eet file matching the supplied shell glob and return an allocated list of their names, if there are any, and if no memory errors occur.

The eet file handle must be valid and glob must not be NULL, or NULL will be returned and count_ret will be filled with 0.

The calling program must call free() on the array returned, but NOT on the string pointers in the array. They are taken as read-only internals from the eet file handle. They are only valid as long as the file handle is not closed. When it is closed those pointers in the array are now not valid and should not be used.

On success the array returned will have a list of string pointers that are the names of the entries that matched, and count_ret will have the number of entries in this array placed in it.

Hint: an easy way to list all entries in an eet file is to use a glob value of "*".

Since:
1.0.0

EAPI Eet_File_Mode eet_mode_get ( Eet_File *  ef  ) 

Get the mode an Eet_File was opened with.

Parameters:
ef A valid eet file handle.
Returns:
The mode ef was opened with.
Since:
1.0.0

EAPI int eet_num_entries ( Eet_File *  ef  ) 

Return the number of entries in the specified eet file.

Parameters:
ef A valid eet file handle.
Returns:
Number of entries in ef or -1 if the number of entries cannot be read due to open mode restrictions.
Since:
1.0.0

EAPI Eet_File* eet_open ( const char *  file,
Eet_File_Mode  mode 
)

Open an eet file on disk, and returns a handle to it.

Parameters:
file The file path to the eet file. eg: "/tmp/file.eet".
mode The mode for opening. Either EET_FILE_MODE_READ, EET_FILE_MODE_WRITE or EET_FILE_MODE_READ_WRITE.
Returns:
An opened eet file handle.
This function will open an exiting eet file for reading, and build the directory table in memory and return a handle to the file, if it exists and can be read, and no memory errors occur on the way, otherwise NULL will be returned.

It will also open an eet file for writing. This will, if successful, delete the original file and replace it with a new empty file, till the eet file handle is closed or flushed. If it cannot be opened for writing or a memory error occurs, NULL is returned.

You can also open the file for read/write. If you then write a key that does not exist it will be created, if the key exists it will be replaced by the new data.

Example: 

 #include <Eet.h>
 #include <stdio.h>

 int
 main(int argc, char **argv)
 {
   Eet_File *ef;
   char buf[1024], *ret, **list;
   int size, num, i;

   strcpy(buf, "Here is a string of data to save!");

   ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE);
   if (!ef) return -1;
   if (!eet_write(ef, "/key/to_store/at", buf, 1024, 1))
     fprintf(stderr, "Error writing data!\n");
   eet_close(ef);

   ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_READ);
   if (!ef) return -1;
   list = eet_list(ef, "*", &num);
   if (list)
     {
       for (i = 0; i < num; i++)
         printf("Key stored: %s\n", list[i]);
       free(list);
     }
   ret = eet_read(ef, "/key/to_store/at", &size);
   if (ret)
     {
       printf("Data read (%i bytes):\n%s\n", size, ret);
       free(ret);
     }
   eet_close(ef);

   return 0;
 }

Since:
1.0.0

EAPI void* eet_read ( Eet_File *  ef,
const char *  name,
int *  size_ret 
)

Read a specified entry from an eet file and return data.

Parameters:
ef A valid eet file handle opened for reading.
name Name of the entry. eg: "/base/file_i_want".
size_ret Number of bytes read from entry and returned.
Returns:
The data stored in that entry in the eet file.
This function finds an entry in the eet file that is stored under the name specified, and returns that data, decompressed, if successful. NULL is returned if the lookup fails or if memory errors are encountered. It is the job of the calling program to call free() on the returned data. The number of bytes in the returned data chunk are placed in size_ret.

If the eet file handle is not valid NULL is returned and size_ret is filled with 0.

Since:
1.0.0

EAPI const void* eet_read_direct ( Eet_File *  ef,
const char *  name,
int *  size_ret 
)

Read a specified entry from an eet file and return data.

Parameters:
ef A valid eet file handle opened for reading.
name Name of the entry. eg: "/base/file_i_want".
size_ret Number of bytes read from entry and returned.
Returns:
The data stored in that entry in the eet file.
This function finds an entry in the eet file that is stored under the name specified, and returns that data if not compressed and successful. NULL is returned if the lookup fails or if memory errors are encountered or if the data is comrpessed. The calling program must never call free() on the returned data. The number of bytes in the returned data chunk are placed in size_ret.

If the eet file handle is not valid NULL is returned and size_ret is filled with 0.

Since:
1.0.0

EAPI int eet_shutdown ( void   ) 

Shut down the EET library.

Returns:
The new init count.
Since:
1.0.0

EAPI int eet_write ( Eet_File *  ef,
const char *  name,
const void *  data,
int  size,
int  compress 
)

Write a specified entry to an eet file handle.

Parameters:
ef A valid eet file handle opened for writing.
name Name of the entry. eg: "/base/file_i_want".
data Pointer to the data to be stored.
size Length in bytes in the data to be stored.
compress Compression flags (1 == compress, 0 = don't compress).
Returns:
Success or failure of the write.
This function will write the specified chunk of data to the eet file and return greater than 0 on success. 0 will be returned on failure.

The eet file handle must be a valid file handle for an eet file opened for writing. If it is not, 0 will be returned and no action will be performed.

Name, and data must not be NULL, and size must be > 0. If these conditions are not met, 0 will be returned.

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

Since:
1.0.0

Copyright © Enlightenment.org

Eet Documentation Generated: Sat May 17 13:39:50 2008