Eet File Main Functions

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

Modules
	Eet File Ciphered Main Functions
	Most of the Eet File Main Functions have alternative versions that accounts for ciphers to protect their content.
Typedefs
typedef enum _Eet_File_Mode	Eet_File_Mode
	Modes that a file can be opened.
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.
Enumerations
enum	_Eet_File_Mode { , 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)
	Open an eet file on disk, and returns a handle to it.
EAPI Eet_File *	eet_memopen_read (const void *data, size_t size)
	Open an eet file directly from a memory location.
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_Error	eet_sync (Eet_File *ef)
	Sync content of an eet file handle, flushing pending writes.
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 Eina_Bool	eet_alias (Eet_File ef, const char name, const char *destination, int compress)
	Alias a specific section to another one.
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.

Detailed Description

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

Typedef Documentation

Eet_File

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

See also:: eet_open(); eet_memopen_read(); eet_close()

typedef enum _Eet_File_Mode Eet_File_Mode

Modes that a file can be opened.

Enumeration Type Documentation

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

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 check are done.

Parameters:

	ef	A valid eet file handle opened for writing.
	name	Name of the entry. eg: "/base/file_i_want".
	destination	Destionation of the alias. 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, otherwhise EINA_FALSE will be returned.

Since:: 1.3.3

References EET_FILE_MODE_READ_WRITE, and EET_FILE_MODE_WRITE.

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

References EET_FILE_MODE_READ.

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.

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

Since:: 1.0.0

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

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

References EET_FILE_MODE_READ, and EET_FILE_MODE_READ_WRITE.

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

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

Since:: 1.1.0

References EET_FILE_MODE_READ.

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

References EET_FILE_MODE_READ, and EET_FILE_MODE_READ_WRITE.

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>
 #include <string.h>

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

   eet_init();

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

   eet_shutdown();

   return 0;
 }

Since:: 1.0.0

References EET_FILE_MODE_READ, EET_FILE_MODE_READ_WRITE, EET_FILE_MODE_WRITE, and eet_sync().

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.

See also:: eet_read_cipher()

Since:: 1.0.0

References eet_read_cipher().

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

References EET_FILE_MODE_READ, EET_FILE_MODE_READ_WRITE, and eet_read_direct().

Referenced by eet_data_dump_cipher(), eet_data_image_header_read_cipher(), eet_data_image_read_cipher(), eet_data_image_read_to_surface_cipher(), eet_data_node_read_cipher(), eet_data_read_cipher(), and eet_read_direct().

EAPI Eet_Error eet_sync ( Eet_File * ef )

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

Parameters:

ef

A valid eet file handle.

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

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

Referenced by eet_open().

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

References eet_write_cipher().

Enlightenment

Beauty at your fingertips

Eet File Main Functions

Modules

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation