Eet File Main Functions
Eet

Functions to create, destroy and do basic manipulation of Eet_File handles. More...

## Topics

| Eet File Ciphered Main Functions
| Most of the Eet File Main Functions have alternative versions that accounts for ciphers to protect their content.

## Data Structures

struct | _Eet_Entry

## Macros

#define | EET_IMAGE_LOSSLESS EMILE_IMAGE_LOSSLESS
#define | EET_IMAGE_JPEG EMILE_IMAGE_JPEG
#define | EET_IMAGE_ETC1 EMILE_IMAGE_ETC1
#define | EET_IMAGE_ETC2_RGB EMILE_IMAGE_ETC2_RGB
#define | EET_IMAGE_ETC2_RGBA EMILE_IMAGE_ETC2_RGBA
#define | EET_IMAGE_ETC1_ALPHA EMILE_IMAGE_ETC1_ALPHA
#define | EET_COLORSPACE_ARGB8888 EMILE_COLORSPACE_ARGB8888
#define | EET_COLORSPACE_GRY8 EMILE_COLORSPACE_GRY8
#define | EET_COLORSPACE_AGRY88 EMILE_COLORSPACE_AGRY88
#define | EET_COLORSPACE_ETC1 EMILE_COLORSPACE_ETC1
#define | EET_COLORSPACE_RGB8_ETC2 EMILE_COLORSPACE_RGB8_ETC2
#define | EET_COLORSPACE_RGBA8_ETC2_EAC EMILE_COLORSPACE_RGBA8_ETC2_EAC
#define | EET_COLORSPACE_ETC1_ALPHA EMILE_COLORSPACE_ETC1_ALPHA

## Typedefs

typedef enum _Eet_File_Mode | Eet_File_Mode
| Modes that a file can be opened.
typedef Emile_Image_Encoding | Eet_Image_Encoding
| Specify lossy encoding for image.
typedef Emile_Colorspace | Eet_Colorspace
| Specify colorspace for image.
typedef struct _Eet_File | Eet_File
| Opaque handle that defines an Eet file (or memory).
typedef struct _Eet_Dictionary | Eet_Dictionary
| Opaque handle that defines a file-backed (mmaped) dictionary of strings.
typedef struct _Eet_Entry | Eet_Entry
| Eet files may contains multiple Entries per file, this handle describe them.

## Enumerations

enum | _Eet_File_Mode { EET_FILE_MODE_INVALID = -1 , EET_FILE_MODE_READ , EET_FILE_MODE_WRITE , EET_FILE_MODE_READ_WRITE }
| Modes that a file can be opened. More...

## Functions

EAPI Eet_File * | eet_open (const char *file, Eet_File_Mode mode)
| Opens an eet file on disk, and returns a handle to it.
EAPI Eet_File * | eet_mmap (const Eina_File *file)
| Opens an eet file on disk from an Eina_File handle, and returns a handle to it.
EAPI Eet_File * | eet_memopen_read (const void *data, size_t size)
| Opens an eet file directly from a memory location.
EAPI Eet_File_Mode | eet_mode_get (Eet_File *ef)
| Gets the mode an Eet_File was opened with.
EAPI Eet_Error | eet_close (Eet_File *ef)
| Closes an eet file handle and flush pending writes.
EAPI Eet_Error | eet_sync (Eet_File *ef)
| Syncs content of an eet file handle, flushing pending writes.
EAPI Eet_Error | eet_sync_sync (Eet_File *ef)
| does exactly what eet_xunc() does but also fsyncs file data
EAPI Eet_Dictionary * | eet_dictionary_get (Eet_File *ef)
| Returns a handle to the shared string dictionary of the Eet file.
EAPI int | eet_dictionary_string_check (Eet_Dictionary *ed, const char *string)
| Checks if a given string comes from a given dictionary.
EAPI int | eet_dictionary_count (const Eet_Dictionary *ed)
| Returns the number of strings inside a dictionary.
EAPI void * | eet_read (Eet_File *ef, const char *name, int *size_ret)
| Reads 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)
| Reads 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)
| Deletes a specified entry from an Eet file being written or re-written.
EAPI Eina_Bool | eet_alias (Eet_File *ef, const char *name, const char *destination, int compress)
| Alias a specific section to another one.
EAPI const char * | eet_file_get (Eet_File *ef)
| Retrieves the filename of an Eet_File.
EAPI const char * | eet_alias_get (Eet_File *ef, const char *name)
| Retrieves the destination name of an alias.
EAPI char ** | eet_list (Eet_File *ef, const char *glob, int *count_ret)
| Lists all entries in eet file matching shell glob.
EAPI Eina_Iterator * | eet_list_entries (Eet_File *ef)
| Returns an iterator that will describe each entry of an Eet_File.
EAPI int | eet_num_entries (Eet_File *ef)
| Returns the number of entries in the specified eet file.

