+/**
+ @brief Eet Data Handling Library Public API Calls
+
+ These routines are used for Eet Library interaction
+
+ @mainpage Eet Library Documentation
+
+ @version 1.6.0
+ @date 2000-2012
+
+ Please see the @ref authors page for contact details.
+
+ @section toc Table of Contents
+
+ @li @ref intro
+ @li @ref example
+ @li @ref compiling
+ @li @ref install
+ @li @ref next_steps
+ @li @ref intro_example
+
+ @section intro What is Eet?
+
+ 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 example A simple example on using Eet
+
+ 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
+
+ @section compiling How to compile using Eet ?
+
+ 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
+
+ You simply have to make sure that pkg-config is in your shell's PATH (see
+ the manual page for your appropriate shell) and eet.pc in /usr/lib/pkgconfig
+ or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
+ to link and use Eet once you have written your code to use it.
+
+ Since the program is linked to Eet, it is now able to use any advertised
+ API calls to serialize your data.
+
+ You should make sure you add any extra compile and link flags to your
+ compile commands that your application may need as well. The above example
+ is only guaranteed to make Eet add it's own requirements.
+
+
+ @section install How is it installed?
+
+ Simple:
+
+ @verbatim
+ ./configure
+ make
+ su -
+ ...
+ make install
+ @endverbatim
+
+ @section 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 Eina
+ (http://docs.enlightenment.org/auto/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 intro_example Introductory Examples
+
+ @ref Examples
+
+ @todo Document data format for images and data structures.
+
+ */
+
+/**
+ @page authors Authors
+ @author Carsten Haitzler <raster@@rasterman.com>
+ @author David Goodlad <dgoodlad@@gmail.com>
+ @author Cedric Bail <cedric.bail@@free.fr>
+ @author Arnaud de Turckheim <quarium@@gmail.com>
+ @author Luis Felipe Strano Moraes <lfelipe@@profusion.mobi>
+ @author Chidambar Zinnoury <illogict@@online.fr>
+ @author Vincent Torri <vtorri@@univ-evry.fr>
+ @author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
+ @author Raphael Kubo da Costa <kubo@@profusion.mobi>
+ @author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
+ @author Albin "Lutin" Tonnerre <albin.tonnerre@@gmail.com>
+ @author Adam Simpkins <adam@@adamsimpkins.net>
+ @author Mike Blumenkrantz <michael.blumenkrantz@gmail.com>
+
+ Please contact <enlightenment-devel@lists.sourceforge.net> to get in
+ contact with the developers and maintainers.
+ */
+
#ifndef _EET_H
#define _EET_H
*/
#define EET_VERSION_MAJOR 1
-#define EET_VERSION_MINOR 4
+#define EET_VERSION_MINOR 6
/**
* @typedef Eet_Version
*
* This is the Eet version information structure that can be used at
- * runtiime to detect which version of eet is being used and adapt
+ * runtime to detect which version of eet is being used and adapt
* appropriately as follows for example:
*
* @code
* #endif
* @endcode
*
- * Note the #if check can be dropped if your program refuses to compile or
+ * 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 rlease or the svn revsion number Eet is built from) */
+ 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;
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 fine is #EET_FILE_MODE_READ */
+ 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 since generic Input/Output error */
+ 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 */
/**
* @}
*/
+
+/**
+ * @defgroup Eet_Compression Eet Compression Levels
+ * 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.
*
- * @return The new init count.
+ * 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);
+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);
+EAPI int
+eet_shutdown(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.
+ * 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);
+EAPI void
+eet_clearcache(void);
/**
* @defgroup Eet_File_Group Eet File Main Functions
* 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".
* @{
*/
* @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 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 struct _Eet_Dictionary Eet_Dictionary;
/**
* @}
* does not exist it will be created, if the key exists it will be replaced
* by the new data.
*
- * Example:
- * @code
- * #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;
- * }
- * @endcode
+ * 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);
+EAPI Eet_File *
+eet_open(const char *file,
+ Eet_File_Mode mode);
/**
- * Open an eet file directly from a memory location. The data are not copied,
- * so you must keep them around as long as the eet file is open. Their is
- * currently no cache for this kind of Eet_File, so it's reopen every time
- * you do use eet_memopen_read.
+ * 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);
+EAPI Eet_File *
+eet_memopen_read(const void *data,
+ size_t size);
/**
* Get the mode an Eet_File was opened with.
* @since 1.0.0
* @ingroup Eet_File_Group
*/
-EAPI Eet_File_Mode eet_mode_get(Eet_File *ef);
+EAPI Eet_File_Mode
+eet_mode_get(Eet_File *ef);
/**
- * Close an eet file handle and flush and writes pending.
+ * 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.
+ * 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);
+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.
* @since 1.2.4
* @ingroup Eet_File_Group
*/
-EAPI Eet_Error eet_sync(Eet_File *ef);
+EAPI Eet_Error
+eet_sync(Eet_File *ef);
/**
* Return a handle to the shared string dictionary of the Eet file
*
* @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 instructrions.
+ * the #Eet_Data_Descriptor_Class instructions.
*
* @since 1.0.0
* @ingroup Eet_File_Group
*/
-EAPI Eet_Dictionary * eet_dictionary_get(Eet_File *ef);
+EAPI Eet_Dictionary *
+eet_dictionary_get(Eet_File *ef);
/**
* Check if a given string comes from a given dictionary
*
* 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
+ * 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);
+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
* @since 1.0.0
* @ingroup Eet_File_Group
*/
-EAPI void * eet_read(Eet_File *ef,
- const char *name,
- int *size_ret);
+EAPI void *
+eet_read(Eet_File *ef,
+ const char *name,
+ int *size_ret);
/**
* Read a specified entry from an eet file and return data
* 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
+ * 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.
*
* @since 1.0.0
* @ingroup Eet_File_Group
*/
-EAPI const void * eet_read_direct(Eet_File *ef,
- const char *name,
- int *size_ret);
+EAPI const void *
+eet_read_direct(Eet_File *ef,
+ const char *name,
+ int *size_ret);
/**
* Write a specified entry to an eet file handle
* @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);
+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
* @since 1.0.0
* @ingroup Eet_File_Group
*/
-EAPI int eet_delete(Eet_File *ef,
- const char *name);
+EAPI int
+eet_delete(Eet_File *ef,
+ const char *name);
/**
* Alias a specific section to another one. Destination may exist or not,
- * no check are done.
+ * no checks are done.
* @param ef A valid eet file handle opened for writing.
- * @param name Name of the entry. eg: "/base/file_i_want".
- * @param destination Destionation of the alias. eg: "/base/the_real_stuff_i_want".
+ * @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, otherwhise EINA_FALSE will be returned.
+ * 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);
+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);
/**
* List all entries in eet file matching shell glob.
* @since 1.0.0
* @ingroup Eet_File_Group
*/
-EAPI char ** eet_list(Eet_File *ef,
- const char *glob,
- int *count_ret);
+EAPI char **
+eet_list(Eet_File *ef,
+ const char *glob,
+ int *count_ret);
/**
* Return the number of entries in the specified eet file.
* @since 1.0.0
* @ingroup Eet_File_Group
*/
-EAPI int eet_num_entries(Eet_File *ef);
+EAPI int
+eet_num_entries(Eet_File *ef);
/**
* @defgroup Eet_File_Cipher_Group Eet File Ciphered Main Functions
* @since 1.0.0
* @ingroup Eet_File_Cipher_Group
*/
-EAPI void * eet_read_cipher(Eet_File *ef,
- const char *name,
- int *size_ret,
- const char *cipher_key);
+EAPI void *
+eet_read_cipher(Eet_File *ef,
+ const char *name,
+ int *size_ret,
+ const char *cipher_key);
/**
* Write a specified entry to an eet file handle using a cipher.
* @since 1.0.0
* @ingroup Eet_File_Cipher_Group
*/
-EAPI int eet_write_cipher(Eet_File *ef,
- const char *name,
- const void *data,
- int size,
- int compress,
- const char *cipher_key);
+EAPI int
+eet_write_cipher(Eet_File *ef,
+ const char *name,
+ const void *data,
+ int size,
+ int compress,
+ const char *cipher_key);
/**
* @defgroup Eet_File_Image_Group Image Store and Load
*
* Eet efficiently stores and loads images, including alpha
* channels and lossy compressions.
+ *
+ * Eet can handle both lossy compression with different levels of quality and
+ * non-lossy compression with different compression levels. It's also possible,
+ * given an image data, to only read its header to get the image information
+ * without decoding the entire content for it.
+ *
+ * The encode family of functions will take an image raw buffer and its
+ * parameters and compress it in memory, returning the new buffer.
+ * Likewise, the decode functions will read from the given location in memory
+ * and return the uncompressed image.
+ *
+ * The read and write functions will, respectively, encode and decode to or
+ * from an Eet file, under the specified key.
+ *
+ * These functions are fairly low level and the same functionality can be
+ * achieved using Evas and Edje, making it much easier to work with images
+ * as well as not needing to worry about things like scaling them.
*/
/**
* @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag.
- * @return 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.
+ * @return 1 on successful decode, 0 otherwise
*
- * 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.
+ * Reads and decodes the image header data stored under the given key and
+ * Eet file.
*
- * On success the function returns 1 indicating the header was read and
- * decoded properly, or 0 on failure.
+ * The information decoded is placed in each of the parameters, which must be
+ * provided. The width and height, measured in pixels, will be stored under
+ * the variables pointed by @p w and @p h, respectively. If the read or
+ * decode of the header fails, this values will be 0. The @p alpha parameter
+ * will be 1 or 0, denoting if the alpha channel of the image is used or not.
+ * If the image was losslessly compressed, the @p compress parameter will hold
+ * the compression amount used, ranging from 0 to 9 and @p lossy will be 0.
+ * In the case of lossy compression, @p lossy will be 1, and the compression
+ * quality will be placed under @p quality, with a value ranging from 0 to 100.
*
+ * @see eet_data_image_header_decode()
* @see eet_data_image_header_read_cipher()
*
* @since 1.0.0
* @ingroup Eet_File_Image_Group
*/
-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);
+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 image data from the named key in the eet file.
* @param lossy A pointer to the int to hold the lossiness flag.
* @return 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.
+ * Reads and decodes the image stored in the given Eet file under the named
+ * key.
*
- * 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.
+ * The returned 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 rest of the parameters are the same as in eet_data_image_header_read().
*
* 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.
*
+ * @see eet_data_image_header_read()
+ * @see eet_data_image_decode()
* @see eet_data_image_read_cipher()
+ * @see eet_data_image_read_to_surface()
*
* @since 1.0.0
* @ingroup Eet_File_Image_Group
*/
-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);
+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.
+ * Read image data from the named key in the eet file and store it in the given buffer.
* @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want".
* @param src_x The starting x coordinate from where to dump the stream.
* @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on success, 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.
+ * Reads and decodes the image stored in the given Eet file, placing the
+ * resulting pixel data in the buffer pointed by the user.
*
- * 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.
+ * Like eet_data_image_read(), it takes the image data stored under the
+ * @p name key in the @p ef file, but instead of returning a new buffer with
+ * the pixel data, it places the result in the buffer pointed by @p d, which
+ * must be provided by the user and of sufficient size to hold the requested
+ * portion of the image.
+ *
+ * The @p src_x and @p src_y parameters indicate the top-left corner of the
+ * section of the image to decode. These have to be higher or equal than 0 and
+ * less than the respective total width and height of the image. The width
+ * and height of the section of the image to decode are given in @p w and @p h
+ * and also can't be higher than the total width and height of the image.
+ *
+ * The @p row_stride parameter indicates the length in bytes of each line in
+ * the destination buffer and it has to be at least @p w * 4.
+ *
+ * All the other parameters are the same as in eet_data_image_read().
*
* On success the function returns 1, and 0 on failure. On failure the
* parameter values may not contain any sensible data.
*
+ * @see eet_data_image_read()
+ * @see eet_data_image_decode()
+ * @see eet_data_image_decode_to_surface()
* @see eet_data_image_read_to_surface_cipher()
*
* @since 1.0.2
* @ingroup Eet_File_Image_Group
*/
-EAPI int eet_data_image_read_to_surface(Eet_File *ef,
- const char *name,
- unsigned int src_x,
- unsigned int src_y,
- unsigned int *d,
- unsigned int w,
- unsigned int h,
- unsigned int row_stride,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI int
+eet_data_image_read_to_surface(Eet_File *ef,
+ const char *name,
+ unsigned int src_x,
+ unsigned int src_y,
+ unsigned int *d,
+ unsigned int w,
+ unsigned int h,
+ unsigned int row_stride,
+ int *alpha,
+ int *compress,
+ int *quality,
+ int *lossy);
/**
* Write image data to the named key in an eet file.
* On success this function returns the number of bytes that were required
* to encode the image data, or on failure it returns 0.
*
+ * @see eet_data_image_read()
+ * @see eet_data_image_encode()
* @see eet_data_image_write_cipher()
*
* @since 1.0.0
* @ingroup Eet_File_Image_Group
*/
-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);
+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);
/**
* Decode Image data header only to get information.
* @param lossy A pointer to the int to hold the lossiness flag.
* @return 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.
+ * This function works exactly like eet_data_image_header_read(), but instead
+ * of reading from an Eet file, it takes the buffer of size @p size pointed
+ * by @p data, which must be a valid Eet encoded image.
*
* On success the function returns 1 indicating the header was read and
* decoded properly, or 0 on failure.
*
+ * @see eet_data_image_header_read()
* @see eet_data_image_header_decode_cipher()
*
* @since 1.0.0
* @ingroup Eet_File_Image_Group
*/
-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);
+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 into pixel data.
* 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.
+ * It works exactly like eet_data_image_read(), but it takes the encoded
+ * data in the @p data buffer of size @p size, instead of reading from a file.
+ * All the others parameters are also the same.
*
* 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.
*
+ * @see eet_data_image_read()
* @see eet_data_image_decode_cipher()
*
* @since 1.0.0
* @ingroup Eet_File_Image_Group
*/
-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);
+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.
+ * Decode Image data into pixel data and stores in the given buffer.
* @param data The encoded pixel data.
* @param size The size, in bytes, of the encoded pixel data.
* @param src_x The starting x coordinate from where to dump the stream.
* @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on success, 0 otherwise.
*
- * This function takes encoded pixel data and decodes it into raw RGBA
- * pixels on success.
- *
- * The other parameters of the image (alpha, compress 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.
+ * Like eet_data_image_read_to_surface(), but reading the given @p data buffer
+ * instead of a file.
*
* On success the function returns 1, and 0 on failure. On failure the
* parameter values may not contain any sensible data.
*
+ * @see eet_data_image_read_to_surface()
* @see eet_data_image_decode_to_surface_cipher()
*
* @since 1.0.2
* @ingroup Eet_File_Image_Group
*/
-EAPI int eet_data_image_decode_to_surface(const void *data,
- int size,
- unsigned int src_x,
- unsigned int src_y,
- unsigned int *d,
- unsigned int w,
- unsigned int h,
- unsigned int row_stride,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI int
+eet_data_image_decode_to_surface(const void *data,
+ int size,
+ unsigned int src_x,
+ unsigned int src_y,
+ unsigned int *d,
+ unsigned int w,
+ unsigned int h,
+ unsigned int row_stride,
+ int *alpha,
+ int *compress,
+ int *quality,
+ int *lossy);
/**
* Encode image data for storage or transmission.
* 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).
+ * It works like eet_data_image_write(), but instead of writing the encoded
+ * image into an Eet file, it allocates a new buffer of the size required and
+ * returns the encoded data in it.
*
* On success this function returns a pointer to the encoded data that you
* can free with free() when no longer needed.
*
+ * @see eet_data_image_write()
+ * @see eet_data_image_read()
* @see eet_data_image_encode_cipher()
*
* @since 1.0.0
* @ingroup Eet_File_Image_Group
*/
-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);
+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);
/**
* @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Cipher
* @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag.
- * @return 1 on successfull decode, 0 otherwise
+ * @return 1 on successful 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
+ * 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
* @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI int eet_data_image_header_read_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key,
- unsigned int *w,
- unsigned int *h,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI int
+eet_data_image_header_read_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key,
+ 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 using a cipher.
* 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
+ * 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
* @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI void * eet_data_image_read_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key,
- unsigned int *w,
- unsigned int *h,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI void *
+eet_data_image_read_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key,
+ 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 using a cipher.
* 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
+ * 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
* @since 1.0.2
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI int eet_data_image_read_to_surface_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key,
- unsigned int src_x,
- unsigned int src_y,
- unsigned int *d,
- unsigned int w,
- unsigned int h,
- unsigned int row_stride,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI int
+eet_data_image_read_to_surface_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key,
+ unsigned int src_x,
+ unsigned int src_y,
+ unsigned int *d,
+ unsigned int w,
+ unsigned int h,
+ unsigned int row_stride,
+ int *alpha,
+ int *compress,
+ int *quality,
+ int *lossy);
/**
* Write image data to the named key in an eet file using a cipher.
* @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI int eet_data_image_write_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key,
- const void *data,
- unsigned int w,
- unsigned int h,
- int alpha,
- int compress,
- int quality,
- int lossy);
+EAPI int
+eet_data_image_write_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key,
+ const void *data,
+ unsigned int w,
+ unsigned int h,
+ int alpha,
+ int compress,
+ int quality,
+ int lossy);
/**
* Decode Image data header only to get information using a cipher.
* @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI int eet_data_image_header_decode_cipher(const void *data,
- const char *cipher_key,
- int size,
- unsigned int *w,
- unsigned int *h,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI int
+eet_data_image_header_decode_cipher(const void *data,
+ const char *cipher_key,
+ int size,
+ unsigned int *w,
+ unsigned int *h,
+ int *alpha,
+ int *compress,
+ int *quality,
+ int *lossy);
/**
* Decode Image data into pixel data using a cipher.
* @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI void * eet_data_image_decode_cipher(const void *data,
- const char *cipher_key,
- int size,
- unsigned int *w,
- unsigned int *h,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI void *
+eet_data_image_decode_cipher(const void *data,
+ const char *cipher_key,
+ int size,
+ unsigned int *w,
+ unsigned int *h,
+ int *alpha,
+ int *compress,
+ int *quality,
+ int *lossy);
/**
* Decode Image data into pixel data using a cipher.
* @since 1.0.2
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI int eet_data_image_decode_to_surface_cipher(const void *data,
- const char *cipher_key,
- int size,
- unsigned int src_x,
- unsigned int src_y,
- unsigned int *d,
- unsigned int w,
- unsigned int h,
- unsigned int row_stride,
- int *alpha,
- int *compress,
- int *quality,
- int *lossy);
+EAPI int
+eet_data_image_decode_to_surface_cipher(const void *data,
+ const char *cipher_key,
+ int size,
+ unsigned int src_x,
+ unsigned int src_y,
+ unsigned int *d,
+ unsigned int w,
+ unsigned int h,
+ unsigned int row_stride,
+ int *alpha,
+ int *compress,
+ int *quality,
+ int *lossy);
/**
* Encode image data for storage or transmission using a cipher.
* @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group
*/
-EAPI void * eet_data_image_encode_cipher(const void *data,
- const char *cipher_key,
- unsigned int w,
- unsigned int h,
- int alpha,
- int compress,
- int quality,
- int lossy,
- int *size_ret);
+EAPI void *
+eet_data_image_encode_cipher(const void *data,
+ const char *cipher_key,
+ unsigned int w,
+ unsigned int h,
+ int alpha,
+ int compress,
+ int quality,
+ int lossy,
+ int *size_ret);
/**
* @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms
* Opaque handle that defines an identity (also known as key)
* in Eet's cipher system.
*/
-typedef struct _Eet_Key Eet_Key;
+typedef struct _Eet_Key Eet_Key;
/**
* @}
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-typedef int (* Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data);
+typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data);
/**
* Create an Eet_Key needed for signing an eet file.
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-EAPI Eet_Key * eet_identity_open(const char *certificate_file,
- const char *private_key_file,
- Eet_Key_Password_Callback cb);
+EAPI Eet_Key *
+eet_identity_open(const char *certificate_file,
+ const char *private_key_file,
+ Eet_Key_Password_Callback cb);
/**
- * Close and release all ressource used by an Eet_Key. An
+ * Close and release all resource used by an Eet_Key. An
* reference counter prevent it from being freed until all file
* using it are also closed.
*
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-EAPI void eet_identity_close(Eet_Key *key);
+EAPI void
+eet_identity_close(Eet_Key *key);
/**
* Set a key to sign a file
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-EAPI Eet_Error eet_identity_set(Eet_File *ef,
- Eet_Key *key);
+EAPI Eet_Error
+eet_identity_set(Eet_File *ef,
+ Eet_Key *key);
/**
* Display both private and public key of an Eet_Key.
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-EAPI void eet_identity_print(Eet_Key *key,
- FILE *out);
+EAPI void
+eet_identity_print(Eet_Key *key,
+ FILE *out);
/**
* Get the x509 der certificate associated with an Eet_File. Will return NULL
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-EAPI const void * eet_identity_x509(Eet_File *ef,
- int *der_length);
+EAPI const void *
+eet_identity_x509(Eet_File *ef,
+ int *der_length);
/**
* Get the raw signature associated with an Eet_File. Will return NULL
*
* @ingroup Eet_Cipher_Group
*/
-EAPI const void * eet_identity_signature(Eet_File *ef,
- int *signature_length);
+EAPI const void *
+eet_identity_signature(Eet_File *ef,
+ int *signature_length);
/**
* Get the SHA1 associated with a file. Could be the one used to
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-EAPI const void * eet_identity_sha1(Eet_File *ef,
- int *sha1_length);
+EAPI const void *
+eet_identity_sha1(Eet_File *ef,
+ int *sha1_length);
/**
* Display the x509 der certificate to out.
* @since 1.2.0
* @ingroup Eet_Cipher_Group
*/
-EAPI void eet_identity_certificate_print(const unsigned char *certificate,
- int der_length,
- FILE *out);
+EAPI void
+eet_identity_certificate_print(const unsigned char *certificate,
+ int der_length,
+ FILE *out);
/**
* @defgroup Eet_Data_Group Eet Data Serialization
* quite cumbersome, so we provide lots of macros and convenience
* functions to aid creating the types.
*
- * Example:
- *
+ * We make now a quick overview of some of the most commonly used elements
+ * of this part of the library. A simple example of a configuration system
+ * will work as a somewhat real life example that is still simple enough to
+ * follow.
+ * Only the relevant sections will be shown here, but you can get the full
+ * code @ref eet-data-simple.c "here".
+ *
+ * Ignoring the included headers, we'll begin by defining our configuration
+ * struct.
+ * @dontinclude eet-data-simple.c
+ * @skip typedef
+ * @until }
+ *
+ * When using Eet, you don't think in matters of what data the program needs
+ * to run and which you would like to store. It's all the same and if it makes
+ * more sense to keep them together, it's perfectly fine to do so. At the time
+ * of telling Eet how your data is comprised you can leave out the things
+ * that are runtime only and let Eet take care of the rest for you.
+ *
+ * The key used to store the config follows, as well as the variable used to
+ * store our data descriptor.
+ * This last one is very important. It's the one thing that Eet will use to
+ * identify your data, both at the time of writing it to the file and when
+ * loading from it.
+ * @skipline MY_CONF
+ * @skipline Eet_Data_Descriptor
+ *
+ * Now we'll see how to create this descriptor, so Eet knows how to handle
+ * our data later on.
+ * Begin our function by declaring an Eet_Data_Descriptor_Class, which is
+ * used to create the actual descriptor. This class contains the name of
+ * our data type, its size and several functions that dictate how Eet should
+ * handle memory to allocate the necessary bits to bring our data to life.
+ * You, as a user, will very hardly set this class' contents directly. The
+ * most common scenario is to use one of the provided macros that set it using
+ * the Eina data types, so that's what we'll be doing across all our examples.
+ * @skip static void
+ * @until eet_data_descriptor_stream_new
+ *
+ * Now that we have our descriptor, we need to make it describe something.
+ * We do so by telling it which members of our struct we want it to know about
+ * and their types.
+ * The eet_data_descriptor_element_add() function takes care of this, but it's
+ * too cumbersome for normal use, so several macros are provided that make
+ * it easier to handle. Even with them, however, code can get very repetitive
+ * and it's not uncommon to define custom macros using them to save on typing.
+ * @skip #define
+ * @until }
+ *
+ * Now our descriptor knows about the parts of our structure that we are
+ * interesting in saving. You can see that not all of them are there, yet Eet
+ * will find those that need saving and do the right thing. When loading our
+ * data, any non-described fields in the structure will be zeroed, so there's
+ * no need to worry about garbage memory in them.
+ * Refer to the documentation of #EET_DATA_DESCRIPTOR_ADD_BASIC to understand
+ * what our macro does.
+ *
+ * We are done with our descriptor init function and it's proper to have the
+ * relevant shutdown. Proper coding guidelines indiciate that all memory
+ * allocated should be freed when the program ends, and since you will most
+ * likely keep your descriptor around for the life or your application, it's
+ * only right to free it at the end.
+ * @skip static void
+ * @until }
+ *
+ * Not listed here, but included in the full example are functions to create
+ * a blank configuration and free it. The first one will only be used when
+ * no file exists to load from, or nothing is found in it, but the latter is
+ * used regardless of where our data comes from. Unless you are reading direct
+ * data from the Eet file, you will be in charge of freeing anything loaded
+ * from it.
+ *
+ * Now it's time to look at how we can load our config from some file.
+ * Begin by opening the Eet file normally.
+ * @skip static My_Conf_Type
+ * @until }
+ *
+ * And now we need to read the data from the file and decode it using our
+ * descriptor. Fortunately, that's all done in one single step.
+ * @until goto
+ *
+ * And that's it for all Eet cares about. But since we are dealing with a
+ * common case, as is save and load of user configurations, the next fragment
+ * of code shows why we have a version field in our struct, and how you can
+ * use it to load older configuration files and update them as needed.
+ * @until }
+ *
+ * Finally, close the file and return the newly loaded config data.
+ * @until }
+ *
+ * Saving data is just as easy. The full version of the following function
+ * includes code to save to a temporary file first, so you can be sure not
+ * to lose all your data in the case of a failure mid-writing. You can look
+ * at it @ref eet-data-simple.c "here".
+ * @skip static Eina_Bool
+ * @until {
+ * @skipline Eina_Bool ret
+ * @skip eet_open
+ * @until eet_close
+ * @skip return
+ * @until }
+ *
+ * To close, our main function, which doesn't do much. Just take some arguments
+ * from the command line with the name of the file to load and another one
+ * where to save again. If input file doesn't exist, a new config structure
+ * will be created and saved to our output file.
+ * @skip int main
+ * @until return ret
+ * @until }
+ *
+ * The following is a list of more advanced and detailed examples.
+ * @li @ref eet_data_nested_example
+ * @li @ref eet_data_file_descriptor
+ * @li @ref Example_Eet_Data_File_Descriptor_02
+ * @li @ref Example_Eet_Data_Cipher_Decipher
+ */
+
+/**
+ * @page eet_data_nested_example Nested structures and Eet Data Descriptors
+ *
+ * We've seen already a simple example of how to use Eet Data Descriptors
+ * to handle our structures, but it didn't show how this works when you
+ * have structures inside other structures.
+ *
+ * Now, there's a very simple case of this, for when you have inline structs
+ * to keep your big structure more organized, you don't need anything else
+ * besides what @ref eet-data-simple.c "this simple example does".
+ * Just use something like @p some_struct.sub_struct.member when adding the
+ * member to the descriptor and it will work.
+ *
+ * For example:
* @code
- * #include <Eet.h>
- * #include <Evas.h>
- *
- * typedef struct _blah2
+ * typedef struct
* {
- * char *string;
- * } Blah2;
- *
- * typedef struct _blah3
+ * int a_number;
+ * char *a_string;
+ * struct {
+ * int other_num;
+ * int one_more;
+ * } sub;
+ * } some_struct;
+ *
+ * void some_function()
* {
- * char *string;
- * } Blah3;
+ * ...
+ * my_desc = eet_data_descriptor_stream_new(&eddc);
+ * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_number",
+ * a_number, EET_T_INT);
+ * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_string",
+ * a_string, EET_T_STRING);
+ * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.other_num",
+ * sub.other_num, EET_T_INT);
+ * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.one_more",
+ * sub.one_more", EET_T_INT);
+ * ...
+ * }
+ * @endcode
*
- * typedef struct _blah
- * {
- * char character;
- * short sixteen;
- * int integer;
- * long long lots;
- * float floating;
- * double floating_lots;
- * char *string;
- * Blah2 *blah2;
- * Eina_List *blah3;
- * } Blah;
- *
- * int
- * main(int argc, char **argv)
+ * But this is not what we are here for today. When we talk about nested
+ * structures, what we really want are things like lists and hashes to be
+ * taken into consideration automatically, and all their contents saved and
+ * loaded just like ordinary integers and strings are.
+ *
+ * And of course, Eet can do that, and considering the work it saves you as a
+ * programmer, we could say it's even easier to do than handling just integers.
+ *
+ * Let's begin with our example then, which is not all too different from the
+ * simple one introduced earlier.
+ *
+ * We won't ignore the headers this time to show how easy it is to use Eina
+ * data types with Eet, but we'll still skip most of the code that is not
+ * pertinent to what we want to show now, but as usual, you can get it full
+ * by following @ref eet-data-nested.c "this link".
+ *
+ * @dontinclude eet-data-nested.c
+ * @skipline Eina.h
+ * @skipline Eet.h
+ * @skip typedef struct
+ * @until } My_Conf_Subtype
+ *
+ * Extremely similar to our previous example. Just a new struct in there, and
+ * a pointer to a list in the one we already had. Handling a list of subtypes
+ * is easy on our program, but now we'll see what Eet needs to work with them
+ * (Hint: it's easy too).
+ * @skip _my_conf_descriptor
+ * @until _my_conf_sub_descriptor
+ *
+ * Since we have two structures now, it's only natural that we'll need two
+ * descriptors. One for each, which will be defined exactly as before.
+ * @skip static void
+ * @until eddc
+ * @skip EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET
+ * @until _my_conf_sub_descriptor
+ *
+ * We create our descriptors, each for one type, and as before, we are going to
+ * use a simple macro to set their contents, to save on typing.
+ * @skip #define
+ * @until EET_T_UCHAR
+ *
+ * So far, nothing new. We have our descriptors and we know already how to
+ * save them separately. But what we want is to link them together, and even
+ * more so, we want our main type to hold a list of more than one of the new
+ * sub type. So how do we do that?
+ *
+ * Simple enough, we tell Eet that our main descriptor will hold a list, of
+ * which each node will point to some type described by our new descriptor.
+ * @skip EET_DATA_DESCRIPTOR_ADD_LIST
+ * @until _my_conf_sub_descriptor
+ *
+ * And that's all. We are closing the function now so as to not leave dangling
+ * curly braces, but there's nothing more to show in this example. Only other
+ * additions are the necessary code to free our new data, but you can see it
+ * in the full code listing.
+ * @until }
+ */
+
+/**
+ * @page eet_data_file_descriptor Advanced use of Eet Data Descriptors
+ *
+ * A real life example is usually the best way to see how things are used,
+ * but they also involve a lot more code than what needs to be shown, so
+ * instead of going that way, we'll be borrowing some pieces from one in
+ * the following example. It's been slightly modified from the original
+ * source to show more of the varied ways in which Eet can handle our data.
+ *
+ * @ref eet-data-file_descriptor_01.c "This example" shows a cache of user
+ * accounts and messages received, and it's a bit more interactive than
+ * previous examples.
+ *
+ * Let's begin by looking at the structures we'll be using. First we have
+ * one to define the messages the user receives and one for the one he posts.
+ * Straight forward and nothing new here.
+ * @dontinclude eet-data-file_descriptor_01.c
+ * @skip typedef
+ * @until My_Post
+ *
+ * One more to declare the account itself. This one will contain a list of
+ * all messages received, and the posts we make ourselves will be kept in an
+ * array. No special reason other than to show how to use arrays with Eet.
+ * @until My_Account
+ *
+ * Finally, the main structure to hold our cache of accounts. We'll be looking
+ * for these accounts by their names, so let's keep them in a hash, using
+ * that name as the key.
+ * @until My_Cache
+ *
+ * As explained before, we need one descriptor for each struct we want Eet
+ * to handle, but this time we also want to keep around our Eet file and its
+ * string dictionary. You will see why in a moment.
+ * @skip Eet_Data_Descriptor
+ * @until _my_post_descriptor
+ * @skip Eet_File
+ * @until Eet_Dictionary
+ *
+ * The differences begin now. They aren't much, but we'll be creating our
+ * descriptors differently. Things can be added to our cache, but we won't
+ * be modifying the current contents, so we can consider the data read from
+ * it to be read-only, and thus allow Eet to save time and memory by not
+ * duplicating thins unnecessary.
+ * @skip static void
+ * @until _my_post_descriptor
+ *
+ * As the comment in the code explains, we are asking Eet to give us strings
+ * directly from the mapped file, which avoids having to load it in memory
+ * and data duplication.
+ * Of course, there are things to take into account when doing things this
+ * way, and they will be mentioned as we encounter those special cases.
+ *
+ * Next comes the actual description of our data, just like we did in the
+ * previous examples.
+ * @skip #define
+ * @until #undef
+ * @until #define
+ * @until #undef
+ *
+ * And the account struct's description doesn't add much new, but it's worth
+ * commenting on it.
+ * @skip #define
+ * @until _my_post_descriptor
+ *
+ * How to add a list we've seen before, but now we are also adding an array.
+ * There's nothing really special about it, but it's important to note that
+ * the EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY is used to add arrays of variable
+ * length to a descriptor. That is, arrays just like the one we defined.
+ * Since there's no way in C to know how long they are, we need to keep
+ * track of the count ourselves and Eet needs to know how to do so as well.
+ * That's what the @p posts_count member of our struct is for. When adding
+ * our array member, this macro will look for another variable in the struct
+ * named just like the array, but with @p _count attached to the end.
+ * When saving our data, Eet will know how many elements the array contains
+ * by looking into this count variable. When loading back from a file, this
+ * variable will be set to the right number of elements.
+ *
+ * Another option for arrays is to use EET_DATA_DESCRIPTOR_ADD_ARRAY, which
+ * takes care of fixed sized arrays.
+ * For example, let's suppose that we want to keep track of only the last
+ * ten posts the user sent, and we declare our account struct as follows
+ * @code
+ * typedef struct
* {
- * Blah blah;
- * Blah2 blah2;
- * Blah3 blah3;
- * Eet_Data_Descriptor *edd, *edd2, *edd3;
- * Eet_Data_Descriptor_Class eddc, eddc2, eddc3;
- * void *data;
- * int size;
- * FILE *f;
- * Blah *blah_in;
- *
- * eet_init();
- *
- * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc3, Blah3);
- * edd3 = eet_data_descriptor_stream_new(&eddc3);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd3, Blah3, "string3", string, EET_T_STRING);
- *
- * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc2, Blah2);
- * edd2 = eet_data_descriptor_stream_new(&eddc2);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd2, Blah2, "string2", string, EET_T_STRING);
- *
- * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc, Blah);
- * edd = eet_data_descriptor_stream_new(&eddc);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "character", character, EET_T_CHAR);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "sixteen", sixteen, EET_T_SHORT);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "integer", integer, EET_T_INT);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "lots", lots, EET_T_LONG_LONG);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating", floating, EET_T_FLOAT);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating_lots", floating_lots, EET_T_DOUBLE);
- * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "string", string, EET_T_STRING);
- * EET_DATA_DESCRIPTOR_ADD_SUB(edd, Blah, "blah2", blah2, edd2);
- * EET_DATA_DESCRIPTOR_ADD_LIST(edd, Blah, "blah3", blah3, edd3);
- *
- * blah3.string = "PANTS";
- *
- * blah2.string = "subtype string here!";
- *
- * blah.character = '7';
- * blah.sixteen = 0x7777;
- * blah.integer = 0xc0def00d;
- * blah.lots = 0xdeadbeef31337777;
- * blah.floating = 3.141592654;
- * blah.floating_lots = 0.777777777777777;
- * blah.string = "bite me like a turnip";
- * blah.blah2 = &blah2;
- * blah.blah3 = eina_list_append(NULL, &blah3);
- * blah.blah3 = eina_list_append(blah.blah3, &blah3);
- * blah.blah3 = eina_list_append(blah.blah3, &blah3);
- * blah.blah3 = eina_list_append(blah.blah3, &blah3);
- * blah.blah3 = eina_list_append(blah.blah3, &blah3);
- * blah.blah3 = eina_list_append(blah.blah3, &blah3);
- * blah.blah3 = eina_list_append(blah.blah3, &blah3);
- *
- * data = eet_data_descriptor_encode(edd, &blah, &size);
- * printf("-----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);
- * {
- * Eina_List *l;
- * Blah3 *blah3_in;
- *
- * EINA_LIST_FOREACH(blah_in->blah3, l, blah3_in)
- * {
- * 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);
- *
- * eet_shutdown();
- *
- * return 0;
- * }
+ * unsigned int id;
+ * const char *name;
+ * Eina_List *messages;
+ * My_Post posts[10];
+ * } My_Account;
+ * @endcode
+ * Then we would add the array to our descriptor with
+ * @code
+ * EET_DATA_DESCRIPTOR_ADD_ARRAY(_my_account_descriptor, My_Account, "posts",
+ * posts, _my_post_descriptor);
* @endcode
*
+ * Notice how this time we don't have a @p posts_count variable in our struct.
+ * We could have it for the program to keep track of how many posts the
+ * array actually contains, but Eet no longer needs it. Being defined that
+ * way the array is already taking up all the memory needed for the ten
+ * elements, and it is possible in C to determine how much it is in code.
+ * When saving our data, Eet will just dump the entire memory blob into the
+ * file, regardless of how much of it is really used. So it's important to
+ * take into consideration this kind of things when defining your data types.
+ * Each has its uses, its advantages and disadvantages and it's up to you
+ * to decide which to use.
+ *
+ * Now, going back to our example, we have to finish adding our data to the
+ * descriptors. We are only missing the main one for the cache, which
+ * contains our hash of accounts.
+ * Unless you are using your own hash functions when setting the descriptor
+ * class, always use hashes with string type keys.
+ * @skip #define
+ * @until }
+ *
+ * If you remember, we told Eet not to duplicate memory when possible at the
+ * time of loading back our data. But this doesn't mean everything will be
+ * loaded straight from disk and we don't have to worry about freeing it.
+ * Data in the Eet file is compressed and encoded, so it still needs to be
+ * decoded and memory will be allocated to convert it back into something we
+ * can use. We also need to take care of anything we add in the current
+ * instance of the program.
+ * To summarize, any string we get from Eet is likely to be a pointer to the
+ * internal dictionary, and trying to free it will, in the best case, crash
+ * our application right away.
+ *
+ * So how do we know if we have to free a string? We check if it's part of
+ * the dictionary, and if it's not there we can be sure it's safe to get
+ * rid of it.
+ * @skip static void
+ * @skip }
+ * @skip static void
+ * @until }
+ *
+ * See how this is used when adding a new message to our cache.
+ * @skip static My_Message
+ * @until return msg
+ * @until free(msg)
+ * @until }
+ *
+ * Skipping all the utility functions used by our program (remember you can
+ * look at the full example @ref eet-data-file_descriptor_01.c "here") we get to
+ * our cache loading code. Nothing out of the ordinary at first, just the
+ * same old open file, read data using our main descriptor to decode it
+ * into something we can use and check version of loaded data and if it doesn't
+ * match, do something accordingly.
+ * @skip static My_Cache
+ * @until }
+ * @until }
+ * @until }
+ *
+ * Then comes the interesting part. Remember how we kept two more global
+ * variables with our descriptors? One of them we already used to check if
+ * it was right to free a string or not, but we didn't know where it came from.
+ * Loading our data straight from the mmapped file means that we can't close
+ * it until we are done using it, so we need to keep its handler around until
+ * then. It also means that any changes done to the file can, and will,
+ * invalidate all our pointers to the file backed data, so if we add something
+ * and save the file, we need to reload our cache.
+ *
+ * Thus our load function checks if we had an open file, if there is it gets
+ * closed and our variable is updated to the new handler. Then we get the
+ * string dictionary we use to check if a string is part of it or not.
+ * Updating any references to the cache data is up you as a programmer to
+ * handle properly, there's nothing Eet can do in this situation.
+ * @until }
+ *
+ * The save function doesn't have anything new, and all that's left after it
+ * is the main program, which doesn't really have anything of interest within
+ * the scope of what we are learning.
+ */
+
+/**
+ * @addtogroup Eet_Data_Group
* @{
*/
#define EET_T_UNKNOW 0 /**< Unknown data encoding type */
*
* Opaque handle that have information on a type members.
*
+ * Descriptors are created using an #Eet_Data_Descriptor_Class, and they
+ * describe the contents of the structure that will be serialized by Eet.
+ * Not all members need be described by it, just those that should be handled
+ * by Eet. This way it's possible to have one structure with both data to be
+ * saved to a file, like application configuration, and runtime information
+ * that would be meaningless to store, but is appropriate to keep together
+ * during the program execution.
* The members are added by means of
* EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(),
* EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH()
* @see eet_data_descriptor_file_new()
* @see eet_data_descriptor_free()
*/
-typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor;
+typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor;
/**
* @def EET_DATA_DESCRIPTOR_CLASS_VERSION
* Instructs Eet about memory management for different needs under
* serialization and parse process.
*/
-typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
-
+typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
+
+typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt);
+
+typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size);
+typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem);
+typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str);
+typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str);
+typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l);
+typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d);
+typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l);
+typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l);
+typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt);
+typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d);
+typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h);
+typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str);
+typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str);
+typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow);
+typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow);
+typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size);
+typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem);
/**
* @struct _Eet_Data_Descriptor_Class
*
* Instructs Eet about memory management for different needs under
* serialization and parse process.
*
- * If using Eina data types, it is advised to use the helpers
- * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
- * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET().
+ * The list and hash methods match the Eina API, so for a more detailed
+ * reference on them, look at the Eina_List and Eina_Hash documentation,
+ * respectively.
+ * For the most part these will be used with the standard Eina functions,
+ * so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
+ * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything
+ * accordingly.
*/
struct _Eet_Data_Descriptor_Class
{
- int version; /**< ABI version as #EET_DATA_DESCRIPTOR_CLASS_VERSION */
- const char *name; /**< Name of data type to be serialized */
- int size; /**< Size in bytes of data type to be serialized */
+ int version; /**< ABI version. Should always be set to #EET_DATA_DESCRIPTOR_CLASS_VERSION */
+ const char *name; /**< Name of the user data type to be serialized */
+ int size; /**< Size in bytes of the user data type to be serialized */
struct
{
- void * (*mem_alloc)(size_t size); /**< how to allocate memory (usually malloc()) */
- void (*mem_free)(void *mem); /**< how to free memory (usually free()) */
- char * (*str_alloc)(const char *str); /**< how to allocate a string */
- void (*str_free)(const char *str); /**< how to free a string */
- void * (*list_next)(void *l); /**< how to iterate to the next element of a list. Receives and should return the list node. */
- void * (*list_append)(void *l, void *d); /**< how to append data @p d to list which head node is @p l */
- void * (*list_data)(void *l); /**< retrieves the data from node @p l */
- void * (*list_free)(void *l); /**< free all the nodes from the list which head node is @p l */
- void (*hash_foreach)(void *h, int (*func)(void *h, const char *k, void *dt, void *fdt), void *fdt); /**< iterates over all elements in the hash @p h in no specific order */
- void * (*hash_add)(void *h, const char *k, void *d); /**< add a new data @p d as key @p k in hash @p h */
- void (*hash_free)(void *h); /**< free all entries from the hash @p h */
- char * (*str_direct_alloc)(const char *str); /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */
- void (*str_direct_free)(const char *str); /**< how to free a string returned by str_direct_alloc */
- const char *(*type_get)(const void *data, Eina_Bool *unknow); /**< convert any kind of data type to a name that define an Eet_Data_Element. */
- Eina_Bool (*type_set)(const char *type, void *data, Eina_Bool unknow); /**< set the type at a particular adress */
- void * (*array_alloc)(size_t size); /**< how to allocate memory for array (usually malloc()) */
- void (*array_free)(void *mem); /**< how to free memory for array (usually free()) */
+ Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to allocate memory (usually malloc()) */
+ Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free memory (usually free()) */
+ Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to allocate a string */
+ Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a string */
+ Eet_Descriptor_List_Next_Callback list_next; /**< how to iterate to the next element of a list. Receives and should return the list node. */
+ Eet_Descriptor_List_Append_Callback list_append; /**< how to append data @p d to list which head node is @p l */
+ Eet_Descriptor_List_Data_Callback list_data; /**< retrieves the data from node @p l */
+ Eet_Descriptor_List_Free_Callback list_free; /**< free all the nodes from the list which head node is @p l */
+ Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates over all elements in the hash @p h in no specific order */
+ Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new data @p d with key @p k in hash @p h */
+ Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all entries from the hash @p h */
+ Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */
+ Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to free a string returned by str_direct_alloc */
+ Eet_Descriptor_Type_Get_Callback type_get; /**< get the type, as used in the union or variant mapping, that should be used to store the given data into the eet file. */
+ Eet_Descriptor_Type_Set_Callback type_set; /**< called when loading a mapped type with the given @p type used to describe the type in the descriptor */
+ Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to allocate memory for array (usually malloc()) */
+ Eet_Descriptor_Array_Free_Callback array_free; /**< how to free memory for array (usually free()) */
} func;
};
* @param func_hash_free The function to free an entire hash table.
* @return A new empty data descriptor.
*
- * This function creates a new data descriptore and returns a handle to the
+ * This function creates a new data descriptor 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.
*
*
* 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
+ * endian-independent serialised data chunks for transmission across a
* a network or more.
*
* The function pointers to the list and hash table functions are only
* @deprecated use eet_data_descriptor_stream_new() or
* eet_data_descriptor_file_new()
*/
-EINA_DEPRECATED EAPI Eet_Data_Descriptor * eet_data_descriptor_new(const char *name,
- int size,
- void *(*func_list_next)(void *l),
- void *(*func_list_append)(void *l, void *d),
- void *(*func_list_data)(void *l),
- void *(*func_list_free)(void *l),
- void (*func_hash_foreach)(void *h, int (*func)(void *h,
- const char *k,
- void *dt,
- void *fdt), void *fdt),
- void *(*func_hash_add)(void *h, const char *k, void *d),
- void (*func_hash_free)(void *h));
+EINA_DEPRECATED EAPI Eet_Data_Descriptor *
+eet_data_descriptor_new(const char *name,
+ int size,
+ Eet_Descriptor_List_Next_Callback func_list_next,
+ Eet_Descriptor_List_Append_Callback func_list_append,
+ Eet_Descriptor_List_Data_Callback func_list_data,
+ Eet_Descriptor_List_Free_Callback func_list_free,
+ Eet_Descriptor_Hash_Foreach_Callback func_hash_foreach,
+ Eet_Descriptor_Hash_Add_Callback func_hash_add,
+ Eet_Descriptor_Hash_Free_Callback func_hash_free);
/*
* FIXME:
*
* moving to this api from the old above. this will break things when the
* move happens - but be warned
*/
-EINA_DEPRECATED EAPI Eet_Data_Descriptor * eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc);
-EINA_DEPRECATED EAPI Eet_Data_Descriptor * eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc);
+EINA_DEPRECATED EAPI Eet_Data_Descriptor *
+ eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc);
+EINA_DEPRECATED EAPI Eet_Data_Descriptor *
+ eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc);
/**
- * This function creates a new data descriptore and returns a handle to the
+ * This function creates a new data descriptor 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.
- * @param eddc The data descriptor to free.
+ * @param eddc The class from where to create the data descriptor.
+ * @return A handle to the new data descriptor.
*
* 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.
+ * 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-independent serialised data chunks for transmission across a
+ * network or more.
*
- * This function specially ignore str_direct_alloc and str_direct_free. It
- * is usefull when the eet_data you are reading don't have a dictionnary
- * like network stream or ipc. It also mean that all string will be allocated
+ * This function specially ignores str_direct_alloc and str_direct_free. It
+ * is useful when the eet_data you are reading doesn't have a dictionary,
+ * like network stream or IPC. It also mean that all string will be allocated
* and duplicated in memory.
*
* @since 1.2.3
* @ingroup Eet_Data_Group
*/
-EAPI Eet_Data_Descriptor * eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc);
+EAPI Eet_Data_Descriptor *
+eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc);
/**
- * This function creates a new data descriptore and returns a handle to the
+ * This function creates a new data descriptor 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.
- * @param eddc The data descriptor to free.
+ * @param eddc The class from where to create the data descriptor.
+ * @return A handle to the new data descriptor.
*
* 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
+ * 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-independent serialised data chunks for transmission across a
* a network or more.
*
- * This function use str_direct_alloc and str_direct_free. It is
- * usefull when the eet_data you are reading come from a file and
- * have a dictionnary. This will reduce memory use, improve the
- * possibility for the OS to page this string out. But be carrefull
- * all EET_T_STRING are pointer to a mmapped area and it will point
- * to nowhere if you close the file. So as long as you use this
- * strings, you need to have the Eet_File open.
+ * This function uses str_direct_alloc and str_direct_free. It is
+ * useful when the eet_data you are reading come from a file and
+ * have a dictionary. This will reduce memory use and improve the
+ * possibility for the OS to page this string out.
+ * However, the load speed and memory saving comes with some drawbacks to keep
+ * in mind. If you never modify the contents of the structures loaded from
+ * the file, all you need to remember is that closing the eet file will make
+ * the strings go away. On the other hand, should you need to free a string,
+ * before doing so you have to verify that it's not part of the eet dictionary.
+ * You can do this in the following way, assuming @p ef is a valid Eet_File
+ * and @p str is a string loaded from said file.
+ *
+ * @code
+ * void eet_string_free(Eet_File *ef, const char *str)
+ * {
+ * Eet_Dictionary *dict = eet_dictionary_get(ef);
+ * if (dict && eet_dictionary_string_check(dict, str))
+ * {
+ * // The file contains a dictionary and the given string is a part of
+ * // of it, so we can't free it, just return.
+ * return;
+ * }
+ * // We assume eina_stringshare was used on the descriptor
+ * eina_stringshare_del(str);
+ * }
+ * @endcode
*
* @since 1.2.3
* @ingroup Eet_Data_Group
*/
-EAPI Eet_Data_Descriptor * eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc);
+EAPI Eet_Data_Descriptor *
+eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc);
/**
- * This function is an helper that set all the parameter of an
+ * This function is an helper that set all the parameters of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type
* with a stream.
* @param eddc The Eet_Data_Descriptor_Class you want to set.
+ * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
* @param name The name of the structure described by this class.
* @param size The size of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong
* parameter).
*
+ * @note Unless there's a very specific reason to use this function directly,
+ * the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
+ *
* @since 1.2.3
* @ingroup Eet_Data_Group
*/
-EAPI Eina_Bool eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
- unsigned int eddc_size,
- const char *name,
- int size);
+EAPI Eina_Bool
+eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
+ unsigned int eddc_size,
+ const char *name,
+ int size);
/**
* This macro is an helper that set all the parameter of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type
* with stream.
- * @param Clas The Eet_Data_Descriptor_Class you want to set.
- * @param Type The type of the structure described by this class.
+ * @param clas The Eet_Data_Descriptor_Class you want to set.
+ * @param type The type of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong
* parameter).
*
+ * @see eet_data_descriptor_stream_new
* @since 1.2.3
* @ingroup Eet_Data_Group
*/
-#define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type)\
- (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
+#define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
+ (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
/**
* This function is an helper that set all the parameter of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type
* with a file.
* @param eddc The Eet_Data_Descriptor_Class you want to set.
+ * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
* @param name The name of the structure described by this class.
* @param size The size of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong
* parameter).
*
+ * @note Unless there's a very specific reason to use this function directly,
+ * the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
+ *
* @since 1.2.3
* @ingroup Eet_Data_Group
*/
-EAPI Eina_Bool eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
- unsigned int eddc_size,
- const char *name,
- int size);
+EAPI Eina_Bool
+eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
+ unsigned int eddc_size,
+ const char *name,
+ int size);
/**
* This macro is an helper that set all the parameter of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type
* with file.
- * @param Clas The Eet_Data_Descriptor_Class you want to set.
- * @param Type The type of the structure described by this class.
+ * @param clas The Eet_Data_Descriptor_Class you want to set.
+ * @param type The type of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong
* parameter).
*
+ * @see eet_data_descriptor_file_new
* @since 1.2.3
* @ingroup Eet_Data_Group
*/
-#define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type)\
+#define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
(eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
/**
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI void eet_data_descriptor_free(Eet_Data_Descriptor *edd);
+EAPI void
+eet_data_descriptor_free(Eet_Data_Descriptor *edd);
/**
* This function is an internal used by macros.
* #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a
* group, list or hash.
* @param group_type If element type is #EET_T_UNKNOW, then the @p
- * group_type will speficy if it is a list (#EET_G_LIST),
+ * group_type will specify if it is a list (#EET_G_LIST),
* array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then
* the member is a subtype (pointer to another type defined by
* another #Eet_Data_Descriptor).
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI void eet_data_descriptor_element_add(Eet_Data_Descriptor *edd,
- const char *name,
- int type,
- int group_type,
- int offset,
- /* int count_offset, */
- int count,
- const char *counter_name,
- Eet_Data_Descriptor *subtype);
+EAPI void
+eet_data_descriptor_element_add(Eet_Data_Descriptor *edd,
+ const char *name,
+ int type,
+ int group_type,
+ int offset,
+ /* int count_offset, */
+ int count,
+ const char *counter_name,
+ Eet_Data_Descriptor *subtype);
/**
* Read a data structure from an eet file and decodes it.
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI void * eet_data_read(Eet_File *ef,
- Eet_Data_Descriptor *edd,
- const char *name);
+EAPI void *
+eet_data_read(Eet_File *ef,
+ Eet_Data_Descriptor *edd,
+ const char *name);
/**
* Write a data structure from memory and store in an eet file.
* @param ef The eet file handle to write to.
* @param edd The data descriptor to use when encoding.
* @param name The key to store the data under in the eet file.
- * @param data A pointer to the data structure to ssave and encode.
+ * @param data A pointer to the data structure to save and encode.
* @param compress Compression flags for storage.
* @return bytes written on successful write, 0 on failure.
*
* This function is the reverse of eet_data_read(), saving a data structure
- * to an eet file.
+ * to an eet file. The file must have been opening in write mode and the data
+ * will be kept in memory until the file is either closed or eet_sync() is
+ * called to flush any unwritten changes.
*
* @see eet_data_write_cipher()
*
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI int eet_data_write(Eet_File *ef,
- Eet_Data_Descriptor *edd,
- const char *name,
- const void *data,
- int compress);
+EAPI int
+eet_data_write(Eet_File *ef,
+ Eet_Data_Descriptor *edd,
+ const char *name,
+ const void *data,
+ int compress);
+
+typedef void (*Eet_Dump_Callback)(void *data, const char *str);
/**
* Dump an eet encoded data structure into ascii text
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI int eet_data_text_dump(const void *data_in,
- int size_in,
- void (*dumpfunc)(void *data, const char *str),
- void *dumpdata);
+EAPI int
+eet_data_text_dump(const void *data_in,
+ int size_in,
+ Eet_Dump_Callback dumpfunc,
+ void *dumpdata);
/**
* Take an ascii encoding from eet_data_text_dump() and re-encode in binary.
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI void * eet_data_text_undump(const char *text,
- int textlen,
- int *size_ret);
+EAPI void *
+eet_data_text_undump(const char *text,
+ int textlen,
+ int *size_ret);
/**
* Dump an eet encoded data structure from an eet file into ascii text
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI int eet_data_dump(Eet_File *ef,
- const char *name,
- void (*dumpfunc)(void *data, const char *str),
- void *dumpdata);
+EAPI int
+eet_data_dump(Eet_File *ef,
+ const char *name,
+ Eet_Dump_Callback dumpfunc,
+ void *dumpdata);
/**
* Take an ascii encoding from eet_data_dump() and re-encode in binary.
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI int eet_data_undump(Eet_File *ef,
- const char *name,
- const char *text,
- int textlen,
- int compress);
+EAPI int
+eet_data_undump(Eet_File *ef,
+ const char *name,
+ const char *text,
+ int textlen,
+ int compress);
/**
- * Decode a data structure from an arbitary location in memory.
+ * Decode a data structure from an arbitrary location in memory.
* @param edd The data descriptor to use when decoding.
* @param data_in The pointer to the data to decode into a struct.
* @param size_in The size of the data pointed to in bytes.
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI void * eet_data_descriptor_decode(Eet_Data_Descriptor *edd,
- const void *data_in,
- int size_in);
+EAPI void *
+eet_data_descriptor_decode(Eet_Data_Descriptor *edd,
+ const void *data_in,
+ int size_in);
/**
* Encode a dsata struct to memory and return that encoded data.
* 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.
+ * without having to worry about memory space, machine type, endianness etc.
*
* The parameter @p edd must point to a valid data descriptor, and
* @p data_in must point to the right data structure to encode. If not, the
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-EAPI void * eet_data_descriptor_encode(Eet_Data_Descriptor *edd,
- const void *data_in,
- int *size_ret);
+EAPI void *
+eet_data_descriptor_encode(Eet_Data_Descriptor *edd,
+ const void *data_in,
+ int *size_ret);
/**
* Add a basic data element to a data descriptor.
* my_struct). The @p 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 @p member parameter is
- * the actual struct member itself (for eet_dictionary_string_check
- * example: values), and @p 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,
+ * the actual struct member itself (for example: values), and @p 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
* @ingroup Eet_Data_Group
*/
-#define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type)\
- do {\
- struct_type ___ett;\
- eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- 0, /* 0, */ NULL, NULL);\
- } while(0)
+#define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ 0, /* 0, */ NULL, NULL); \
+ } while(0)
/**
* Add a sub-element type to a data descriptor
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-#define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- 0, /* 0, */ NULL, subtype);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ 0, /* 0, */ NULL, subtype); \
+ } while (0)
/**
* Add a linked list type to a data descriptor
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-#define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- 0, /* 0, */ NULL, subtype);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ 0, /* 0, */ NULL, subtype); \
+ } while (0)
+
+/**
+ * Add a linked list of string to a data descriptor
+ * @param edd The data descriptor to add the type to.
+ * @param struct_type The type of the struct.
+ * @param name The string name to use to encode/decode this member
+ * (must be a constant global and never change).
+ * @param member The struct member itself to be encoded.
+ *
+ * This macro lets you easily add a linked list of char *. All the
+ * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
+ *
+ * @since 1.5.0
+ * @ingroup Eet_Data_Group
+ */
+#define EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_LIST, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ 0, /* 0, */ NULL, NULL); \
+ } while (0)
/**
* Add a hash type to a data descriptor
* parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
* @p subtype being the exception. This must be the data descriptor of the
* element that is in each member of the hash to be stored.
+ * The hash keys must be strings.
*
* @since 1.0.0
* @ingroup Eet_Data_Group
*/
-#define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- 0, /* 0, */ NULL, subtype);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ 0, /* 0, */ NULL, subtype); \
+ } while (0)
/**
* Add a hash of string to a data descriptor
* (must be a constant global and never change).
* @param member The struct member itself to be encoded.
*
- * This macro lets you easily add a hash of string. All the
- * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
+ * This macro lets you easily add a hash of string elements. All the
+ * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH().
*
* @since 1.3.4
* @ingroup Eet_Data_Group
*/
-#define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- 0, /* 0, */ NULL, NULL);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ 0, /* 0, */ NULL, NULL); \
+ } while (0)
+
+/**
+ * Add an array of basic data elements to a data descriptor.
+ * @param edd The data descriptor to add the type to.
+ * @param struct_type The type of the struct.
+ * @param name The string name to use to encode/decode this member
+ * (must be a constant global and never change).
+ * @param member The struct member itself to be encoded.
+ * @param type The type of the member to encode.
+ *
+ * This macro lets you easily add a fixed size array of basic data
+ * types. All the parameters are the same as for
+ * EET_DATA_DESCRIPTOR_ADD_BASIC().
+ * The array must be defined with a fixed size in the declaration of the
+ * struct containing it.
+ *
+ * @since 1.5.0
+ * @ingroup Eet_Data_Group
+ */
+#define EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member, type) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ sizeof(___ett.member) / \
+ sizeof(___ett.member[0]), \
+ NULL, NULL); \
+ } while(0)
+
+/**
+ * Add a variable array of basic data elements to a data descriptor.
+ * @param edd The data descriptor to add the type to.
+ * @param struct_type The type of the struct.
+ * @param name The string name to use to encode/decode this member
+ * (must be a constant global and never change).
+ * @param member The struct member itself to be encoded.
+ * @param type The type of the member to encode.
+ *
+ * This macro lets you easily add a variable size array of basic data
+ * types. All the parameters are the same as for
+ * EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have
+ * a struct member (of type EET_T_INT) called member_count (note the
+ * _count appended to the member) that holds the number of items in
+ * the array. This array will be allocated separately to the struct it
+ * is in.
+ *
+ * @since 1.6.0
+ * @ingroup Eet_Data_Group
+ */
+#define EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, member, type) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, type, EET_G_VAR_ARRAY, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ (char *)(& (___ett.member ## _count)) - \
+ (char *)(& (___ett)), \
+ NULL, \
+ NULL); \
+ } while(0)
/**
* Add a fixed size array type to a data descriptor
* types. All the parameters are the same as for
* EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
* exception. This must be the data descriptor of the element that
- * is in each member of the hash to be stored.
+ * is in each member of the array to be stored.
+ * The array must be defined with a fixed size in the declaration of the
+ * struct containing it.
*
* @since 1.0.2
* @ingroup Eet_Data_Group
*/
-#define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- /* 0, */ sizeof(___ett.member) /\
- sizeof(___ett.member[0]), NULL, subtype);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ /* 0, */ sizeof(___ett.member) / \
+ sizeof(___ett.member[0]), NULL, subtype); \
+ } while (0)
/**
* Add a variable size array type to a data descriptor
* @param member The struct member itself to be encoded.
* @param subtype The type of hash member to add.
*
- * This macro lets you easily add a fixed size array of other data
+ * This macro lets you easily add a variable size array of other data
* types. All the parameters are the same as for
* EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
* exception. This must be the data descriptor of the element that
- * is in each member of the hash to be stored.
+ * is in each member of the array to be stored. This assumes you have
+ * a struct member (of type EET_T_INT) called member_count (note the
+ * _count appended to the member) that holds the number of items in
+ * the array. This array will be allocated separately to the struct it
+ * is in.
*
* @since 1.0.2
* @ingroup Eet_Data_Group
*/
-#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd,\
- struct_type,\
- name,\
- member,\
- subtype)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd,\
- name,\
- EET_T_UNKNOW,\
- EET_G_VAR_ARRAY,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- (char *)(& (___ett.member ## _count)) -\
- (char *)(& (___ett)),\
- /* 0, */ NULL,\
- subtype);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, \
+ name, \
+ EET_T_UNKNOW, \
+ EET_G_VAR_ARRAY, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ (char *)(& (___ett.member ## _count)) - \
+ (char *)(& (___ett)), \
+ /* 0, */ NULL, \
+ subtype); \
+ } while (0)
+
+/**
+ * Add a variable size array type to a data descriptor
+ * @param edd The data descriptor to add the type to.
+ * @param struct_type The type of the struct.
+ * @param name The string name to use to encode/decode this member
+ * (must be a constant global and never change).
+ * @param member The struct member itself to be encoded.
+ *
+ * This macro lets you easily add a variable size array of strings. All
+ * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
+ *
+ * @since 1.4.0
+ * @ingroup Eet_Data_Group
+ */
+#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, \
+ name, \
+ EET_T_STRING, \
+ EET_G_VAR_ARRAY, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ (char *)(& (___ett.member ## _count)) - \
+ (char *)(& (___ett)), \
+ /* 0, */ NULL, \
+ NULL); \
+ } while (0)
/**
* Add an union type to a data descriptor
* @ingroup Eet_Data_Group
* @see Eet_Data_Descriptor_Class
*/
-#define EET_DATA_DESCRIPTOR_ADD_UNION(edd,\
- struct_type,\
- name,\
- member,\
- type_member,\
- unified_type)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- (char *)(& (___ett.type_member)) -\
- (char *)(& (___ett)),\
- NULL, unified_type);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ (char *)(& (___ett.type_member)) - \
+ (char *)(& (___ett)), \
+ NULL, unified_type); \
+ } while (0)
/**
* Add a automatically selectable type to a data descriptor
* @ingroup Eet_Data_Group
* @see Eet_Data_Descriptor_Class
*/
-#define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd,\
- struct_type,\
- name,\
- member,\
- type_member,\
- unified_type)\
- do {\
- struct_type ___ett;\
-\
- eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT,\
- (char *)(& (___ett.member)) -\
- (char *)(& (___ett)),\
- (char *)(& (___ett.type_member)) -\
- (char *)(& (___ett)),\
- NULL, unified_type);\
- } while (0)
+#define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type) \
+ do { \
+ struct_type ___ett; \
+ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT, \
+ (char *)(& (___ett.member)) - \
+ (char *)(& (___ett)), \
+ (char *)(& (___ett.type_member)) - \
+ (char *)(& (___ett)), \
+ NULL, unified_type); \
+ } while (0)
/**
* Add a mapping to a data descriptor that will be used by union, variant or inherited type
* @ingroup Eet_Data_Group
* @see Eet_Data_Descriptor_Class
*/
-#define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype)\
- eet_data_descriptor_element_add(unified_type,\
- name,\
- EET_T_UNKNOW,\
- EET_G_UNKNOWN,\
- 0,\
- 0,\
- NULL,\
- subtype)
+#define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \
+ eet_data_descriptor_element_add(unified_type, \
+ name, \
+ EET_T_UNKNOW, \
+ EET_G_UNKNOWN, \
+ 0, \
+ 0, \
+ NULL, \
+ subtype)
/**
* @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI void * eet_data_read_cipher(Eet_File *ef,
- Eet_Data_Descriptor *edd,
- const char *name,
- const char *cipher_key);
+EAPI void *
+eet_data_read_cipher(Eet_File *ef,
+ Eet_Data_Descriptor *edd,
+ const char *name,
+ const char *cipher_key);
+
+/**
+ * Read a data structure from an eet extended attribute and decodes it using a cipher.
+ * @param filename The file to extract the extended attribute from.
+ * @param attribute The attribute to get the data from.
+ * @param edd The data descriptor handle to use when decoding.
+ * @param cipher_key The key to use as cipher.
+ * @return A pointer to the decoded data structure.
+ *
+ * This function decodes a data structure stored in an eet extended attribute,
+ * returning a pointer to it if it decoded successfully, or NULL on failure.
+ * 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, from a chunk of memory or from an extended attribute
+ * is as simple as a single function call.
+ *
+ * @since 1.5.0
+ * @ingroup Eet_Data_Cipher_Group
+ */
+EAPI void *
+eet_data_xattr_cipher_get(const char *filename,
+ const char *attribute,
+ Eet_Data_Descriptor *edd,
+ const char *cipher_key);
/**
* Write a data structure from memory and store in an eet file
* @param edd The data descriptor to use when encoding.
* @param name The key to store the data under in the eet file.
* @param cipher_key The key to use as cipher.
- * @param data A pointer to the data structure to ssave and encode.
+ * @param data A pointer to the data structure to save and encode.
* @param compress Compression flags for storage.
* @return bytes written on successful write, 0 on failure.
*
- * This function is the reverse of eet_data_read(), saving a data structure
+ * This function is the reverse of eet_data_read_cipher(), saving a data structure
* to an eet file.
*
- * @see eet_data_write_cipher()
- *
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI int eet_data_write_cipher(Eet_File *ef,
- Eet_Data_Descriptor *edd,
- const char *name,
- const char *cipher_key,
- const void *data,
- int compress);
+EAPI int
+eet_data_write_cipher(Eet_File *ef,
+ Eet_Data_Descriptor *edd,
+ const char *name,
+ const char *cipher_key,
+ const void *data,
+ int compress);
+
+/**
+ * Write a data structure from memory and store in an eet extended attribute
+ * using a cipher.
+ * @param filename The file to write the extended attribute to.
+ * @param attribute The attribute to store the data to.
+ * @param edd The data descriptor to use when encoding.
+ * @param cipher_key The key to use as cipher.
+ * @param data A pointer to the data structure to save and encode.
+ * @param flags The policy to use when setting the data.
+ * @return EINA_TRUE on success, EINA_FALSE on failure.
+ *
+ * This function is the reverse of eet_data_xattr_cipher_get(), saving a data structure
+ * to an eet extended attribute.
+ *
+ * @since 1.5.0
+ * @ingroup Eet_Data_Cipher_Group
+ */
+EAPI Eina_Bool
+eet_data_xattr_cipher_set(const char *filename,
+ const char *attribute,
+ Eet_Data_Descriptor *edd,
+ const char *cipher_key,
+ const void *data,
+ Eina_Xattr_Flags flags);
/**
* Dump an eet encoded data structure into ascii text using a cipher.
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI int eet_data_text_dump_cipher(const void *data_in,
- const char *cipher_key,
- int size_in,
- void (*dumpfunc)(void *data, const char *str),
- void *dumpdata);
+EAPI int
+eet_data_text_dump_cipher(const void *data_in,
+ const char *cipher_key,
+ int size_in,
+ Eet_Dump_Callback dumpfunc,
+ void *dumpdata);
/**
* Take an ascii encoding from eet_data_text_dump() and re-encode
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI void * eet_data_text_undump_cipher(const char *text,
- const char *cipher_key,
- int textlen,
- int *size_ret);
+EAPI void *
+eet_data_text_undump_cipher(const char *text,
+ const char *cipher_key,
+ int textlen,
+ int *size_ret);
/**
* Dump an eet encoded data structure from an eet file into ascii
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI int eet_data_dump_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key,
- void (*dumpfunc)(void *data, const char *str),
- void *dumpdata);
+EAPI int
+eet_data_dump_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key,
+ Eet_Dump_Callback dumpfunc,
+ void *dumpdata);
/**
* Take an ascii encoding from eet_data_dump() and re-encode in
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI int eet_data_undump_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key,
- const char *text,
- int textlen,
- int compress);
+EAPI int
+eet_data_undump_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key,
+ const char *text,
+ int textlen,
+ int compress);
/**
- * Decode a data structure from an arbitary location in memory
+ * Decode a data structure from an arbitrary location in memory
* using a cipher.
* @param edd The data descriptor to use when decoding.
* @param data_in The pointer to the data to decode into a struct.
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI void * eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd,
- const void *data_in,
- const char *cipher_key,
- int size_in);
+EAPI void *
+eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd,
+ const void *data_in,
+ const char *cipher_key,
+ int size_in);
/**
* Encode a data struct to memory and return that encoded data
* @since 1.0.0
* @ingroup Eet_Data_Cipher_Group
*/
-EAPI void * eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd,
- const void *data_in,
- const char *cipher_key,
- int *size_ret);
+EAPI void *
+eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd,
+ const void *data_in,
+ const char *cipher_key,
+ int *size_ret);
/**
* @defgroup Eet_Node_Group Low-level Serialization Structures.
* @typedef Eet_Node
* Opaque handle to manage serialization node.
*/
-typedef struct _Eet_Node Eet_Node;
+typedef struct _Eet_Node Eet_Node;
/**
* @typedef Eet_Node_Data
* Contains an union that can fit any kind of node.
*/
-typedef struct _Eet_Node_Data Eet_Node_Data;
+typedef struct _Eet_Node_Data Eet_Node_Data;
/**
* @struct _Eet_Node_Data
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_char_new(const char *name,
- char c);
+EAPI Eet_Node *
+eet_node_char_new(const char *name,
+ char c);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_short_new(const char *name,
- short s);
+EAPI Eet_Node *
+eet_node_short_new(const char *name,
+ short s);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_int_new(const char *name,
- int i);
+EAPI Eet_Node *
+eet_node_int_new(const char *name,
+ int i);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_long_long_new(const char *name,
- long long l);
+EAPI Eet_Node *
+eet_node_long_long_new(const char *name,
+ long long l);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_float_new(const char *name,
- float f);
+EAPI Eet_Node *
+eet_node_float_new(const char *name,
+ float f);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_double_new(const char *name,
- double d);
+EAPI Eet_Node *
+eet_node_double_new(const char *name,
+ double d);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_unsigned_char_new(const char *name,
- unsigned char uc);
+EAPI Eet_Node *
+eet_node_unsigned_char_new(const char *name,
+ unsigned char uc);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_unsigned_short_new(const char *name,
- unsigned short us);
+EAPI Eet_Node *
+eet_node_unsigned_short_new(const char *name,
+ unsigned short us);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_unsigned_int_new(const char *name,
- unsigned int ui);
+EAPI Eet_Node *
+eet_node_unsigned_int_new(const char *name,
+ unsigned int ui);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_unsigned_long_long_new(const char *name,
- unsigned long long l);
+EAPI Eet_Node *
+eet_node_unsigned_long_long_new(const char *name,
+ unsigned long long l);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_string_new(const char *name,
- const char *str);
+EAPI Eet_Node *
+eet_node_string_new(const char *name,
+ const char *str);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_inlined_string_new(const char *name,
- const char *str);
+EAPI Eet_Node *
+eet_node_inlined_string_new(const char *name,
+ const char *str);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_null_new(const char *name);
+EAPI Eet_Node *
+eet_node_null_new(const char *name);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_list_new(const char *name,
- Eina_List *nodes);
+EAPI Eet_Node *
+eet_node_list_new(const char *name,
+ Eina_List *nodes);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_array_new(const char *name,
- int count,
- Eina_List *nodes);
+EAPI Eet_Node *
+eet_node_array_new(const char *name,
+ int count,
+ Eina_List *nodes);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_var_array_new(const char *name,
- Eina_List *nodes);
+EAPI Eet_Node *
+eet_node_var_array_new(const char *name,
+ Eina_List *nodes);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_hash_new(const char *name,
- const char *key,
- Eet_Node *node);
+EAPI Eet_Node *
+eet_node_hash_new(const char *name,
+ const char *key,
+ Eet_Node *node);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_struct_new(const char *name,
- Eina_List *nodes);
+EAPI Eet_Node *
+eet_node_struct_new(const char *name,
+ Eina_List *nodes);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_node_struct_child_new(const char *parent,
- Eet_Node *child);
+EAPI Eet_Node *
+eet_node_struct_child_new(const char *parent,
+ Eet_Node *child);
+
+/**
+ * @brief Get a node's child nodes
+ * @param node The node
+ * @return The first child node which contains a pointer to the
+ * next child node and the parent.
+ * @since 1.5
+ */
+EAPI Eet_Node *
+eet_node_children_get(Eet_Node *node);
+
+/**
+ * @brief Get the next node in a list of nodes
+ * @param node The node
+ * @return A node which contains a pointer to the
+ * next child node and the parent.
+ * @since 1.5
+ */
+EAPI Eet_Node *
+eet_node_next_get(Eet_Node *node);
+
+/**
+ * @brief Get the parent node of a node
+ * @param node The node
+ * @return The parent node of @p node
+ * @since 1.5
+ */
+EAPI Eet_Node *
+eet_node_parent_get(Eet_Node *node);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI void eet_node_list_append(Eet_Node *parent,
- const char *name,
- Eet_Node *child);
+EAPI void
+eet_node_list_append(Eet_Node *parent,
+ const char *name,
+ Eet_Node *child);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI void eet_node_struct_append(Eet_Node *parent,
- const char *name,
- Eet_Node *child);
+EAPI void
+eet_node_struct_append(Eet_Node *parent,
+ const char *name,
+ Eet_Node *child);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI void eet_node_hash_add(Eet_Node *parent,
- const char *name,
- const char *key,
- Eet_Node *child);
+EAPI void
+eet_node_hash_add(Eet_Node *parent,
+ const char *name,
+ const char *key,
+ Eet_Node *child);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI void eet_node_dump(Eet_Node *n,
- int dumplevel,
- void (*dumpfunc)(void *data, const char *str),
- void *dumpdata);
+EAPI void
+eet_node_dump(Eet_Node *n,
+ int dumplevel,
+ Eet_Dump_Callback dumpfunc,
+ void *dumpdata);
+
+/**
+ * @brief Return the type of a node
+ * @param node The node
+ * @return The node's type (EET_T_$TYPE)
+ * @since 1.5
+ */
+EAPI int
+eet_node_type_get(Eet_Node *node);
+
+/**
+ * @brief Return the node's data
+ * @param node The node
+ * @return The data contained in the node
+ * @since 1.5
+ */
+EAPI Eet_Node_Data *
+eet_node_value_get(Eet_Node *node);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI void eet_node_del(Eet_Node *n);
+EAPI void
+eet_node_del(Eet_Node *n);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI void * eet_data_node_encode_cipher(Eet_Node *node,
- const char *cipher_key,
- int *size_ret);
+EAPI void *
+eet_data_node_encode_cipher(Eet_Node *node,
+ const char *cipher_key,
+ int *size_ret);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_data_node_decode_cipher(const void *data_in,
- const char *cipher_key,
- int size_in);
+EAPI Eet_Node *
+eet_data_node_decode_cipher(const void *data_in,
+ const char *cipher_key,
+ int size_in);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI Eet_Node * eet_data_node_read_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key);
+EAPI Eet_Node *
+eet_data_node_read_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key);
/**
* TODO FIX ME
* @ingroup Eet_Node_Group
*/
-EAPI int eet_data_node_write_cipher(Eet_File *ef,
- const char *name,
- const char *cipher_key,
- Eet_Node *node,
- int compress);
+EAPI int
+eet_data_node_write_cipher(Eet_File *ef,
+ const char *name,
+ const char *cipher_key,
+ Eet_Node *node,
+ int compress);
/* EXPERIMENTAL: THIS API MAY CHANGE IN THE FUTURE, USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING. */
* @typedef Eet_Node_Walk
* Describes how to walk trees of #Eet_Node.
*/
-typedef struct _Eet_Node_Walk Eet_Node_Walk;
+typedef struct _Eet_Node_Walk Eet_Node_Walk;
+
+typedef void * (*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void *user_data);
+typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char *name, void *child, void *user_data);
+typedef void * (*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const char *name, int count, void *user_data);
+typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void *child, void *user_data);
+typedef void * (*Eet_Node_Walk_List_Callback)(const char *name, void *user_data);
+typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, void *user_data);
+typedef void * (*Eet_Node_Walk_Hash_Callback)(void *parent, const char *name, const char *key, void *value, void *user_data);
+typedef void * (*Eet_Node_Walk_Simple_Callback)(int type, Eet_Node_Data *data, void *user_data);
/**
* @struct _Eet_Node_Walk
*/
struct _Eet_Node_Walk
{
- void *(*struct_alloc)(const char *type, void *user_data);
- void (*struct_add)(void *parent, const char *name, void *child, void *user_data);
- void *(*array)(Eina_Bool variable, const char *name, int count, void *user_data);
- void (*insert)(void *array, int index, void *child, void *user_data);
- void *(*list)(const char *name, void *user_data);
- void (*append)(void *list, void *child, void *user_data);
- void *(*hash)(void *parent, const char *name, const char *key, void *value, void *user_data);
- void *(*simple)(int type, Eet_Node_Data *data, void *user_data);
+ Eet_Node_Walk_Struct_Alloc_Callback struct_alloc;
+ Eet_Node_Walk_Struct_Add_Callback struct_add;
+ Eet_Node_Walk_Array_Callback array;
+ Eet_Node_Walk_Insert_Callback insert;
+ Eet_Node_Walk_List_Callback list;
+ Eet_Node_Walk_Append_Callback append;
+ Eet_Node_Walk_Hash_Callback hash;
+ Eet_Node_Walk_Simple_Callback simple;
};
-EAPI void * eet_node_walk(void *parent,
- const char *name,
- Eet_Node *root,
- Eet_Node_Walk *cb,
- void *user_data);
+EAPI void *
+eet_node_walk(void *parent,
+ const char *name,
+ Eet_Node *root,
+ Eet_Node_Walk *cb,
+ void *user_data);
/*******/
*
* @ingroup Eet_Connection_Group
*/
-typedef struct _Eet_Connection Eet_Connection;
+typedef struct _Eet_Connection Eet_Connection;
/**
* @typedef Eet_Read_Cb
- * Called back when an @ref Eet_Data_Group has been received completly and could be used.
+ * Called back when an @ref Eet_Data_Group has been received completely and could be used.
*
* @ingroup Eet_Connection_Group
*/
-typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *user_data);
+typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *user_data);
/**
* @typedef Eet_Write_Cb
*
* @ingroup Eet_Connection_Group
*/
-typedef Eina_Bool Eet_Write_Cb (const void *data, size_t size, void *user_data);
+typedef Eina_Bool Eet_Write_Cb (const void *data, size_t size, void *user_data);
/**
* Instanciate a new connection to track.
- * @oaram eet_read_cb Function to call when one Eet_Data packet has been fully assemble.
+ * @param eet_read_cb Function to call when one Eet_Data packet has been fully assemble.
* @param eet_write_cb Function to call when one Eet_Data packet is ready to be send over the wire.
* @param user_data Pointer provided to both functions to be used as a context handler.
* @return NULL on failure, or a valid Eet_Connection handler.
* @since 1.2.4
* @ingroup Eet_Connection_Group
*/
-EAPI Eet_Connection * eet_connection_new(Eet_Read_Cb *eet_read_cb,
- Eet_Write_Cb *eet_write_cb,
- const void *user_data);
+EAPI Eet_Connection *
+eet_connection_new(Eet_Read_Cb *eet_read_cb,
+ Eet_Write_Cb *eet_write_cb,
+ const void *user_data);
/**
* Process a raw packet received over the link
- * @oaram conn Connection handler to track.
+ * @param conn Connection handler to track.
* @param data Raw data packet.
* @param size The size of that packet.
* @return 0 on complete success, any other value indicate where in the stream it got wrong (It could be before that packet).
* @since 1.2.4
* @ingroup Eet_Connection_Group
*/
-EAPI int eet_connection_received(Eet_Connection *conn,
- const void *data,
- size_t size);
+EAPI int
+eet_connection_received(Eet_Connection *conn,
+ const void *data,
+ size_t size);
/**
* Convert a complex structure and prepare it to be send.
- * @oaram conn Connection handler to track.
+ * @param conn Connection handler to track.
* @param edd The data descriptor to use when encoding.
* @param data_in The pointer to the struct to encode into data.
* @param cipher_key The key to use as cipher.
* @since 1.2.4
* @ingroup Eet_Connection_Group
*/
-EAPI Eina_Bool eet_connection_send(Eet_Connection *conn,
- Eet_Data_Descriptor *edd,
- const void *data_in,
- const char *cipher_key);
+EAPI Eina_Bool
+eet_connection_send(Eet_Connection *conn,
+ Eet_Data_Descriptor *edd,
+ const void *data_in,
+ const char *cipher_key);
/**
* Convert a Eet_Node tree and prepare it to be send.
- * @oaram conn Connection handler to track.
+ * @param conn Connection handler to track.
* @param node The data tree to use when encoding.
* @param cipher_key The key to use as cipher.
* @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
* @since 1.2.4
* @ingroup Eet_Connection_Group
*/
-EAPI Eina_Bool eet_connection_node_send(Eet_Connection *conn,
- Eet_Node *node,
- const char *cipher_key);
+EAPI Eina_Bool
+eet_connection_node_send(Eet_Connection *conn,
+ Eet_Node *node,
+ const char *cipher_key);
/**
* Close a connection and lost its track.
- * @oaram conn Connection handler to close.
+ * @param conn Connection handler to close.
* @param on_going Signal if a partial packet wasn't completed.
* @return the user_data passed to both callback.
*
* @since 1.2.4
* @ingroup Eet_Connection_Group
*/
-EAPI void * eet_connection_close(Eet_Connection *conn,
- Eina_Bool *on_going);
+EAPI void *
+eet_connection_close(Eet_Connection *conn,
+ Eina_Bool *on_going);
/***************************************************************************/