efl/src/lib/eet/Eet.h

/**
   @brief Eet Data Handling Library Public API Calls

   These routines are used for Eet Library interaction

   @page eet_main Eet

   @date 2000 (created)

   @section toc Table of Contents

   @li @ref eet_main_intro
   @li @ref eet_main_compiling
   @li @ref eet_main_next_steps
   @li @ref eet_main_intro_example

   @section eet_main_intro Introduction

   It is a tiny library designed to write an arbitrary set of chunks of data
   to a file and optionally compress each chunk (very much like a zip file)
   and allow fast random-access reading of the file later on. It does not
   do zip as a zip itself has more complexity than is needed, and it was much
   simpler to implement this once here.

   Eet is extremely fast, small and simple. Eet files can be very small and
   highly compressed, making them very optimal for just sending across the
   internet without having to archive, compress or decompress and install them.
   They allow for lightning-fast random-access reads once created, making them
   perfect for storing data that is written once (or rarely) and read many
   times, but the program does not want to have to read it all in at once.

   It also can encode and decode data structures in memory, as well as image
   data for saving to Eet files or sending across the network to other
   machines, or just writing to arbitrary files on the system. All data is
   encoded in a platform independent way and can be written and read by any
   architecture.

   @section eet_main_compiling How to compile

   Eet is a library your application links to. The procedure for this is very
   simple. You simply have to compile your application with the appropriate
   compiler flags that the @p pkg-config script outputs. For example:

   Compiling C or C++ files into object files:

   @verbatim
   gcc -c -o main.o main.c `pkg-config --cflags eet`
   @endverbatim

   Linking object files into a binary executable:

   @verbatim
   gcc -o my_application main.o `pkg-config --libs eet`
   @endverbatim

   See @ref pkgconfig

   @section eet_main_next_steps Next Steps

   After you understood what Eet is and installed it in your system
   you should proceed understanding the programming interface. We'd
   recommend you to take a while to learn @ref Eina as it is very
   convenient and optimized, and Eet provides integration with it.

   Recommended reading:

   @li @ref Eet_File_Group to know the basics to open and save files.
   @li @ref Eet_Data_Group to know the convenient way to serialize and
    parse your data structures automatically. Just create your
    descriptors and let Eet do the work for you.

   @section eet_main_intro_example Introductory Examples

   Here is a simple example on how to use Eet to save a series of strings to a
   file and load them again. The advantage of using Eet over just
   fprintf() and
   fscanf() is that not only can these entries be strings, they need no special
   parsing to handle delimiter characters or escaping, they can be binary data,
   image data, data structures containing integers, strings, other data
   structures, linked lists and much more, without the programmer having to
   worry about parsing, and best of all, Eet is very fast.

   This is just a very simple example that doesn't show all of the capabilities
   of Eet, but it serves to illustrate its simplicity.

   @include eet-basic.c

   More examples can be found at @ref eet_examples.

   @todo Document data format for images and data structures.

 */

#ifndef _EET_H
#define _EET_H

#include <stdlib.h>
#include <stdio.h>
#include <Eina.h>

#ifdef EAPI
# undef EAPI
#endif /* ifdef EAPI */

#ifdef _WIN32
# ifdef EFL_EET_BUILD
#  ifdef DLL_EXPORT
#   define EAPI __declspec(dllexport)
#  else /* ifdef DLL_EXPORT */
#   define EAPI
#  endif /* ! DLL_EXPORT */
# else /* ifdef EFL_EET_BUILD */
#  define EAPI __declspec(dllimport)
# endif /* ! EFL_EET_BUILD */
#else /* ifdef _WIN32 */
# ifdef __GNUC__
#  if __GNUC__ >= 4
#   define EAPI __attribute__ ((visibility("default")))
#  else /* if __GNUC__ >= 4 */
#   define EAPI
#  endif /* if __GNUC__ >= 4 */
# else /* ifdef __GNUC__ */
#  define EAPI
# endif /* ifdef __GNUC__ */
#endif /* ! _WIN32 */