## Detailed Description

Functions to create, destroy and do basic manipulation of Eet_File handles.

This section explains how to use the most basic Eet functions, which are used to work with eet files, read data from them, store it back in or take a look at what entries it contains, without making use of the serialization capabilities explained in Eet Data Serialization.

The following example will serve as an introduction to most, if not all, of these functions.

If you are only using Eet, this is the only header you need to include.

#include <Eet.h>
Eet.h
The file that provides the eet functions.

Now let's create ourselves an eet file to play with. The following function shows step by step how to open a file and write some data in it. First, we define our file handler and some other things we'll put in it.

Eet_File *ef;
char buf[1024], *ptr;
int size, len, i;
const char *some_strings[] = {
"And some more strings",
"spread across several",
"elements of an array!"
};
const char some_data[] =
"\x1e\xe7\x0f\x42\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x35"
"\x00\x00\x00\xa0\x00\x00\x00\xa0\x00\x00\x00\x24\x00\x00\x00\x11"
"\x00\x00\x00\x00\x2f\x6d\x69\x73\x74\x65\x72\x69\x6f\x75\x73\x2f"
"\x64\x61\x74\x61\x00\x41\x6e\x20\x45\x45\x54\x20\x69\x6e\x73\x69"
"\x64\x65\x20\x6f\x66\x20\x61\x6e\x20\x45\x45\x54\x21\x0a\x54\x68"
"\x69\x73\x20\x77\x61\x73\x6e\x27\x74\x20\x72\x65\x61\x6c\x6c\x79"
"\x20\x75\x73\x65\x66\x75\x6c\x20\x62\x75\x74\x20\x69\x74\x20\x68"
"\x65\x6c\x70\x65\x64\x20\x74\x6f\x20\x73\x68\x6f\x77\x20\x68\x6f"
"\x77\x0a\x74\x6f\x20\x75\x73\x65\x20\x65\x65\x74\x5f\x6d\x65\x6d"
"\x6f\x70\x65\x6e\x5f\x72\x65\x61\x64\x28\x29\x20\x74\x6f\x20\x6f"
"\x70\x65\x6e\x20\x61\x6e\x20\x65\x65\x74\x20\x66\x69\x6c\x65\x20"
"\x66\x72\x6f\x6d\x0a\x64\x61\x74\x61\x20\x61\x6c\x72\x65\x61\x64"
"\x79\x20\x6c\x6f\x61\x64\x65\x64\x20\x69\x6e\x20\x6d\x65\x6d\x6f"
"\x72\x79\x2e\x0a\x00";
Eet_File
struct _Eet_File Eet_File
Opaque handle that defines an Eet file (or memory).
Definition Eet.h:527

We open a new file in write mode, and if it fails, we just return, since there's not much more we can do about it..

ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE);
if (!ef) return 0;
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:1525
EET_FILE_MODE_WRITE
@ EET_FILE_MODE_WRITE
File is write-only.
Definition Eet.h:480

Now, we need to write some data in our file. For now, strings will suffice, so let's just dump a bunch of them in there.

strcpy(buf, "Here is a string of data to save!");
size = eet_write(ef, "/key/to_store/at", buf, sizeof(buf), 1);
if (!size)
{
fprintf(stderr, "Error writing data!\n");
eet_close(ef);
return 0;
}
eet_close
EAPI Eet_Error eet_close(Eet_File *ef)
Closes an eet file handle and flush pending writes.
Definition eet_lib.c:1934
eet_write
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.
Definition eet_lib.c:2527

As you can see, we copied a string into our static buffer, which is a bit bigger than the full length of the string, and then told Eet to write it into the file, compressed, returning the size of the data written into the file. This is all to show that Eet treats data as just data. It doesn't matter what that data represents (for now), it's all just bytes for it. As running the following code will show, we took a string of around 30 bytes and put it in a buffer of 1024 bytes, but the returned size won't be any of those.

len = strlen(buf);
printf("strlen() = %d, eet_write() = %d\n", len, size);

Next, we copy into our buffer our set of strings, including their null terminators and write them into the file. No error checking for the sake of brevity. And a call to eet_sync() to make sure all out data is properly written down to disk, even though we haven't yet closed the file.

ptr = buf;
for (i = 0; i < 3; i++)
{
len = strlen(some_strings[i]) + 1;
memcpy(ptr, some_strings[i], len);
ptr += len;
}
eet_write(ef, "/several/strings", buf, sizeof(buf), 1);
eet_sync(ef);
eet_sync
EAPI Eet_Error eet_sync(Eet_File *ef)
Syncs content of an eet file handle, flushing pending writes.
Definition eet_lib.c:654

One more write, this time our large array of binary data and... well, I couldn't come up with a valid use of the last set of strings we stored, so let's take it out from the file with eet_delete().

eet_write(ef, "/some/mysterious/data", some_data, sizeof(some_data) - 1, 1);
eet_delete(ef, "/several/strings");
eet_delete
EAPI int eet_delete(Eet_File *ef, const char *name)
Deletes a specified entry from an Eet file being written or re-written.
Definition eet_lib.c:2537

Finally, we close the file, saving any changes back to disk and return. Notice how, if there's any error closing the file or saving its contents, the return value from the function will be a false one, which later on will make the program exit with an error code.

return eet_close(ef) == EET_ERROR_NONE;
EET_ERROR_NONE
@ EET_ERROR_NONE
No error, it's all fine!
Definition Eet.h:202

Moving onto our main function, we will open the same file and read it back. Trivial, but it'll show how we can do so in more than one way. We'll skip the variable declarations, as they aren't very different from what we've seen already.

We start from the beginning by initializing Eet so things in general work. Forgetting to do so will result in weird results or crashes when calling any eet function, so if you experience something like that, the first thing to look at is whether eet_init() is missing. Then we call our `create_eet_file` function, described above, to make sure we have something to work with. If the function fails it will return 0 and we just exit, since nothing from here onwards will work anyway.

eet_init();
if (!create_eet_file())
return -1;
eet_init
EAPI int eet_init(void)
Initializes the EET library.
Definition eet_lib.c:543

Let's take a look now at what entries our file has. For this, we use eet_list(), which will return a list of strings, each being the name of one entry. Since we skipped before, it may be worth noting that `list` is declared as a `char` **. The `num` parameter will, of course, have the number of entries contained in our file. If everything's fine, we'll get our list and print it to the screen, and once done with it, we free the list. That's just the list, not its contents, as they are internal strings used by Eet and trying to free them will surely break things.

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);
}
eet_list
EAPI char ** eet_list(Eet_File *ef, const char *glob, int *count_ret)
Lists all entries in eet file matching shell glob.
Definition eet_lib.c:2608
EET_FILE_MODE_READ
@ EET_FILE_MODE_READ
File is read-only.
Definition Eet.h:479