#ifdef __cplusplus
extern "C" {
#endif /* ifdef __cplusplus */

/**
 * @file Eet.h
 * @brief The file that provides the eet functions.
 *
 * This header provides the Eet management functions.
 *
 */

#define EET_VERSION_MAJOR 1
#define EET_VERSION_MINOR 8
/**
 * @typedef Eet_Version
 *
 * This is the Eet version information structure that can be used at
 * runtime to detect which version of eet is being used and adapt
 * appropriately as follows for example:
 *
 * @code
 * #if defined(EET_VERSION_MAJOR) && (EET_VERSION_MAJOR >= 1) && defined(EET_VERSION_MINOR) && (EET_VERSION_MINOR > 2)
 * printf("Eet version: %i.%i.%i\n",
 *        eet_version->major,
 *        eet_version->minor,
 *        eet_version->micro);
 * if (eet_version->revision > 0)
 *   {
 *     printf("  Built from SVN revision # %i\n", eet_version->revision);
 *   }
 * #endif
 * @endcode
 *
 * Note the \#if check can be dropped if your program refuses to compile or
 * work with an Eet version less than 1.3.0.
 */
typedef struct _Eet_Version
{
   int major; /** < major (binary or source incompatible changes) */
   int minor; /** < minor (new features, bugfixes, major improvements version) */
   int micro; /** < micro (bugfix, internal improvements, no new features version) */
   int revision; /** < svn revision (0 if a proper release or the svn revision number Eet is built from) */
} Eet_Version;

EAPI extern Eet_Version *eet_version;

/**
 * @defgroup Eet_Group Top level functions
 * @ingroup Eet
 * Functions that affect Eet as a whole.
 *
 * @{
 */

/**
 * @enum _Eet_Error
 * All the error identifiers known by Eet.
 */
typedef enum _Eet_Error
{
   EET_ERROR_NONE, /**< No error, it's all fine! */
   EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */
   EET_ERROR_EMPTY, /**< There was nothing to do */
   EET_ERROR_NOT_WRITABLE, /**< Could not write to file or file is #EET_FILE_MODE_READ */
   EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */
   EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */
   EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it is too big */
   EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write due a generic Input/Output error */
   EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of space */
   EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */
   EET_ERROR_MMAP_FAILED, /**< Could not mmap file */
   EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */
   EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */
   EET_ERROR_INVALID_SIGNATURE, /**< Signature is invalid */
   EET_ERROR_NOT_SIGNED, /**< File or contents are not signed */
   EET_ERROR_NOT_IMPLEMENTED, /**< Function is not implemented */
   EET_ERROR_PRNG_NOT_SEEDED, /**< Could not introduce random seed */
   EET_ERROR_ENCRYPT_FAILED, /**< Could not encrypt contents */
   EET_ERROR_DECRYPT_FAILED /**< Could not decrypt contents */
} Eet_Error; /**< Eet error identifiers */

/**
 * @}
 */
   
/**
 * @defgroup Eet_Compression Eet Compression Levels
 * @ingroup Eet
 * Compression modes/levels supported by Eet.
 *
 * @{
 */

/**
 * @enum _Eet_Compression
 * All the compression modes known by Eet.
 */

typedef enum _Eet_Compression
{
   EET_COMPRESSION_NONE      = 0,  /**< No compression at all @since 1.7 */
   EET_COMPRESSION_DEFAULT   = 1,  /**< Default compression (Zlib) @since 1.7 */
   EET_COMPRESSION_LOW       = 2,  /**< Fast but minimal compression (Zlib) @since 1.7 */
   EET_COMPRESSION_MED       = 6,  /**< Medium compression level (Zlib) @since 1.7 */
   EET_COMPRESSION_HI        = 9,  /**< Slow but high compression level (Zlib) @since 1.7 */
   EET_COMPRESSION_VERYFAST  = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */
   EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST)  (LZ4) @since 1.7 */
     
   EET_COMPRESSION_LOW2      = 3,  /**< Space filler for compatibility. Don't use it @since 1.7 */
   EET_COMPRESSION_MED1      = 4,  /**< Space filler for compatibility. Don't use it @since 1.7 */
   EET_COMPRESSION_MED2      = 5,  /**< Space filler for compatibility. Don't use it @since 1.7 */
   EET_COMPRESSION_HI1       = 7,  /**< Space filler for compatibility. Don't use it @since 1.7 */
   EET_COMPRESSION_HI2       = 8   /**< Space filler for compatibility. Don't use it @since 1.7 */
} Eet_Compression; /**< Eet compression modes @since 1.7 */
   
/**
 * @}
 */

/**
 * Initialize the EET library.
 *
 * The first time this function is called, it will perform all the internal
 * initialization required for the library to function properly and increment
 * the initialization counter. Any subsequent call only increment this counter
 * and return its new value, so it's safe to call this function more than once.
 *
 * @return The new init count. Will be 0 if initialization failed.
 *
 * @since 1.0.0
 * @ingroup Eet_Group
 */
EAPI int
eet_init(void);

/**
 * Shut down the EET library.
 *
 * If eet_init() was called more than once for the running application,
 * eet_shutdown() will decrement the initialization counter and return its
 * new value, without doing anything else. When the counter reaches 0, all
 * of the internal elements will be shutdown and any memory used freed.
 *
 * @return The new init count.
 *
 * @since 1.0.0
 * @ingroup Eet_Group
 */