Reading back plain data is simple. Just a call to eet_read() with the file to read from, and the name of the entry we are interested in. We get back our data and the passed `size` parameter will contain the size of it. If the data was stored compressed, it will decompressed first.

ret = eet_read(ef, "/key/to_store/at", &size);
if (ret)
{
printf("Data read (%i bytes):\n%s\n", size, ret);
free(ret);
}
eet_read
EAPI void * eet_read(Eet_File *ef, const char *name, int *size_ret)
Reads a specified entry from an eet file and return data.
Definition eet_lib.c:2041

Another simple read for the set of strings from before, except those were deleted, so we should get a NULL return and continue normally.

ret = eet_read(ef, "/several/strings", &size);
if (ret)
{
printf("More data read (%i bytes):\n%s\n", size, ret);
free(ret);
}

Finally, we'll get our binary data in the same way we got the strings. Once again, it makes no difference for Eet what the data is, it's up to us to know how to handle it.

ret = eet_read(ef, "/some/mysterious/data", &size);
if (ret)
{

Now some cheating, we know that this data is an Eet file because, well... we just know it. So we are going to open it and take a look at its insides. For this, eet_open() won't work, as it needs to have a file on disk to read from and all we have is some data in RAM.

So how do we do? One way would be to create a normal file and write down our data, then open it with eet_open(). Another, faster and more efficient if all we want to do is read the file, is to use eet_memopen_read().

Eet_File *ef2;
ef2 = eet_memopen_read(ret, size);
eet_memopen_read
EAPI Eet_File * eet_memopen_read(const void *data, size_t size)
Opens an eet file directly from a memory location.
Definition eet_lib.c:1413

As you can see, the size we got from our previous read was put to good use this time. Unlike the first one where all we had were strings, the size of the data read only serves to demonstrate that we are reading back the entire size of our original `buf` variable.

A little peeking to see how many entries the file has and to make an example of eet_num_entries() to get that number when we don't care about their names.

num = eet_num_entries(ef2);
printf("Mysterious data has %d entries\n", num);
eet_num_entries
EAPI int eet_num_entries(Eet_File *ef)
Returns the number of entries in the specified eet file.
Definition eet_lib.c:2692

More cheating follows. Just like we knew this was an Eet file, we also know what key to read from, and on top of that we know that the data in it is not compressed. Knowing all this allows us to take some shortcuts.

printf("Mysterious data:\n%s\n",
(char *)eet_read_direct(ef2, "/mysterious/data", NULL));
eet_read_direct
EAPI const void * eet_read_direct(Eet_File *ef, const char *name, int *size_ret)
Reads a specified entry from an eet file and return data.
Definition eet_lib.c:2049

That's a direct print of our data, whatever that data is. We don't want to worry about having to free it later, so we just used eet_direct_read() to tell Eet to gives a pointer to the internal data in the file, without duplicating it. Since we said that data was not compressed, we shouldn't worry about printing garbage to the screen (and yes, we also know the data is yet another string). We also don't care about the size of the data as it was stored in the file, so we passed NULL as the size parameter. One very important note about this, however, is that we don't care about the size parameter because the data in the file contains the null terminator for the string. So when using Eet to store strings this way, it's very important to consider whether you will keep that final null byte, or to always get the size read and do the necessary checks and copies. It's up to the user and the particular use cases to decide how this will be done.

With everything done, close this second file and free the data used to open it. And this is important, we can't free that data until we are done with the file, as Eet is using it. When opening with eet_memopen_read(), the data passed to it must be available for as long as the the file is open.

eet_close(ef2);
free(ret);
}

Finally, we close the first file, shutdown all internal resources used by Eet and leave our main function, thus terminating our program.

eet_close(ef);
eet_shutdown();
return 0;
eet_shutdown
EAPI int eet_shutdown(void)
Shuts down the EET library.
Definition eet_lib.c:597

You can look at the full code of the example here.