EAPI int
eet_shutdown(void);

/**
 * Clear eet cache
 *
 * For a faster access to previously accessed data, Eet keeps an internal
 * cache of files. These files will be freed automatically only when
 * they are unused and the cache gets full, in order based on the last time
 * they were used.
 * On systems with little memory this may present an unnecessary constraint,
 * so eet_clearcache() is available for users to reclaim the memory used by
 * files that are no longer needed. Those that were open using
 * ::EET_FILE_MODE_WRITE or ::EET_FILE_MODE_READ_WRITE and have modifications,
 * will be written down to disk before flushing them from memory.
 *
 * @since 1.0.0
 * @ingroup Eet_Group
 */
EAPI void
eet_clearcache(void);

/**
 * @defgroup Eet_File_Group Eet File Main Functions
 * @ingroup Eet
 *
 * Functions to create, destroy and do basic manipulation of
 * #Eet_File handles.
 *
 * This sections 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 @ref Eet_Data_Group.
 *
 * 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.
 * @dontinclude eet-file.c
 * @skipline Eet.h
 *
 * 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.
 * @line static int
 * @skip Eet_File
 * @until ";
 * @skip eet_open
 *
 * 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..
 * @until return
 *
 * 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.
 * @until }
 *
 * 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.
 * @until printf
 *
 * 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.
 * @until eet_sync
 *
 * 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().
 * @until eet_delete
 *
 * 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.
 * @until return
 *
 * 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 @p 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.
 * @skip eet_init
 * @until return
 *
 * 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 @p list
 * is declared as a @p char **.
 * The @p 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.
 * @until }
 *
 * 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 @p size parameter will contain the size of it. If
 * the data was stored compressed, it will decompressed first.
 * @until }
 *
 * Another simple read for the set of strings from before, except those were
 * deleted, so we should get a NULL return and continue normally.
 * @until }
 *
 * 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.
 * @until {
 *
 * 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().
 * @until memopen
 *
 * 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 @p 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.
 * @until printf
 *
 * More cheating follows. Just like we knew this was an Eet file, we also know
 * what key to read from, and ontop of that we know that the data in it is not
 * compressed.
 * Knowing all this allows us to take some shortcuts.
 * @until read_direct
 *
 * 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.
 * @until }
 *
 * Finally, we close the first file, shutdown all internal resources used by
 * Eet and leave our main function, thus terminating our program.
 * @until return
 *
 * You can look at the full code of the example @ref eet-file.c "here".
 * @{
 */

/**
 * @enum _Eet_File_Mode
 * Modes that a file can be opened.
 */
typedef enum _Eet_File_Mode
{
   EET_FILE_MODE_INVALID = -1,
   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 */
} Eet_File_Mode; /**< Modes that a file can be opened. */

/**
 * @typedef 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 eet_open()
 * @see eet_memopen_read()
 * @see eet_close()
 */
typedef struct _Eet_File Eet_File;

/**
 * @typedef Eet_Dictionary
 * Opaque handle that defines a file-backed (mmaped) dictionary of strings.
 */
typedef struct _Eet_Dictionary Eet_Dictionary;

/**
 * @typedef Eet_Entries
 * 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 eet_list_entries()
 * @since 1.8.0
 */
typedef struct _Eet_Entry Eet_Entry;
struct _Eet_Entry
{
   const char *name; /**< The entry name */

   int offset;       /**< Where it start in the file  */
   int size;         /**< The size on disk */
   int data_size;    /**< The decompressed size if relevant */

   Eina_Bool compression; /**< Is this data compressed ? */
   Eina_Bool ciphered;    /**< Is it ciphered ? */
   Eina_Bool alias;       /**< Is it an alias ? */
};

/**
 * @}
 */

/**
 * Open an eet file on disk, and returns a handle to it.
 * @param file The file path to the eet file. eg: @c "/tmp/file.eet".
 * @param mode The mode for opening. Either #EET_FILE_MODE_READ,
 *        #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE.
 * @return An opened eet file handle.
 * @ingroup Eet_File_Group
 *
 * 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
 */
EAPI Eet_File *
eet_open(const char *file,
         Eet_File_Mode mode);

/**
 * 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.
 * @param data Address of file in memory.
 * @param size Size of memory to be read.
 * @return A handle to the file.
 *
 * Files opened this way will always be in read-only mode.
 *
 * @since 1.1.0
 * @ingroup Eet_File_Group
 */
EAPI Eet_File *
eet_memopen_read(const void *data,
                 size_t size);