## Typedef Documentation

## Eet_Image_Encoding

typedef Emile_Image_Encoding Eet_Image_Encoding

Specify lossy encoding for image.

Since
  1.10

## Eet_Colorspace

typedef Emile_Colorspace Eet_Colorspace

Specify colorspace for image.

Since
  1.10

## Eet_File

typedef struct _Eet_File Eet_File

Opaque handle that defines an Eet file (or memory).

This handle will be returned by the functions eet_open() and eet_memopen_read() and is used by every other function that affects the file in any way. When you are done with it, call eet_close() to close it and, if the file was open for writing, write down to disk any changes made to it.

See also
  eet_open()
  eet_memopen_read()
  eet_close()

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

## Eet_Entry

typedef struct _Eet_Entry Eet_Entry

Eet files may contains multiple Entries per file, this handle describe them.

You can get that handle from an iterator given by eet_list_entries().

See also
  eet_list_entries()

Since
  1.8.0

## Enumeration Type Documentation

## _Eet_File_Mode

enum _Eet_File_Mode

Modes that a file can be opened.

Enumerator
EET_FILE_MODE_READ | File is read-only.
EET_FILE_MODE_WRITE | File is write-only.
EET_FILE_MODE_READ_WRITE | File is for both read and write.

## Function Documentation

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

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.

If the same file is opened multiple times, then the same file handle will be returned as eet maintains an internal list of all currently open files. Note that it considers files opened for read only and those opened for read/write and write only as 2 separate sets. Those that do not write to the file and those that do. Eet will allow 2 handles to the same file if they are in the 2 separate lists/groups. That means opening a file for read only looks in the read only set, and returns a handle to that file handle and increments its reference count. If you open a file for read/write or write only it looks in the write set and returns a handle after incrementing the reference count. You need to close an eet file handle as many times as it has been opened to maintain correct reference counts. Files whose modified timestamp or size do not match those of the existing referenced file handles will not be returned and a new handle will be returned instead.

Since
  1.0.0

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

References EET_FILE_MODE_READ, EET_FILE_MODE_READ_WRITE, EET_FILE_MODE_WRITE, eet_sync(), EINA_FALSE, eina_file_close(), eina_file_map_all(), eina_file_open(), EINA_FILE_SEQUENTIAL, eina_file_size_get(), eina_stringshare_add_length(), and EINA_TRUE.

Referenced by edje_edit_clean_save_as(), elm_prefs_data_new(), and emotion_init().

## eet_mmap()

EAPI Eet_File * eet_mmap | ( | const Eina_File * | file | ) |

Opens an eet file on disk from an Eina_File handle, and returns a handle to it.

Parameters

  file | The Eina_File handle to map to an eet file.

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.

This function can't open file for writing only read only mode is supported for now.

If the same file is opened multiple times, then the same file handle will be returned as eet maintains an internal list of all currently open files. That means opening a file for read only looks in the read only set, and returns a handle to that file handle and increments its reference count. You need to close an eet file handle as many times as it has been opened to maintain correct reference counts.

Since
  1.8.0

References EET_FILE_MODE_READ, eet_sync(), EINA_FALSE, eina_file_dup(), eina_file_filename_get(), eina_file_map_all(), EINA_FILE_SEQUENTIAL, eina_file_size_get(), eina_stringshare_add(), and EINA_TRUE.

## eet_memopen_read()

EAPI Eet_File * eet_memopen_read | ( | const void * | data,
|  | size_t | size )

Opens an eet file directly from a memory location.

The data is not copied, so you must keep it around as long as the eet file is open. There is currently no cache for this kind of Eet_File, so it's reopened every time you use eet_memopen_read.

Parameters

  data | Address of file in memory.
  size | Size of memory to be read.

Returns
  A handle to the file.

Files opened this way will always be in read-only mode.

Since
  1.1.0

Examples
  eet-file.c.

References EET_FILE_MODE_READ, and EINA_FALSE.

## eet_mode_get()

EAPI Eet_File_Mode eet_mode_get | ( | Eet_File * | ef | ) |

Gets 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

## eet_close()

EAPI Eet_Error eet_close | ( | Eet_File * | ef | ) |

Closes an eet file handle and flush pending writes.

Parameters

  ef | A valid eet file handle.

Returns
  An eet error identifier.

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 it was opened for read (or read/write), the file handle may still be held open internally for caching purposes. To flush speculatively held eet file handles use eet_clearcache().

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

Since
  1.0.0

See also
  eet_clearcache()

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

References EINA_FALSE.

Referenced by edje_edit_clean_save_as(), elm_prefs_data_new(), and emotion_shutdown().

## eet_sync()

EAPI Eet_Error eet_sync | ( | Eet_File * | ef | ) |

Syncs content of an eet file handle, flushing pending writes.

Parameters

  ef | A valid eet file handle.

Returns
  An eet error identifier.

This function will flush any pending writes to disk. The eet file must be opened for write.

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

Since
  1.2.4

Examples
  eet-file.c.

References EET_ERROR_BAD_OBJECT, EET_ERROR_NONE, EET_ERROR_NOT_WRITABLE, EET_FILE_MODE_READ_WRITE, EET_FILE_MODE_WRITE, and EINA_FALSE.

Referenced by eet_mmap(), and eet_open().

## eet_sync_sync()

EAPI Eet_Error eet_sync_sync | ( | Eet_File * | ef | ) |

does exactly what eet_xunc() does but also fsyncs file data

Parameters

  ef | A valid eet file handle.

Returns
  An eet error identifier.

This function does everything eet_xunc() does with one addition - it ensures data is written to/synced to disk (as best is possible) by calling fdatasync() on the file before writes are all queued/done.

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

Since
  1.27

References EET_ERROR_BAD_OBJECT, EET_ERROR_NONE, EET_ERROR_NOT_WRITABLE, EET_FILE_MODE_READ_WRITE, EET_FILE_MODE_WRITE, and EINA_TRUE.

## eet_dictionary_get()

EAPI Eet_Dictionary * eet_dictionary_get | ( | Eet_File * | ef | ) |

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

See also
  eet_dictionary_string_check() to know if given string came from the dictionary or it was dynamically allocated using the Eet_Data_Descriptor_Class instructions.

Since
  1.0.0

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

Referenced by eet_data_dump_cipher(), eet_data_node_read_cipher(), eet_data_node_write_cipher(), eet_data_read_cipher(), eet_data_read_cipher_buffer(), eet_data_undump_cipher(), and eet_data_write_cipher().

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

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 invalid, the string is NULL or the string is not in the dictionary, `0` is returned.

Since
  1.0.0

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

## eet_dictionary_count()

EAPI int eet_dictionary_count | ( | const Eet_Dictionary * | ed | ) |

Returns the number of strings inside a dictionary.

Parameters

  ed | A valid dictionary handle

Returns
  the number of strings inside a dictionary

Since
  1.6.0

## eet_read()

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