/**
 * Get the mode an Eet_File was opened with.
 * @param ef A valid eet file handle.
 * @return The mode ef was opened with.
 *
 * @since 1.0.0
 * @ingroup Eet_File_Group
 */
EAPI Eet_File_Mode
eet_mode_get(Eet_File *ef);

/**
 * Close an eet file handle and flush pending writes.
 * @param ef A valid eet file handle.
 * @return 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
 * @ingroup Eet_File_Group
 * 
 * @see eet_clearcache()
 */
EAPI Eet_Error
eet_close(Eet_File *ef);

/**
 * Sync content of an eet file handle, flushing pending writes.
 * @param ef A valid eet file handle.
 * @return 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
 * @ingroup Eet_File_Group
 */
EAPI Eet_Error
eet_sync(Eet_File *ef);

/**
 * Return a handle to the shared string dictionary of the Eet file
 * @param ef A valid eet file handle.
 * @return A handle to the dictionary of the file
 *
 * This function returns a handle to the dictionary of an Eet file whose
 * handle is @p ef, if a dictionary exists. NULL is returned otherwise or
 * if the file handle is known to be invalid.
 *
 * @see 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
 * @ingroup Eet_File_Group
 */
EAPI Eet_Dictionary *
eet_dictionary_get(Eet_File *ef);

/**
 * Check if a given string comes from a given dictionary
 * @param ed A valid dictionary handle
 * @param string A valid 0 byte terminated C string
 * @return 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
 * @ingroup Eet_File_Group
 */
EAPI int
eet_dictionary_string_check(Eet_Dictionary *ed,
                            const char *string);

/**
 * Return the number of strings inside a dictionary
 * @param ed A valid dictionary handle
 * @return the number of strings inside a dictionary
 *
 * @since 1.6.0
 * @ingroup Eet_File_Group
 */
EAPI int
eet_dictionary_count(const Eet_Dictionary *ed);

/**
 * Read a specified entry from an eet file and return data
 * @param ef A valid eet file handle opened for reading.
 * @param name Name of the entry. eg: "/base/file_i_want".
 * @param size_ret Number of bytes read from entry and returned.
 * @return 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 eet_read_cipher()
 *
 * @since 1.0.0
 * @ingroup Eet_File_Group
 */
EAPI void *
eet_read(Eet_File *ef,
         const char *name,
         int *size_ret);

/**
 * Read a specified entry from an eet file and return data
 * @param ef A valid eet file handle opened for reading.
 * @param name Name of the entry. eg: "/base/file_i_want".
 * @param size_ret Number of bytes read from entry and returned.
 * @return 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
 * @ingroup Eet_File_Group
 */
EAPI const void *
eet_read_direct(Eet_File *ef,
                const char *name,
                int *size_ret);

/**
 * Write a specified entry to an eet file handle
 * @param ef A valid eet file handle opened for writing.
 * @param name Name of the entry. eg: "/base/file_i_want".
 * @param data Pointer to the data to be stored.
 * @param size Length in bytes in the data to be stored.
 * @param compress Compression flags (1 == compress, 0 = don't compress).
 * @return 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 eet_write_cipher()
 *
 * @since 1.0.0
 * @ingroup Eet_File_Group
 */
EAPI int
eet_write(Eet_File *ef,
          const char *name,
          const void *data,
          int size,
          int compress);

/**
 * Delete a specified entry from an Eet file being written or re-written
 * @param ef A valid eet file handle opened for writing.
 * @param name Name of the entry. eg: "/base/file_i_want".
 * @return 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
 * @ingroup Eet_File_Group
 */
EAPI int
eet_delete(Eet_File *ef,
           const char *name);

/**
 * Alias a specific section to another one. Destination may exist or not,
 * no checks are done.
 * @param ef A valid eet file handle opened for writing.
 * @param name Name of the new entry. eg: "/base/file_i_want".
 * @param destination Actual source of the aliased entry eg: "/base/the_real_stuff_i_want".
 * @param compress Compression flags (1 == compress, 0 = don't compress).
 * @return 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
 * @ingroup Eet_File_Group
 */
EAPI Eina_Bool
eet_alias(Eet_File *ef,
          const char *name,
          const char *destination,
          int compress);

/**
 * Retrieve the filename of an Eet_File
 * @param ef A valid eet file handle opened for writing.
 * @return 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
 * @ingroup Eet_File_Group
 */
EAPI const char *
eet_file_get(Eet_File *ef);

/**
 * Retrieve the destination name of an alias
 * @param ef A valid eet file handle opened for writing
 * @param name Name of the entry. eg: "/base/file_i_want"
 * @return 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
 * @ingroup Eet_File_Group
 */
EAPI const char *
eet_alias_get(Eet_File *ef,
              const char *name);