Reads 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`.

See also
  eet_read_cipher()

Since
  1.0.0

Examples
  eet-basic.c, and eet-file.c.

References eet_read_cipher().

Referenced by edje_edit_clean_save_as(), edje_edit_group_copy(), edje_edit_image_del(), edje_edit_sound_samplebuffer_get(), and edje_edit_vector_del().

## eet_read_direct()

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

Reads 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 compressed. 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

Examples
  eet-file.c.

References EET_FILE_MODE_READ, EET_FILE_MODE_READ_WRITE, eet_read_direct(), eina_binbuf_free(), eina_binbuf_length_get(), eina_binbuf_string_get(), and emile_decompress().

Referenced by edje_edit_clean_save_as(), eet_data_dump_cipher(), eet_data_image_colorspace_get(), eet_data_image_header_read_cipher(), eet_data_image_read_cipher(), eet_data_image_read_to_cspace_surface_cipher(), eet_data_node_read_cipher(), eet_data_read_cipher(), eet_data_read_cipher_buffer(), and eet_read_direct().

## eet_write()

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
  bytes written on successful write, 0 on failure.

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

See also
  eet_write_cipher()

Since
  1.0.0

Examples
  eet-basic.c, and eet-file.c.

References eet_write_cipher().

Referenced by edje_edit_clean_save_as(), edje_edit_group_copy(), edje_edit_image_del(), and edje_edit_vector_del().

## eet_delete()

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

Deletes 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

Examples
  eet-file.c.

References EET_FILE_MODE_READ.

Referenced by edje_edit_font_del(), edje_edit_group_del(), edje_edit_image_del(), edje_edit_sound_sample_del(), and edje_edit_vector_del().

## eet_alias()

EAPI Eina_Bool eet_alias | ( | Eet_File * | ef,
|  | const char * | name,
|  | const char * | destination,
|  | int | compress )

Alias a specific section to another one.

Destination may exist or not, no checks are done.

Parameters

  ef | A valid eet file handle opened for writing.
  name | Name of the new entry. eg: "/base/file_i_want".
  destination | Actual source of the aliased entry eg: "/base/the_real_stuff_i_want".
  compress | Compression flags (1 == compress, 0 = don't compress).

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

Name and Destination must not be NULL, otherwise EINA_FALSE will be returned. The equivalent of this would be calling 'ln -s destination name'

Since
  1.3.3

References EET_FILE_MODE_READ_WRITE, EET_FILE_MODE_WRITE, eina_binbuf_free(), eina_binbuf_manage_new(), EINA_FALSE, EINA_TRUE, and emile_compress().

## eet_file_get()

EAPI const char * eet_file_get | ( | Eet_File * | ef | ) |

Retrieves the filename of an Eet_File.

Parameters

  ef | A valid eet file handle opened for writing.

Returns
  The stringshared file string opened with eet_open(), or NULL on error

Note
  This function will return NULL for files opened with eet_memopen_read()

Since
  1.6

## eet_alias_get()

EAPI const char * eet_alias_get | ( | Eet_File * | ef,
|  | const char * | name )

Retrieves the destination name of an alias.

Parameters

  ef | A valid eet file handle opened for writing
  name | Name of the entry. eg: "/base/file_i_want"

Returns
  Destination of the alias. eg: "/base/the_real_stuff_i_want", NULL on failure

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

Since
  1.5

References EET_FILE_MODE_READ, EET_FILE_MODE_READ_WRITE, eina_binbuf_free(), eina_binbuf_length_get(), eina_binbuf_string_get(), eina_stringshare_add(), and emile_decompress().

## eet_list()

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

Lists 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

Examples
  eet-file.c.

References EET_FILE_MODE_READ, and EET_FILE_MODE_READ_WRITE.

Referenced by edje_edit_clean_save_as(), edje_edit_group_copy(), and edje_edit_group_del().

## eet_list_entries()

EAPI Eina_Iterator * eet_list_entries | ( | Eet_File * | ef | ) |

Returns an iterator that will describe each entry of an Eet_File.

Parameters

  ef | A valid eet file handle.

Returns
  An iterator of Eet_Entry.

Since
  1.8.0

References EINA_FALSE, EINA_MAGIC_SET, _Eina_Iterator::free, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, FUNC_ITERATOR_LOCK, FUNC_ITERATOR_NEXT, _Eina_Iterator::get_container, _Eina_Iterator::lock, _Eina_Iterator::next, _Eina_Iterator::unlock, and _Eina_Iterator::version.

## eet_num_entries()

EAPI int eet_num_entries | ( | Eet_File * | ef | ) |

Returns 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

Examples
  eet-file.c.

References EET_FILE_MODE_READ, and EET_FILE_MODE_READ_WRITE.