2 @brief Eet Data Handling Library Public API Calls
4 These routines are used for Eet Library interaction
10 @section toc Table of Contents
12 @li @ref eet_main_intro
13 @li @ref eet_main_compiling
14 @li @ref eet_main_next_steps
15 @li @ref eet_main_intro_example
17 @section eet_main_intro Introduction
19 It is a tiny library designed to write an arbitrary set of chunks of data
20 to a file and optionally compress each chunk (very much like a zip file)
21 and allow fast random-access reading of the file later on. It does not
22 do zip as a zip itself has more complexity than is needed, and it was much
23 simpler to implement this once here.
25 Eet is extremely fast, small and simple. Eet files can be very small and
26 highly compressed, making them very optimal for just sending across the
27 internet without having to archive, compress or decompress and install them.
28 They allow for lightning-fast random-access reads once created, making them
29 perfect for storing data that is written once (or rarely) and read many
30 times, but the program does not want to have to read it all in at once.
32 It also can encode and decode data structures in memory, as well as image
33 data for saving to Eet files or sending across the network to other
34 machines, or just writing to arbitrary files on the system. All data is
35 encoded in a platform independent way and can be written and read by any
38 @section eet_main_compiling How to compile
40 Eet is a library your application links to. The procedure for this is very
41 simple. You simply have to compile your application with the appropriate
42 compiler flags that the @p pkg-config script outputs. For example:
44 Compiling C or C++ files into object files:
47 gcc -c -o main.o main.c `pkg-config --cflags eet`
50 Linking object files into a binary executable:
53 gcc -o my_application main.o `pkg-config --libs eet`
58 @section eet_main_next_steps Next Steps
60 After you understood what Eet is and installed it in your system
61 you should proceed understanding the programming interface. We'd
62 recommend you to take a while to learn @ref Eina as it is very
63 convenient and optimized, and Eet provides integration with it.
67 @li @ref Eet_File_Group to know the basics to open and save files.
68 @li @ref Eet_Data_Group to know the convenient way to serialize and
69 parse your data structures automatically. Just create your
70 descriptors and let Eet do the work for you.
72 @section eet_main_intro_example Introductory Examples
74 Here is a simple example on how to use Eet to save a series of strings to a
75 file and load them again. The advantage of using Eet over just
77 fscanf() is that not only can these entries be strings, they need no special
78 parsing to handle delimiter characters or escaping, they can be binary data,
79 image data, data structures containing integers, strings, other data
80 structures, linked lists and much more, without the programmer having to
81 worry about parsing, and best of all, Eet is very fast.
83 This is just a very simple example that doesn't show all of the capabilities
84 of Eet, but it serves to illustrate its simplicity.
88 More examples can be found at @ref eet_examples.
90 @todo Document data format for images and data structures.
100 #include <Efl_Config.h>
104 #endif /* ifdef EAPI */
107 # ifdef EFL_EET_BUILD
109 # define EAPI __declspec(dllexport)
110 # else /* ifdef DLL_EXPORT */
112 # endif /* ! DLL_EXPORT */
113 # else /* ifdef EFL_EET_BUILD */
114 # define EAPI __declspec(dllimport)
115 # endif /* ! EFL_EET_BUILD */
116 #else /* ifdef _WIN32 */
119 # define EAPI __attribute__ ((visibility("default")))
120 # else /* if __GNUC__ >= 4 */
122 # endif /* if __GNUC__ >= 4 */
123 # else /* ifdef __GNUC__ */
125 # endif /* ifdef __GNUC__ */
126 #endif /* ! _WIN32 */
130 #endif /* ifdef __cplusplus */
134 * @brief The file that provides the eet functions.
136 * This header provides the Eet management functions.
140 #define EET_VERSION_MAJOR EFL_VERSION_MAJOR
141 #define EET_VERSION_MINOR EFL_VERSION_MINOR
143 * @typedef Eet_Version
145 * This is the Eet version information structure that can be used at
146 * runtime to detect which version of eet is being used and adapt
147 * appropriately as follows for example:
150 * #if defined(EET_VERSION_MAJOR) && (EET_VERSION_MAJOR >= 1) && defined(EET_VERSION_MINOR) && (EET_VERSION_MINOR > 2)
151 * printf("Eet version: %i.%i.%i\n",
152 * eet_version->major,
153 * eet_version->minor,
154 * eet_version->micro);
155 * if (eet_version->revision > 0)
157 * printf(" Built from SVN revision # %i\n", eet_version->revision);
162 * Note the \#if check can be dropped if your program refuses to compile or
163 * work with an Eet version less than 1.3.0.
165 typedef struct _Eet_Version
167 int major; /** < major (binary or source incompatible changes) */
168 int minor; /** < minor (new features, bugfixes, major improvements version) */
169 int micro; /** < micro (bugfix, internal improvements, no new features version) */
170 int revision; /** < svn revision (0 if a proper release or the svn revision number Eet is built from) */
173 EAPI extern Eet_Version *eet_version;
176 * @defgroup Eet_Group Top level functions
178 * Functions that affect Eet as a whole.
185 * All the error identifiers known by Eet.
187 typedef enum _Eet_Error
189 EET_ERROR_NONE, /**< No error, it's all fine! */
190 EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */
191 EET_ERROR_EMPTY, /**< There was nothing to do */
192 EET_ERROR_NOT_WRITABLE, /**< Could not write to file or file is #EET_FILE_MODE_READ */
193 EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */
194 EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */
195 EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it is too big */
196 EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write due a generic Input/Output error */
197 EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of space */
198 EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */
199 EET_ERROR_MMAP_FAILED, /**< Could not mmap file */
200 EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */
201 EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */
202 EET_ERROR_INVALID_SIGNATURE, /**< Signature is invalid */
203 EET_ERROR_NOT_SIGNED, /**< File or contents are not signed */
204 EET_ERROR_NOT_IMPLEMENTED, /**< Function is not implemented */
205 EET_ERROR_PRNG_NOT_SEEDED, /**< Could not introduce random seed */
206 EET_ERROR_ENCRYPT_FAILED, /**< Could not encrypt contents */
207 EET_ERROR_DECRYPT_FAILED /**< Could not decrypt contents */
208 } Eet_Error; /**< Eet error identifiers */
215 * @defgroup Eet_Compression Eet Compression Levels
217 * Compression modes/levels supported by Eet.
223 * @enum _Eet_Compression
224 * All the compression modes known by Eet.
227 typedef enum _Eet_Compression
229 EET_COMPRESSION_NONE = 0, /**< No compression at all @since 1.7 */
230 EET_COMPRESSION_DEFAULT = 1, /**< Default compression (Zlib) @since 1.7 */
231 EET_COMPRESSION_LOW = 2, /**< Fast but minimal compression (Zlib) @since 1.7 */
232 EET_COMPRESSION_MED = 6, /**< Medium compression level (Zlib) @since 1.7 */
233 EET_COMPRESSION_HI = 9, /**< Slow but high compression level (Zlib) @since 1.7 */
234 EET_COMPRESSION_VERYFAST = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */
235 EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST) (LZ4) @since 1.7 */
237 EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Don't use it @since 1.7 */
238 EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Don't use it @since 1.7 */
239 EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Don't use it @since 1.7 */
240 EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Don't use it @since 1.7 */
241 EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Don't use it @since 1.7 */
242 } Eet_Compression; /**< Eet compression modes @since 1.7 */
249 * Initialize the EET library.
251 * The first time this function is called, it will perform all the internal
252 * initialization required for the library to function properly and increment
253 * the initialization counter. Any subsequent call only increment this counter
254 * and return its new value, so it's safe to call this function more than once.
256 * @return The new init count. Will be 0 if initialization failed.
265 * Shut down the EET library.
267 * If eet_init() was called more than once for the running application,
268 * eet_shutdown() will decrement the initialization counter and return its
269 * new value, without doing anything else. When the counter reaches 0, all
270 * of the internal elements will be shutdown and any memory used freed.
272 * @return The new init count.
283 * For a faster access to previously accessed data, Eet keeps an internal
284 * cache of files. These files will be freed automatically only when
285 * they are unused and the cache gets full, in order based on the last time
287 * On systems with little memory this may present an unnecessary constraint,
288 * so eet_clearcache() is available for users to reclaim the memory used by
289 * files that are no longer needed. Those that were open using
290 * ::EET_FILE_MODE_WRITE or ::EET_FILE_MODE_READ_WRITE and have modifications,
291 * will be written down to disk before flushing them from memory.
297 eet_clearcache(void);
300 * @defgroup Eet_File_Group Eet File Main Functions
303 * Functions to create, destroy and do basic manipulation of
306 * This sections explains how to use the most basic Eet functions, which
307 * are used to work with eet files, read data from them, store it back in or
308 * take a look at what entries it contains, without making use of the
309 * serialization capabilities explained in @ref Eet_Data_Group.
311 * The following example will serve as an introduction to most, if not all,
312 * of these functions.
314 * If you are only using Eet, this is the only header you need to include.
315 * @dontinclude eet-file.c
318 * Now let's create ourselves an eet file to play with. The following function
319 * shows step by step how to open a file and write some data in it.
320 * First, we define our file handler and some other things we'll put in it.
326 * We open a new file in write mode, and if it fails, we just return, since
327 * there's not much more we can do about it..
330 * Now, we need to write some data in our file. For now, strings will suffice,
331 * so let's just dump a bunch of them in there.
334 * As you can see, we copied a string into our static buffer, which is a bit
335 * bigger than the full length of the string, and then told Eet to write it
336 * into the file, compressed, returning the size of the data written into the
338 * This is all to show that Eet treats data as just data. It doesn't matter
339 * what that data represents (for now), it's all just bytes for it. As running
340 * the following code will show, we took a string of around 30 bytes and put it
341 * in a buffer of 1024 bytes, but the returned size won't be any of those.
344 * Next, we copy into our buffer our set of strings, including their null
345 * terminators and write them into the file. No error checking for the sake
346 * of brevity. And a call to eet_sync() to make sure all out data is
347 * properly written down to disk, even though we haven't yet closed the file.
350 * One more write, this time our large array of binary data and... well, I
351 * couldn't come up with a valid use of the last set of strings we stored,
352 * so let's take it out from the file with eet_delete().
355 * Finally, we close the file, saving any changes back to disk and return.
356 * Notice how, if there's any error closing the file or saving its contents,
357 * the return value from the function will be a false one, which later on
358 * will make the program exit with an error code.
361 * Moving onto our main function, we will open the same file and read it back.
362 * Trivial, but it'll show how we can do so in more than one way. We'll skip
363 * the variable declarations, as they aren't very different from what we've
366 * We start from the beginning by initializing Eet so things in general work.
367 * Forgetting to do so will result in weird results or crashes when calling
368 * any eet function, so if you experience something like that, the first thing
369 * to look at is whether eet_init() is missing.
370 * Then we call our @p create_eet_file function, described above, to make
371 * sure we have something to work with. If the function fails it will return
372 * 0 and we just exit, since nothing from here onwards will work anyway.
376 * Let's take a look now at what entries our file has. For this, we use
377 * eet_list(), which will return a list of strings, each being the name of
378 * one entry. Since we skipped before, it may be worth noting that @p list
379 * is declared as a @p char **.
380 * The @p num parameter will, of course, have the number of entries contained
382 * If everything's fine, we'll get our list and print it to the screen, and
383 * once done with it, we free the list. That's just the list, not its contents,
384 * as they are internal strings used by Eet and trying to free them will surely
388 * Reading back plain data is simple. Just a call to eet_read() with the file
389 * to read from, and the name of the entry we are interested in. We get back
390 * our data and the passed @p size parameter will contain the size of it. If
391 * the data was stored compressed, it will decompressed first.
394 * Another simple read for the set of strings from before, except those were
395 * deleted, so we should get a NULL return and continue normally.
398 * Finally, we'll get our binary data in the same way we got the strings. Once
399 * again, it makes no difference for Eet what the data is, it's up to us to
400 * know how to handle it.
403 * Now some cheating, we know that this data is an Eet file because, well...
404 * we just know it. So we are going to open it and take a look at its insides.
405 * For this, eet_open() won't work, as it needs to have a file on disk to read
406 * from and all we have is some data in RAM.
408 * So how do we do? One way would be to create a normal file and write down
409 * our data, then open it with eet_open(). Another, faster and more efficient
410 * if all we want to do is read the file, is to use eet_memopen_read().
413 * As you can see, the size we got from our previous read was put to good use
414 * this time. Unlike the first one where all we had were strings, the size
415 * of the data read only serves to demonstrate that we are reading back the
416 * entire size of our original @p buf variable.
418 * A little peeking to see how many entries the file has and to make an
419 * example of eet_num_entries() to get that number when we don't care about
423 * More cheating follows. Just like we knew this was an Eet file, we also know
424 * what key to read from, and ontop of that we know that the data in it is not
426 * Knowing all this allows us to take some shortcuts.
429 * That's a direct print of our data, whatever that data is. We don't want
430 * to worry about having to free it later, so we just used eet_direct_read()
431 * to tell Eet to gives a pointer to the internal data in the file, without
432 * duplicating it. Since we said that data was not compressed, we shouldn't
433 * worry about printing garbage to the screen (and yes, we also know the data
434 * is yet another string).
435 * We also don't care about the size of the data as it was stored in the file,
436 * so we passed NULL as the size parameter.
437 * One very important note about this, however, is that we don't care about
438 * the size parameter because the data in the file contains the null
439 * terminator for the string. So when using Eet to store strings this way,
440 * it's very important to consider whether you will keep that final null
441 * byte, or to always get the size read and do the necessary checks and copies.
442 * It's up to the user and the particular use cases to decide how this will
445 * With everything done, close this second file and free the data used to open
446 * it. And this is important, we can't free that data until we are done with
447 * the file, as Eet is using it. When opening with eet_memopen_read(), the data
448 * passed to it must be available for as long as the the file is open.
451 * Finally, we close the first file, shutdown all internal resources used by
452 * Eet and leave our main function, thus terminating our program.
455 * You can look at the full code of the example @ref eet-file.c "here".
460 * @enum _Eet_File_Mode
461 * Modes that a file can be opened.
463 typedef enum _Eet_File_Mode
465 EET_FILE_MODE_INVALID = -1,
466 EET_FILE_MODE_READ, /**< File is read-only. */
467 EET_FILE_MODE_WRITE, /**< File is write-only. */
468 EET_FILE_MODE_READ_WRITE /**< File is for both read and write */
469 } Eet_File_Mode; /**< Modes that a file can be opened. */
473 * Opaque handle that defines an Eet file (or memory).
475 * This handle will be returned by the functions eet_open() and
476 * eet_memopen_read() and is used by every other function that affects the
477 * file in any way. When you are done with it, call eet_close() to close it
478 * and, if the file was open for writing, write down to disk any changes made
482 * @see eet_memopen_read()
485 typedef struct _Eet_File Eet_File;
488 * @typedef Eet_Dictionary
489 * Opaque handle that defines a file-backed (mmaped) dictionary of strings.
491 typedef struct _Eet_Dictionary Eet_Dictionary;
494 * @typedef Eet_Entries
495 * Eet files may contains multiple Entries per file, this handle describe them. You can get that handle from an iterator given by eet_list_entries().
497 * @see eet_list_entries()
500 typedef struct _Eet_Entry Eet_Entry;
503 const char *name; /**< The entry name */
505 int offset; /**< Where it start in the file */
506 int size; /**< The size on disk */
507 int data_size; /**< The decompressed size if relevant */
509 Eina_Bool compression; /**< Is this data compressed ? */
510 Eina_Bool ciphered; /**< Is it ciphered ? */
511 Eina_Bool alias; /**< Is it an alias ? */
519 * Open an eet file on disk, and returns a handle to it.
520 * @param file The file path to the eet file. eg: @c "/tmp/file.eet".
521 * @param mode The mode for opening. Either #EET_FILE_MODE_READ,
522 * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE.
523 * @return An opened eet file handle.
524 * @ingroup Eet_File_Group
526 * This function will open an exiting eet file for reading, and build
527 * the directory table in memory and return a handle to the file, if it
528 * exists and can be read, and no memory errors occur on the way, otherwise
529 * NULL will be returned.
531 * It will also open an eet file for writing. This will, if successful,
532 * delete the original file and replace it with a new empty file, till
533 * the eet file handle is closed or flushed. If it cannot be opened for
534 * writing or a memory error occurs, NULL is returned.
536 * You can also open the file for read/write. If you then write a key that
537 * does not exist it will be created, if the key exists it will be replaced
540 * If the same file is opened multiple times, then the same file handle will
541 * be returned as eet maintains an internal list of all currently open
542 * files. Note that it considers files opened for read only and those opened
543 * for read/write and write only as 2 separate sets. Those that do not write
544 * to the file and those that do. Eet will allow 2 handles to the same file
545 * if they are in the 2 separate lists/groups. That means opening a file for
546 * read only looks in the read only set, and returns a handle to that file
547 * handle and increments its reference count. If you open a file for read/write
548 * or write only it looks in the write set and returns a handle after
549 * incrementing the reference count. You need to close an eet file handle
550 * as many times as it has been opened to maintain correct reference counts.
551 * Files whose modified timestamp or size do not match those of the existing
552 * referenced file handles will not be returned and a new handle will be
558 eet_open(const char *file,
562 * Open an eet file on disk from an Eina_File handle, and returns a handle to it.
563 * @param file The Eina_File handle to map to an eet file.
564 * @return An opened eet file handle.
565 * @ingroup Eet_File_Group
567 * This function will open an exiting eet file for reading, and build
568 * the directory table in memory and return a handle to the file, if it
569 * exists and can be read, and no memory errors occur on the way, otherwise
570 * NULL will be returned.
572 * This function can't open file for writing only read only mode is supported for now.
574 * If the same file is opened multiple times, then the same file handle will
575 * be returned as eet maintains an internal list of all currently open
576 * files. That means opening a file for read only looks in the read only set,
577 * and returns a handle to that file handle and increments its reference count.
578 * You need to close an eet file handle as many times as it has been opened to
579 * maintain correct reference counts.
584 eet_mmap(const Eina_File *file);
587 * Open an eet file directly from a memory location. The data is not copied,
588 * so you must keep it around as long as the eet file is open. There is
589 * currently no cache for this kind of Eet_File, so it's reopened every time
590 * you use eet_memopen_read.
591 * @param data Address of file in memory.
592 * @param size Size of memory to be read.
593 * @return A handle to the file.
595 * Files opened this way will always be in read-only mode.
598 * @ingroup Eet_File_Group
601 eet_memopen_read(const void *data,
605 * Get the mode an Eet_File was opened with.
606 * @param ef A valid eet file handle.
607 * @return The mode ef was opened with.
610 * @ingroup Eet_File_Group
613 eet_mode_get(Eet_File *ef);
616 * Close an eet file handle and flush pending writes.
617 * @param ef A valid eet file handle.
618 * @return An eet error identifier.
620 * This function will flush any pending writes to disk if the eet file
621 * was opened for write, and free all data associated with the file handle
622 * and file, and close the file. If it was opened for read (or read/write),
623 * the file handle may still be held open internally for caching purposes.
624 * To flush speculatively held eet file handles use eet_clearcache().
626 * If the eet file handle is not valid nothing will be done.
629 * @ingroup Eet_File_Group
631 * @see eet_clearcache()
634 eet_close(Eet_File *ef);
637 * Sync content of an eet file handle, flushing pending writes.
638 * @param ef A valid eet file handle.
639 * @return An eet error identifier.
641 * This function will flush any pending writes to disk. The eet file must
642 * be opened for write.
644 * If the eet file handle is not valid nothing will be done.
647 * @ingroup Eet_File_Group
650 eet_sync(Eet_File *ef);
653 * Return a handle to the shared string dictionary of the Eet file
654 * @param ef A valid eet file handle.
655 * @return A handle to the dictionary of the file
657 * This function returns a handle to the dictionary of an Eet file whose
658 * handle is @p ef, if a dictionary exists. NULL is returned otherwise or
659 * if the file handle is known to be invalid.
661 * @see eet_dictionary_string_check() to know if given string came
662 * from the dictionary or it was dynamically allocated using
663 * the #Eet_Data_Descriptor_Class instructions.
666 * @ingroup Eet_File_Group
668 EAPI Eet_Dictionary *
669 eet_dictionary_get(Eet_File *ef);
672 * Check if a given string comes from a given dictionary
673 * @param ed A valid dictionary handle
674 * @param string A valid 0 byte terminated C string
675 * @return 1 if it is in the dictionary, 0 otherwise
677 * This checks the given dictionary to see if the given string is actually
678 * inside that dictionary (i.e. comes from it) and returns 1 if it does.
679 * If the dictionary handle is invalid, the string is NULL or the string is
680 * not in the dictionary, 0 is returned.
683 * @ingroup Eet_File_Group
686 eet_dictionary_string_check(Eet_Dictionary *ed,
690 * Return the number of strings inside a dictionary
691 * @param ed A valid dictionary handle
692 * @return the number of strings inside a dictionary
695 * @ingroup Eet_File_Group
698 eet_dictionary_count(const Eet_Dictionary *ed);
701 * Read a specified entry from an eet file and return data
702 * @param ef A valid eet file handle opened for reading.
703 * @param name Name of the entry. eg: "/base/file_i_want".
704 * @param size_ret Number of bytes read from entry and returned.
705 * @return The data stored in that entry in the eet file.
707 * This function finds an entry in the eet file that is stored under the
708 * name specified, and returns that data, decompressed, if successful.
709 * NULL is returned if the lookup fails or if memory errors are
710 * encountered. It is the job of the calling program to call free() on
711 * the returned data. The number of bytes in the returned data chunk are
712 * placed in size_ret.
714 * If the eet file handle is not valid NULL is returned and size_ret is
717 * @see eet_read_cipher()
720 * @ingroup Eet_File_Group
723 eet_read(Eet_File *ef,
728 * Read a specified entry from an eet file and return data
729 * @param ef A valid eet file handle opened for reading.
730 * @param name Name of the entry. eg: "/base/file_i_want".
731 * @param size_ret Number of bytes read from entry and returned.
732 * @return The data stored in that entry in the eet file.
734 * This function finds an entry in the eet file that is stored under the
735 * name specified, and returns that data if not compressed and successful.
736 * NULL is returned if the lookup fails or if memory errors are
737 * encountered or if the data is compressed. The calling program must never
738 * call free() on the returned data. The number of bytes in the returned
739 * data chunk are placed in size_ret.
741 * If the eet file handle is not valid NULL is returned and size_ret is
745 * @ingroup Eet_File_Group
748 eet_read_direct(Eet_File *ef,
753 * Write a specified entry to an eet file handle
754 * @param ef A valid eet file handle opened for writing.
755 * @param name Name of the entry. eg: "/base/file_i_want".
756 * @param data Pointer to the data to be stored.
757 * @param size Length in bytes in the data to be stored.
758 * @param compress Compression flags (1 == compress, 0 = don't compress).
759 * @return bytes written on successful write, 0 on failure.
761 * This function will write the specified chunk of data to the eet file
762 * and return greater than 0 on success. 0 will be returned on failure.
764 * The eet file handle must be a valid file handle for an eet file opened
765 * for writing. If it is not, 0 will be returned and no action will be
768 * Name, and data must not be NULL, and size must be > 0. If these
769 * conditions are not met, 0 will be returned.
771 * The data will be copied (and optionally compressed) in ram, pending
772 * a flush to disk (it will stay in ram till the eet file handle is
775 * @see eet_write_cipher()
778 * @ingroup Eet_File_Group
781 eet_write(Eet_File *ef,
788 * Delete a specified entry from an Eet file being written or re-written
789 * @param ef A valid eet file handle opened for writing.
790 * @param name Name of the entry. eg: "/base/file_i_want".
791 * @return Success or failure of the delete.
793 * This function will delete the specified chunk of data from the eet file
794 * and return greater than 0 on success. 0 will be returned on failure.
796 * The eet file handle must be a valid file handle for an eet file opened
797 * for writing. If it is not, 0 will be returned and no action will be
800 * Name, must not be NULL, otherwise 0 will be returned.
803 * @ingroup Eet_File_Group
806 eet_delete(Eet_File *ef,
810 * Alias a specific section to another one. Destination may exist or not,
811 * no checks are done.
812 * @param ef A valid eet file handle opened for writing.
813 * @param name Name of the new entry. eg: "/base/file_i_want".
814 * @param destination Actual source of the aliased entry eg: "/base/the_real_stuff_i_want".
815 * @param compress Compression flags (1 == compress, 0 = don't compress).
816 * @return EINA_TRUE on success, EINA_FALSE on failure.
818 * Name and Destination must not be NULL, otherwise EINA_FALSE will be returned.
819 * The equivalent of this would be calling 'ln -s destination name'
822 * @ingroup Eet_File_Group
825 eet_alias(Eet_File *ef,
827 const char *destination,
831 * Retrieve the filename of an Eet_File
832 * @param ef A valid eet file handle opened for writing.
833 * @return The stringshared file string opened with eet_open(), or NULL on error
835 * @note This function will return NULL for files opened with eet_memopen_read()
838 * @ingroup Eet_File_Group
841 eet_file_get(Eet_File *ef);
844 * Retrieve the destination name of an alias
845 * @param ef A valid eet file handle opened for writing
846 * @param name Name of the entry. eg: "/base/file_i_want"
847 * @return Destination of the alias. eg: "/base/the_real_stuff_i_want", NULL on failure
849 * Name must not be NULL, otherwise NULL will be returned.
852 * @ingroup Eet_File_Group
855 eet_alias_get(Eet_File *ef,
859 * List all entries in eet file matching shell glob.
860 * @param ef A valid eet file handle.
861 * @param glob A shell glob to match against.
862 * @param count_ret Number of entries found to match.
863 * @return Pointer to an array of strings.
865 * This function will list all entries in the eet file matching the
866 * supplied shell glob and return an allocated list of their names, if
867 * there are any, and if no memory errors occur.
869 * The eet file handle must be valid and glob must not be NULL, or NULL
870 * will be returned and count_ret will be filled with 0.
872 * The calling program must call free() on the array returned, but NOT
873 * on the string pointers in the array. They are taken as read-only
874 * internals from the eet file handle. They are only valid as long as
875 * the file handle is not closed. When it is closed those pointers in the
876 * array are now not valid and should not be used.
878 * On success the array returned will have a list of string pointers
879 * that are the names of the entries that matched, and count_ret will have
880 * the number of entries in this array placed in it.
882 * Hint: an easy way to list all entries in an eet file is to use a glob
886 * @ingroup Eet_File_Group
889 eet_list(Eet_File *ef,
894 * Return an iterator that will describe each entry of an Eet_File.
895 * @param ef A valid eet file handle.
896 * @return An interator of Eet_Entry.
899 * @ingroup Eet_File_Group
902 EAPI Eina_Iterator *eet_list_entries(Eet_File *ef);
905 * Return the number of entries in the specified eet file.
906 * @param ef A valid eet file handle.
907 * @return Number of entries in ef or -1 if the number of entries
908 * cannot be read due to open mode restrictions.
911 * @ingroup Eet_File_Group
914 eet_num_entries(Eet_File *ef);
917 * @defgroup Eet_File_Cipher_Group Eet File Ciphered Main Functions
919 * Most of the @ref Eet_File_Group have alternative versions that
920 * accounts for ciphers to protect their content.
922 * @see @ref Eet_Cipher_Group
924 * @ingroup Eet_File_Group
928 * Read a specified entry from an eet file and return data using a cipher.
929 * @param ef A valid eet file handle opened for reading.
930 * @param name Name of the entry. eg: "/base/file_i_want".
931 * @param size_ret Number of bytes read from entry and returned.
932 * @param cipher_key The key to use as cipher.
933 * @return The data stored in that entry in the eet file.
935 * This function finds an entry in the eet file that is stored under the
936 * name specified, and returns that data, decompressed, if successful.
937 * NULL is returned if the lookup fails or if memory errors are
938 * encountered. It is the job of the calling program to call free() on
939 * the returned data. The number of bytes in the returned data chunk are
940 * placed in size_ret.
942 * If the eet file handle is not valid NULL is returned and size_ret is
948 * @ingroup Eet_File_Cipher_Group
951 eet_read_cipher(Eet_File *ef,
954 const char *cipher_key);
957 * Write a specified entry to an eet file handle using a cipher.
958 * @param ef A valid eet file handle opened for writing.
959 * @param name Name of the entry. eg: "/base/file_i_want".
960 * @param data Pointer to the data to be stored.
961 * @param size Length in bytes in the data to be stored.
962 * @param compress Compression flags (1 == compress, 0 = don't compress).
963 * @param cipher_key The key to use as cipher.
964 * @return bytes written on successful write, 0 on failure.
966 * This function will write the specified chunk of data to the eet file
967 * and return greater than 0 on success. 0 will be returned on failure.
969 * The eet file handle must be a valid file handle for an eet file opened
970 * for writing. If it is not, 0 will be returned and no action will be
973 * Name, and data must not be NULL, and size must be > 0. If these
974 * conditions are not met, 0 will be returned.
976 * The data will be copied (and optionally compressed) in ram, pending
977 * a flush to disk (it will stay in ram till the eet file handle is
983 * @ingroup Eet_File_Cipher_Group
986 eet_write_cipher(Eet_File *ef,
991 const char *cipher_key);
994 * @defgroup Eet_File_Image_Group Image Store and Load
997 * Eet efficiently stores and loads images, including alpha
998 * channels and lossy compressions.
1000 * Eet can handle both lossy compression with different levels of quality and
1001 * non-lossy compression with different compression levels. It's also possible,
1002 * given an image data, to only read its header to get the image information
1003 * without decoding the entire content for it.
1005 * The encode family of functions will take an image raw buffer and its
1006 * parameters and compress it in memory, returning the new buffer.
1007 * Likewise, the decode functions will read from the given location in memory
1008 * and return the uncompressed image.
1010 * The read and write functions will, respectively, encode and decode to or
1011 * from an Eet file, under the specified key.
1013 * These functions are fairly low level and the same functionality can be
1014 * achieved using Evas and Edje, making it much easier to work with images
1015 * as well as not needing to worry about things like scaling them.
1019 * Read just the header data for an image and dont decode the pixels.
1020 * @param ef A valid eet file handle opened for reading.
1021 * @param name Name of the entry. eg: "/base/file_i_want".
1022 * @param w A pointer to the unsigned int to hold the width in pixels.
1023 * @param h A pointer to the unsigned int to hold the height in pixels.
1024 * @param alpha A pointer to the int to hold the alpha flag.
1025 * @param compress A pointer to the int to hold the compression amount.
1026 * @param quality A pointer to the int to hold the quality amount.
1027 * @param lossy A pointer to the int to hold the lossiness flag.
1028 * @return 1 on successful decode, 0 otherwise
1030 * Reads and decodes the image header data stored under the given key and
1033 * The information decoded is placed in each of the parameters, which must be
1034 * provided. The width and height, measured in pixels, will be stored under
1035 * the variables pointed by @p w and @p h, respectively. If the read or
1036 * decode of the header fails, this values will be 0. The @p alpha parameter
1037 * will be 1 or 0, denoting if the alpha channel of the image is used or not.
1038 * If the image was losslessly compressed, the @p compress parameter will hold
1039 * the compression amount used, ranging from 0 to 9 and @p lossy will be 0.
1040 * In the case of lossy compression, @p lossy will be 1, and the compression
1041 * quality will be placed under @p quality, with a value ranging from 0 to 100.
1043 * @see eet_data_image_header_decode()
1044 * @see eet_data_image_header_read_cipher()
1047 * @ingroup Eet_File_Image_Group
1050 eet_data_image_header_read(Eet_File *ef,
1060 * Read image data from the named key in the eet file.
1061 * @param ef A valid eet file handle opened for reading.
1062 * @param name Name of the entry. eg: "/base/file_i_want".
1063 * @param w A pointer to the unsigned int to hold the width in pixels.
1064 * @param h A pointer to the unsigned int to hold the height in pixels.
1065 * @param alpha A pointer to the int to hold the alpha flag.
1066 * @param compress A pointer to the int to hold the compression amount.
1067 * @param quality A pointer to the int to hold the quality amount.
1068 * @param lossy A pointer to the int to hold the lossiness flag.
1069 * @return The image pixel data decoded
1071 * Reads and decodes the image stored in the given Eet file under the named
1074 * The returned pixel data is a linear array of pixels starting from the
1075 * top-left of the image, scanning row by row from left to right. Each pile
1076 * is a 32bit value, with the high byte being the alpha channel, the next being
1077 * red, then green, and the low byte being blue.
1079 * The rest of the parameters are the same as in eet_data_image_header_read().
1081 * On success the function returns a pointer to the image data decoded. The
1082 * calling application is responsible for calling free() on the image data
1083 * when it is done with it. On failure NULL is returned and the parameter
1084 * values may not contain any sensible data.
1086 * @see eet_data_image_header_read()
1087 * @see eet_data_image_decode()
1088 * @see eet_data_image_read_cipher()
1089 * @see eet_data_image_read_to_surface()
1092 * @ingroup Eet_File_Image_Group
1095 eet_data_image_read(Eet_File *ef,
1105 * Read image data from the named key in the eet file and store it in the given buffer.
1106 * @param ef A valid eet file handle opened for reading.
1107 * @param name Name of the entry. eg: "/base/file_i_want".
1108 * @param src_x The starting x coordinate from where to dump the stream.
1109 * @param src_y The starting y coordinate from where to dump the stream.
1110 * @param d A pointer to the pixel surface.
1111 * @param w The expected width in pixels of the pixel surface to decode.
1112 * @param h The expected height in pixels of the pixel surface to decode.
1113 * @param row_stride The length of a pixels line in the destination surface.
1114 * @param alpha A pointer to the int to hold the alpha flag.
1115 * @param compress A pointer to the int to hold the compression amount.
1116 * @param quality A pointer to the int to hold the quality amount.
1117 * @param lossy A pointer to the int to hold the lossiness flag.
1118 * @return 1 on success, 0 otherwise.
1120 * Reads and decodes the image stored in the given Eet file, placing the
1121 * resulting pixel data in the buffer pointed by the user.
1123 * Like eet_data_image_read(), it takes the image data stored under the
1124 * @p name key in the @p ef file, but instead of returning a new buffer with
1125 * the pixel data, it places the result in the buffer pointed by @p d, which
1126 * must be provided by the user and of sufficient size to hold the requested
1127 * portion of the image.
1129 * The @p src_x and @p src_y parameters indicate the top-left corner of the
1130 * section of the image to decode. These have to be higher or equal than 0 and
1131 * less than the respective total width and height of the image. The width
1132 * and height of the section of the image to decode are given in @p w and @p h
1133 * and also can't be higher than the total width and height of the image.
1135 * The @p row_stride parameter indicates the length in bytes of each line in
1136 * the destination buffer and it has to be at least @p w * 4.
1138 * All the other parameters are the same as in eet_data_image_read().
1140 * On success the function returns 1, and 0 on failure. On failure the
1141 * parameter values may not contain any sensible data.
1143 * @see eet_data_image_read()
1144 * @see eet_data_image_decode()
1145 * @see eet_data_image_decode_to_surface()
1146 * @see eet_data_image_read_to_surface_cipher()
1149 * @ingroup Eet_File_Image_Group
1152 eet_data_image_read_to_surface(Eet_File *ef,
1159 unsigned int row_stride,
1166 * Write image data to the named key in an eet file.
1167 * @param ef A valid eet file handle opened for writing.
1168 * @param name Name of the entry. eg: "/base/file_i_want".
1169 * @param data A pointer to the image pixel data.
1170 * @param w The width of the image in pixels.
1171 * @param h The height of the image in pixels.
1172 * @param alpha The alpha channel flag.
1173 * @param compress The compression amount.
1174 * @param quality The quality encoding amount.
1175 * @param lossy The lossiness flag.
1176 * @return Success if the data was encoded and written or not.
1178 * This function takes image pixel data and encodes it in an eet file
1179 * stored under the supplied name key, and returns how many bytes were
1180 * actually written to encode the image data.
1182 * The data expected is the same format as returned by eet_data_image_read.
1183 * If this is not the case weird things may happen. Width and height must
1184 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1185 * the alpha values are not useful and 1 meaning they are). Compress can
1186 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1187 * This is only used if the image is not lossily encoded. Quality is used on
1188 * lossy compression and should be a value from 0 to 100. The lossy flag
1189 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1190 * image quality loss (but then have a much smaller encoding).
1192 * On success this function returns the number of bytes that were required
1193 * to encode the image data, or on failure it returns 0.
1195 * @see eet_data_image_read()
1196 * @see eet_data_image_encode()
1197 * @see eet_data_image_write_cipher()
1200 * @ingroup Eet_File_Image_Group
1203 eet_data_image_write(Eet_File *ef,
1214 * Decode Image data header only to get information.
1215 * @param data The encoded pixel data.
1216 * @param size The size, in bytes, of the encoded pixel data.
1217 * @param w A pointer to the unsigned int to hold the width in pixels.
1218 * @param h A pointer to the unsigned int to hold the height in pixels.
1219 * @param alpha A pointer to the int to hold the alpha flag.
1220 * @param compress A pointer to the int to hold the compression amount.
1221 * @param quality A pointer to the int to hold the quality amount.
1222 * @param lossy A pointer to the int to hold the lossiness flag.
1223 * @return 1 on success, 0 on failure.
1225 * This function works exactly like eet_data_image_header_read(), but instead
1226 * of reading from an Eet file, it takes the buffer of size @p size pointed
1227 * by @p data, which must be a valid Eet encoded image.
1229 * On success the function returns 1 indicating the header was read and
1230 * decoded properly, or 0 on failure.
1232 * @see eet_data_image_header_read()
1233 * @see eet_data_image_header_decode_cipher()
1236 * @ingroup Eet_File_Image_Group
1239 eet_data_image_header_decode(const void *data,
1249 * Decode Image data into pixel data.
1250 * @param data The encoded pixel data.
1251 * @param size The size, in bytes, of the encoded pixel data.
1252 * @param w A pointer to the unsigned int to hold the width in pixels.
1253 * @param h A pointer to the unsigned int to hold the height in pixels.
1254 * @param alpha A pointer to the int to hold the alpha flag.
1255 * @param compress A pointer to the int to hold the compression amount.
1256 * @param quality A pointer to the int to hold the quality amount.
1257 * @param lossy A pointer to the int to hold the lossiness flag.
1258 * @return The image pixel data decoded
1260 * This function takes encoded pixel data and decodes it into raw RGBA
1261 * pixels on success.
1263 * It works exactly like eet_data_image_read(), but it takes the encoded
1264 * data in the @p data buffer of size @p size, instead of reading from a file.
1265 * All the others parameters are also the same.
1267 * On success the function returns a pointer to the image data decoded. The
1268 * calling application is responsible for calling free() on the image data
1269 * when it is done with it. On failure NULL is returned and the parameter
1270 * values may not contain any sensible data.
1272 * @see eet_data_image_read()
1273 * @see eet_data_image_decode_cipher()
1276 * @ingroup Eet_File_Image_Group
1279 eet_data_image_decode(const void *data,
1289 * Decode Image data into pixel data and stores in the given buffer.
1290 * @param data The encoded pixel data.
1291 * @param size The size, in bytes, of the encoded pixel data.
1292 * @param src_x The starting x coordinate from where to dump the stream.
1293 * @param src_y The starting y coordinate from where to dump the stream.
1294 * @param d A pointer to the pixel surface.
1295 * @param w The expected width in pixels of the pixel surface to decode.
1296 * @param h The expected height in pixels of the pixel surface to decode.
1297 * @param row_stride The length of a pixels line in the destination surface.
1298 * @param alpha A pointer to the int to hold the alpha flag.
1299 * @param compress A pointer to the int to hold the compression amount.
1300 * @param quality A pointer to the int to hold the quality amount.
1301 * @param lossy A pointer to the int to hold the lossiness flag.
1302 * @return 1 on success, 0 otherwise.
1304 * Like eet_data_image_read_to_surface(), but reading the given @p data buffer
1305 * instead of a file.
1307 * On success the function returns 1, and 0 on failure. On failure the
1308 * parameter values may not contain any sensible data.
1310 * @see eet_data_image_read_to_surface()
1311 * @see eet_data_image_decode_to_surface_cipher()
1314 * @ingroup Eet_File_Image_Group
1317 eet_data_image_decode_to_surface(const void *data,
1324 unsigned int row_stride,
1331 * Encode image data for storage or transmission.
1332 * @param data A pointer to the image pixel data.
1333 * @param size_ret A pointer to an int to hold the size of the returned data.
1334 * @param w The width of the image in pixels.
1335 * @param h The height of the image in pixels.
1336 * @param alpha The alpha channel flag.
1337 * @param compress The compression amount.
1338 * @param quality The quality encoding amount.
1339 * @param lossy The lossiness flag.
1340 * @return The encoded image data.
1342 * This function stakes image pixel data and encodes it with compression and
1343 * possible loss of quality (as a trade off for size) for storage or
1344 * transmission to another system.
1346 * It works like eet_data_image_write(), but instead of writing the encoded
1347 * image into an Eet file, it allocates a new buffer of the size required and
1348 * returns the encoded data in it.
1350 * On success this function returns a pointer to the encoded data that you
1351 * can free with free() when no longer needed.
1353 * @see eet_data_image_write()
1354 * @see eet_data_image_read()
1355 * @see eet_data_image_encode_cipher()
1358 * @ingroup Eet_File_Image_Group
1361 eet_data_image_encode(const void *data,
1371 * @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Cipher
1373 * Most of the @ref Eet_File_Image_Group have alternative versions
1374 * that accounts for ciphers to protect their content.
1376 * @see @ref Eet_Cipher_Group
1378 * @ingroup Eet_File_Image_Group
1382 * Read just the header data for an image and dont decode the pixels using a cipher.
1383 * @param ef A valid eet file handle opened for reading.
1384 * @param name Name of the entry. eg: "/base/file_i_want".
1385 * @param cipher_key The key to use as cipher.
1386 * @param w A pointer to the unsigned int to hold the width in pixels.
1387 * @param h A pointer to the unsigned int to hold the height in pixels.
1388 * @param alpha A pointer to the int to hold the alpha flag.
1389 * @param compress A pointer to the int to hold the compression amount.
1390 * @param quality A pointer to the int to hold the quality amount.
1391 * @param lossy A pointer to the int to hold the lossiness flag.
1392 * @return 1 on successful decode, 0 otherwise
1394 * This function reads an image from an eet file stored under the named
1395 * key in the eet file and return a pointer to the decompressed pixel data.
1397 * The other parameters of the image (width, height etc.) are placed into
1398 * the values pointed to (they must be supplied). The pixel data is a linear
1399 * array of pixels starting from the top-left of the image scanning row by
1400 * row from left to right. Each pixel is a 32bit value, with the high byte
1401 * being the alpha channel, the next being red, then green, and the low byte
1402 * being blue. The width and height are measured in pixels and will be
1403 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1404 * that the alpha channel is not used. 1 denotes that it is significant.
1405 * Compress is filled with the compression value/amount the image was
1406 * stored with. The quality value is filled with the quality encoding of
1407 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1408 * the image was encoded lossily or not.
1410 * On success the function returns 1 indicating the header was read and
1411 * decoded properly, or 0 on failure.
1413 * @see eet_data_image_header_read()
1416 * @ingroup Eet_File_Image_Cipher_Group
1419 eet_data_image_header_read_cipher(Eet_File *ef,
1421 const char *cipher_key,
1430 * Read image data from the named key in the eet file using a cipher.
1431 * @param ef A valid eet file handle opened for reading.
1432 * @param name Name of the entry. eg: "/base/file_i_want".
1433 * @param cipher_key The key to use as cipher.
1434 * @param w A pointer to the unsigned int to hold the width in pixels.
1435 * @param h A pointer to the unsigned int to hold the height in pixels.
1436 * @param alpha A pointer to the int to hold the alpha flag.
1437 * @param compress A pointer to the int to hold the compression amount.
1438 * @param quality A pointer to the int to hold the quality amount.
1439 * @param lossy A pointer to the int to hold the lossiness flag.
1440 * @return The image pixel data decoded
1442 * This function reads an image from an eet file stored under the named
1443 * key in the eet file and return a pointer to the decompressed pixel data.
1445 * The other parameters of the image (width, height etc.) are placed into
1446 * the values pointed to (they must be supplied). The pixel data is a linear
1447 * array of pixels starting from the top-left of the image scanning row by
1448 * row from left to right. Each pixel is a 32bit value, with the high byte
1449 * being the alpha channel, the next being red, then green, and the low byte
1450 * being blue. The width and height are measured in pixels and will be
1451 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1452 * that the alpha channel is not used. 1 denotes that it is significant.
1453 * Compress is filled with the compression value/amount the image was
1454 * stored with. The quality value is filled with the quality encoding of
1455 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1456 * the image was encoded lossily or not.
1458 * On success the function returns a pointer to the image data decoded. The
1459 * calling application is responsible for calling free() on the image data
1460 * when it is done with it. On failure NULL is returned and the parameter
1461 * values may not contain any sensible data.
1463 * @see eet_data_image_read()
1466 * @ingroup Eet_File_Image_Cipher_Group
1469 eet_data_image_read_cipher(Eet_File *ef,
1471 const char *cipher_key,
1480 * Read image data from the named key in the eet file using a cipher.
1481 * @param ef A valid eet file handle opened for reading.
1482 * @param name Name of the entry. eg: "/base/file_i_want".
1483 * @param cipher_key The key to use as cipher.
1484 * @param src_x The starting x coordinate from where to dump the stream.
1485 * @param src_y The starting y coordinate from where to dump the stream.
1486 * @param d A pointer to the pixel surface.
1487 * @param w The expected width in pixels of the pixel surface to decode.
1488 * @param h The expected height in pixels of the pixel surface to decode.
1489 * @param row_stride The length of a pixels line in the destination surface.
1490 * @param alpha A pointer to the int to hold the alpha flag.
1491 * @param compress A pointer to the int to hold the compression amount.
1492 * @param quality A pointer to the int to hold the quality amount.
1493 * @param lossy A pointer to the int to hold the lossiness flag.
1494 * @return 1 on success, 0 otherwise.
1496 * This function reads an image from an eet file stored under the named
1497 * key in the eet file and return a pointer to the decompressed pixel data.
1499 * The other parameters of the image (width, height etc.) are placed into
1500 * the values pointed to (they must be supplied). The pixel data is a linear
1501 * array of pixels starting from the top-left of the image scanning row by
1502 * row from left to right. Each pixel is a 32bit value, with the high byte
1503 * being the alpha channel, the next being red, then green, and the low byte
1504 * being blue. The width and height are measured in pixels and will be
1505 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1506 * that the alpha channel is not used. 1 denotes that it is significant.
1507 * Compress is filled with the compression value/amount the image was
1508 * stored with. The quality value is filled with the quality encoding of
1509 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1510 * the image was encoded lossily or not.
1512 * On success the function returns 1, and 0 on failure. On failure the
1513 * parameter values may not contain any sensible data.
1515 * @see eet_data_image_read_to_surface()
1518 * @ingroup Eet_File_Image_Cipher_Group
1521 eet_data_image_read_to_surface_cipher(Eet_File *ef,
1523 const char *cipher_key,
1529 unsigned int row_stride,
1536 * Write image data to the named key in an eet file using a cipher.
1537 * @param ef A valid eet file handle opened for writing.
1538 * @param name Name of the entry. eg: "/base/file_i_want".
1539 * @param cipher_key The key to use as cipher.
1540 * @param data A pointer to the image pixel data.
1541 * @param w The width of the image in pixels.
1542 * @param h The height of the image in pixels.
1543 * @param alpha The alpha channel flag.
1544 * @param compress The compression amount.
1545 * @param quality The quality encoding amount.
1546 * @param lossy The lossiness flag.
1547 * @return Success if the data was encoded and written or not.
1549 * This function takes image pixel data and encodes it in an eet file
1550 * stored under the supplied name key, and returns how many bytes were
1551 * actually written to encode the image data.
1553 * The data expected is the same format as returned by eet_data_image_read.
1554 * If this is not the case weird things may happen. Width and height must
1555 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1556 * the alpha values are not useful and 1 meaning they are). Compress can
1557 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1558 * This is only used if the image is not lossily encoded. Quality is used on
1559 * lossy compression and should be a value from 0 to 100. The lossy flag
1560 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1561 * image quality loss (but then have a much smaller encoding).
1563 * On success this function returns the number of bytes that were required
1564 * to encode the image data, or on failure it returns 0.
1566 * @see eet_data_image_write()
1569 * @ingroup Eet_File_Image_Cipher_Group
1572 eet_data_image_write_cipher(Eet_File *ef,
1574 const char *cipher_key,
1584 * Decode Image data header only to get information using a cipher.
1585 * @param data The encoded pixel data.
1586 * @param cipher_key The key to use as cipher.
1587 * @param size The size, in bytes, of the encoded pixel data.
1588 * @param w A pointer to the unsigned int to hold the width in pixels.
1589 * @param h A pointer to the unsigned int to hold the height in pixels.
1590 * @param alpha A pointer to the int to hold the alpha flag.
1591 * @param compress A pointer to the int to hold the compression amount.
1592 * @param quality A pointer to the int to hold the quality amount.
1593 * @param lossy A pointer to the int to hold the lossiness flag.
1594 * @return 1 on success, 0 on failure.
1596 * This function takes encoded pixel data and decodes it into raw RGBA
1597 * pixels on success.
1599 * The other parameters of the image (width, height etc.) are placed into
1600 * the values pointed to (they must be supplied). The pixel data is a linear
1601 * array of pixels starting from the top-left of the image scanning row by
1602 * row from left to right. Each pixel is a 32bit value, with the high byte
1603 * being the alpha channel, the next being red, then green, and the low byte
1604 * being blue. The width and height are measured in pixels and will be
1605 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1606 * that the alpha channel is not used. 1 denotes that it is significant.
1607 * Compress is filled with the compression value/amount the image was
1608 * stored with. The quality value is filled with the quality encoding of
1609 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1610 * the image was encoded lossily or not.
1612 * On success the function returns 1 indicating the header was read and
1613 * decoded properly, or 0 on failure.
1615 * @see eet_data_image_header_decode()
1618 * @ingroup Eet_File_Image_Cipher_Group
1621 eet_data_image_header_decode_cipher(const void *data,
1622 const char *cipher_key,
1632 * Decode Image data into pixel data using a cipher.
1633 * @param data The encoded pixel data.
1634 * @param cipher_key The key to use as cipher.
1635 * @param size The size, in bytes, of the encoded pixel data.
1636 * @param w A pointer to the unsigned int to hold the width in pixels.
1637 * @param h A pointer to the unsigned int to hold the height in pixels.
1638 * @param alpha A pointer to the int to hold the alpha flag.
1639 * @param compress A pointer to the int to hold the compression amount.
1640 * @param quality A pointer to the int to hold the quality amount.
1641 * @param lossy A pointer to the int to hold the lossiness flag.
1642 * @return The image pixel data decoded
1644 * This function takes encoded pixel data and decodes it into raw RGBA
1645 * pixels on success.
1647 * The other parameters of the image (width, height etc.) are placed into
1648 * the values pointed to (they must be supplied). The pixel data is a linear
1649 * array of pixels starting from the top-left of the image scanning row by
1650 * row from left to right. Each pixel is a 32bit value, with the high byte
1651 * being the alpha channel, the next being red, then green, and the low byte
1652 * being blue. The width and height are measured in pixels and will be
1653 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1654 * that the alpha channel is not used. 1 denotes that it is significant.
1655 * Compress is filled with the compression value/amount the image was
1656 * stored with. The quality value is filled with the quality encoding of
1657 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1658 * the image was encoded lossily or not.
1660 * On success the function returns a pointer to the image data decoded. The
1661 * calling application is responsible for calling free() on the image data
1662 * when it is done with it. On failure NULL is returned and the parameter
1663 * values may not contain any sensible data.
1665 * @see eet_data_image_decode()
1668 * @ingroup Eet_File_Image_Cipher_Group
1671 eet_data_image_decode_cipher(const void *data,
1672 const char *cipher_key,
1682 * Decode Image data into pixel data using a cipher.
1683 * @param data The encoded pixel data.
1684 * @param cipher_key The key to use as cipher.
1685 * @param size The size, in bytes, of the encoded pixel data.
1686 * @param src_x The starting x coordinate from where to dump the stream.
1687 * @param src_y The starting y coordinate from where to dump the stream.
1688 * @param d A pointer to the pixel surface.
1689 * @param w The expected width in pixels of the pixel surface to decode.
1690 * @param h The expected height in pixels of the pixel surface to decode.
1691 * @param row_stride The length of a pixels line in the destination surface.
1692 * @param alpha A pointer to the int to hold the alpha flag.
1693 * @param compress A pointer to the int to hold the compression amount.
1694 * @param quality A pointer to the int to hold the quality amount.
1695 * @param lossy A pointer to the int to hold the lossiness flag.
1696 * @return 1 on success, 0 otherwise.
1698 * This function takes encoded pixel data and decodes it into raw RGBA
1699 * pixels on success.
1701 * The other parameters of the image (alpha, compress etc.) are placed into
1702 * the values pointed to (they must be supplied). The pixel data is a linear
1703 * array of pixels starting from the top-left of the image scanning row by
1704 * row from left to right. Each pixel is a 32bit value, with the high byte
1705 * being the alpha channel, the next being red, then green, and the low byte
1706 * being blue. The width and height are measured in pixels and will be
1707 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1708 * that the alpha channel is not used. 1 denotes that it is significant.
1709 * Compress is filled with the compression value/amount the image was
1710 * stored with. The quality value is filled with the quality encoding of
1711 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1712 * the image was encoded lossily or not.
1714 * On success the function returns 1, and 0 on failure. On failure the
1715 * parameter values may not contain any sensible data.
1717 * @see eet_data_image_decode_to_surface()
1720 * @ingroup Eet_File_Image_Cipher_Group
1723 eet_data_image_decode_to_surface_cipher(const void *data,
1724 const char *cipher_key,
1731 unsigned int row_stride,
1738 * Encode image data for storage or transmission using a cipher.
1739 * @param data A pointer to the image pixel data.
1740 * @param cipher_key The key to use as cipher.
1741 * @param size_ret A pointer to an int to hold the size of the returned data.
1742 * @param w The width of the image in pixels.
1743 * @param h The height of the image in pixels.
1744 * @param alpha The alpha channel flag.
1745 * @param compress The compression amount.
1746 * @param quality The quality encoding amount.
1747 * @param lossy The lossiness flag.
1748 * @return The encoded image data.
1750 * This function stakes image pixel data and encodes it with compression and
1751 * possible loss of quality (as a trade off for size) for storage or
1752 * transmission to another system.
1754 * The data expected is the same format as returned by eet_data_image_read.
1755 * If this is not the case weird things may happen. Width and height must
1756 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1757 * the alpha values are not useful and 1 meaning they are). Compress can
1758 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1759 * This is only used if the image is not lossily encoded. Quality is used on
1760 * lossy compression and should be a value from 0 to 100. The lossy flag
1761 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1762 * image quality loss (but then have a much smaller encoding).
1764 * On success this function returns a pointer to the encoded data that you
1765 * can free with free() when no longer needed.
1767 * @see eet_data_image_encode()
1770 * @ingroup Eet_File_Image_Cipher_Group
1773 eet_data_image_encode_cipher(const void *data,
1774 const char *cipher_key,
1784 * @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms
1787 * Eet allows one to protect entries of an #Eet_File
1788 * individually. This may be used to ensure data was not tampered or
1789 * that third party does not read your data.
1791 * @see @ref Eet_File_Cipher_Group
1792 * @see @ref Eet_File_Image_Cipher_Group
1799 * Opaque handle that defines an identity (also known as key)
1800 * in Eet's cipher system.
1802 typedef struct _Eet_Key Eet_Key;
1809 * Callback used to request if needed the password of a private key.
1811 * @param buffer the buffer where to store the password.
1812 * @param size the maximum password size (size of buffer, including '@\0').
1813 * @param rwflag if the buffer is also readable or just writable.
1814 * @param data currently unused, may contain some context in future.
1815 * @return 1 on success and password was set to @p buffer, 0 on failure.
1818 * @ingroup Eet_Cipher_Group
1820 typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data);
1823 * Create an Eet_Key needed for signing an eet file.
1825 * The certificate should provide the public that match the private key.
1826 * No verification is done to ensure that.
1828 * @param certificate_file The file where to find the certificate.
1829 * @param private_key_file The file that contains the private key.
1830 * @param cb Function to callback if password is required to unlock
1832 * @return A key handle to use, or @c NULL on failure.
1834 * @see eet_identity_close()
1836 * @warning You need to compile signature support in EET.
1838 * @ingroup Eet_Cipher_Group
1841 eet_identity_open(const char *certificate_file,
1842 const char *private_key_file,
1843 Eet_Key_Password_Callback cb);
1846 * Close and release all resource used by an Eet_Key. An
1847 * reference counter prevent it from being freed until all file
1848 * using it are also closed.
1850 * @param key the key handle to close and free resources.
1853 * @ingroup Eet_Cipher_Group
1856 eet_identity_close(Eet_Key *key);
1859 * Set a key to sign a file
1861 * @param ef the file to set the identity.
1862 * @param key the key handle to set as identity.
1863 * @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or
1864 * #EET_ERROR_NONE on success.
1867 * @ingroup Eet_Cipher_Group
1870 eet_identity_set(Eet_File *ef,
1874 * Display both private and public key of an Eet_Key.
1876 * @param key the handle to print.
1877 * @param out where to print.
1879 * @warning You need to compile signature support in EET.
1881 * @ingroup Eet_Cipher_Group
1884 eet_identity_print(Eet_Key *key,
1888 * Get the x509 der certificate associated with an Eet_File. Will return NULL
1889 * if the file is not signed.
1891 * @param ef The file handle to query.
1892 * @param der_length The length of returned data, may be @c NULL.
1893 * @return the x509 certificate or @c NULL on error.
1896 * @ingroup Eet_Cipher_Group
1899 eet_identity_x509(Eet_File *ef,
1903 * Get the raw signature associated with an Eet_File. Will return NULL
1904 * if the file is not signed.
1906 * @param ef The file handle to query.
1907 * @param signature_length The length of returned data, may be @c NULL.
1908 * @return the raw signature or @c NULL on error.
1910 * @ingroup Eet_Cipher_Group
1913 eet_identity_signature(Eet_File *ef,
1914 int *signature_length);
1917 * Get the SHA1 associated with a file. Could be the one used to
1918 * sign the data or if the data where not signed, it will be the
1921 * @param ef The file handle to query.
1922 * @param sha1_length The length of returned data, may be @c NULL.
1923 * @return the associated SHA1 or @c NULL on error.
1926 * @ingroup Eet_Cipher_Group
1929 eet_identity_sha1(Eet_File *ef,
1933 * Display the x509 der certificate to out.
1935 * @param certificate the x509 certificate to print
1936 * @param der_length The length the certificate.
1937 * @param out where to print.
1939 * @warning You need to compile signature support in EET.
1941 * @ingroup Eet_Cipher_Group
1944 eet_identity_certificate_print(const unsigned char *certificate,
1949 * @defgroup Eet_Data_Group Eet Data Serialization
1952 * Convenience functions to serialize and parse complex data
1953 * structures to binary blobs.
1955 * While Eet core just handles binary blobs, it is often required
1956 * to save some structured data of different types, such as
1957 * strings, integers, lists, hashes and so on.
1959 * Eet can serialize and then parse data types given some
1960 * construction instructions. These are defined in two levels:
1962 * - #Eet_Data_Descriptor_Class to tell generic memory handling,
1963 * such as the size of the type, how to allocate memory, strings,
1964 * lists, hashes and so on.
1966 * - #Eet_Data_Descriptor to tell inside such type, the members and
1967 * their offsets inside the memory blob, their types and
1968 * names. These members can be simple types or other
1969 * #Eet_Data_Descriptor, allowing hierarchical types to be
1972 * Given that C provides no introspection, this process can be
1973 * quite cumbersome, so we provide lots of macros and convenience
1974 * functions to aid creating the types.
1976 * We make now a quick overview of some of the most commonly used elements
1977 * of this part of the library. A simple example of a configuration system
1978 * will work as a somewhat real life example that is still simple enough to
1980 * Only the relevant sections will be shown here, but you can get the full
1981 * code @ref eet-data-simple.c "here".
1983 * Ignoring the included headers, we'll begin by defining our configuration
1985 * @dontinclude eet-data-simple.c
1989 * When using Eet, you don't think in matters of what data the program needs
1990 * to run and which you would like to store. It's all the same and if it makes
1991 * more sense to keep them together, it's perfectly fine to do so. At the time
1992 * of telling Eet how your data is comprised you can leave out the things
1993 * that are runtime only and let Eet take care of the rest for you.
1995 * The key used to store the config follows, as well as the variable used to
1996 * store our data descriptor.
1997 * This last one is very important. It's the one thing that Eet will use to
1998 * identify your data, both at the time of writing it to the file and when
2001 * @skipline Eet_Data_Descriptor
2003 * Now we'll see how to create this descriptor, so Eet knows how to handle
2004 * our data later on.
2005 * Begin our function by declaring an Eet_Data_Descriptor_Class, which is
2006 * used to create the actual descriptor. This class contains the name of
2007 * our data type, its size and several functions that dictate how Eet should
2008 * handle memory to allocate the necessary bits to bring our data to life.
2009 * You, as a user, will very hardly set this class' contents directly. The
2010 * most common scenario is to use one of the provided macros that set it using
2011 * the Eina data types, so that's what we'll be doing across all our examples.
2013 * @until eet_data_descriptor_stream_new
2015 * Now that we have our descriptor, we need to make it describe something.
2016 * We do so by telling it which members of our struct we want it to know about
2018 * The eet_data_descriptor_element_add() function takes care of this, but it's
2019 * too cumbersome for normal use, so several macros are provided that make
2020 * it easier to handle. Even with them, however, code can get very repetitive
2021 * and it's not uncommon to define custom macros using them to save on typing.
2025 * Now our descriptor knows about the parts of our structure that we are
2026 * interesting in saving. You can see that not all of them are there, yet Eet
2027 * will find those that need saving and do the right thing. When loading our
2028 * data, any non-described fields in the structure will be zeroed, so there's
2029 * no need to worry about garbage memory in them.
2030 * Refer to the documentation of #EET_DATA_DESCRIPTOR_ADD_BASIC to understand
2031 * what our macro does.
2033 * We are done with our descriptor init function and it's proper to have the
2034 * relevant shutdown. Proper coding guidelines indiciate that all memory
2035 * allocated should be freed when the program ends, and since you will most
2036 * likely keep your descriptor around for the life or your application, it's
2037 * only right to free it at the end.
2041 * Not listed here, but included in the full example are functions to create
2042 * a blank configuration and free it. The first one will only be used when
2043 * no file exists to load from, or nothing is found in it, but the latter is
2044 * used regardless of where our data comes from. Unless you are reading direct
2045 * data from the Eet file, you will be in charge of freeing anything loaded
2048 * Now it's time to look at how we can load our config from some file.
2049 * Begin by opening the Eet file normally.
2050 * @skip static My_Conf_Type
2053 * And now we need to read the data from the file and decode it using our
2054 * descriptor. Fortunately, that's all done in one single step.
2057 * And that's it for all Eet cares about. But since we are dealing with a
2058 * common case, as is save and load of user configurations, the next fragment
2059 * of code shows why we have a version field in our struct, and how you can
2060 * use it to load older configuration files and update them as needed.
2063 * Finally, close the file and return the newly loaded config data.
2066 * Saving data is just as easy. The full version of the following function
2067 * includes code to save to a temporary file first, so you can be sure not
2068 * to lose all your data in the case of a failure mid-writing. You can look
2069 * at it @ref eet-data-simple.c "here".
2070 * @skip static Eina_Bool
2072 * @skipline Eina_Bool ret
2078 * To close, our main function, which doesn't do much. Just take some arguments
2079 * from the command line with the name of the file to load and another one
2080 * where to save again. If input file doesn't exist, a new config structure
2081 * will be created and saved to our output file.
2086 * The following is a list of more advanced and detailed examples.
2087 * @li @ref eet_data_nested_example
2088 * @li @ref eet_data_file_descriptor
2089 * @li @ref Example_Eet_Data_File_Descriptor_02
2090 * @li @ref Example_Eet_Data_Cipher_Decipher
2094 * @page eet_data_nested_example Nested structures and Eet Data Descriptors
2096 * We've seen already a simple example of how to use Eet Data Descriptors
2097 * to handle our structures, but it didn't show how this works when you
2098 * have structures inside other structures.
2100 * Now, there's a very simple case of this, for when you have inline structs
2101 * to keep your big structure more organized, you don't need anything else
2102 * besides what @ref eet-data-simple.c "this simple example does".
2103 * Just use something like @p some_struct.sub_struct.member when adding the
2104 * member to the descriptor and it will work.
2118 * void some_function()
2121 * my_desc = eet_data_descriptor_stream_new(&eddc);
2122 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_number",
2123 * a_number, EET_T_INT);
2124 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_string",
2125 * a_string, EET_T_STRING);
2126 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.other_num",
2127 * sub.other_num, EET_T_INT);
2128 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.one_more",
2129 * sub.one_more", EET_T_INT);
2134 * But this is not what we are here for today. When we talk about nested
2135 * structures, what we really want are things like lists and hashes to be
2136 * taken into consideration automatically, and all their contents saved and
2137 * loaded just like ordinary integers and strings are.
2139 * And of course, Eet can do that, and considering the work it saves you as a
2140 * programmer, we could say it's even easier to do than handling just integers.
2142 * Let's begin with our example then, which is not all too different from the
2143 * simple one introduced earlier.
2145 * We won't ignore the headers this time to show how easy it is to use Eina
2146 * data types with Eet, but we'll still skip most of the code that is not
2147 * pertinent to what we want to show now, but as usual, you can get it full
2148 * by following @ref eet-data-nested.c "this link".
2150 * @dontinclude eet-data-nested.c
2153 * @skip typedef struct
2154 * @until } My_Conf_Subtype
2156 * Extremely similar to our previous example. Just a new struct in there, and
2157 * a pointer to a list in the one we already had. Handling a list of subtypes
2158 * is easy on our program, but now we'll see what Eet needs to work with them
2159 * (Hint: it's easy too).
2160 * @skip _my_conf_descriptor
2161 * @until _my_conf_sub_descriptor
2163 * Since we have two structures now, it's only natural that we'll need two
2164 * descriptors. One for each, which will be defined exactly as before.
2167 * @skip EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET
2168 * @until _my_conf_sub_descriptor
2170 * We create our descriptors, each for one type, and as before, we are going to
2171 * use a simple macro to set their contents, to save on typing.
2173 * @until EET_T_UCHAR
2175 * So far, nothing new. We have our descriptors and we know already how to
2176 * save them separately. But what we want is to link them together, and even
2177 * more so, we want our main type to hold a list of more than one of the new
2178 * sub type. So how do we do that?
2180 * Simple enough, we tell Eet that our main descriptor will hold a list, of
2181 * which each node will point to some type described by our new descriptor.
2182 * @skip EET_DATA_DESCRIPTOR_ADD_LIST
2183 * @until _my_conf_sub_descriptor
2185 * And that's all. We are closing the function now so as to not leave dangling
2186 * curly braces, but there's nothing more to show in this example. Only other
2187 * additions are the necessary code to free our new data, but you can see it
2188 * in the full code listing.
2193 * @page eet_data_file_descriptor Advanced use of Eet Data Descriptors
2195 * A real life example is usually the best way to see how things are used,
2196 * but they also involve a lot more code than what needs to be shown, so
2197 * instead of going that way, we'll be borrowing some pieces from one in
2198 * the following example. It's been slightly modified from the original
2199 * source to show more of the varied ways in which Eet can handle our data.
2201 * @ref eet-data-file_descriptor_01.c "This example" shows a cache of user
2202 * accounts and messages received, and it's a bit more interactive than
2203 * previous examples.
2205 * Let's begin by looking at the structures we'll be using. First we have
2206 * one to define the messages the user receives and one for the one he posts.
2207 * Straight forward and nothing new here.
2208 * @dontinclude eet-data-file_descriptor_01.c
2212 * One more to declare the account itself. This one will contain a list of
2213 * all messages received, and the posts we make ourselves will be kept in an
2214 * array. No special reason other than to show how to use arrays with Eet.
2217 * Finally, the main structure to hold our cache of accounts. We'll be looking
2218 * for these accounts by their names, so let's keep them in a hash, using
2219 * that name as the key.
2222 * As explained before, we need one descriptor for each struct we want Eet
2223 * to handle, but this time we also want to keep around our Eet file and its
2224 * string dictionary. You will see why in a moment.
2225 * @skip Eet_Data_Descriptor
2226 * @until _my_post_descriptor
2228 * @until Eet_Dictionary
2230 * The differences begin now. They aren't much, but we'll be creating our
2231 * descriptors differently. Things can be added to our cache, but we won't
2232 * be modifying the current contents, so we can consider the data read from
2233 * it to be read-only, and thus allow Eet to save time and memory by not
2234 * duplicating thins unnecessary.
2236 * @until _my_post_descriptor
2238 * As the comment in the code explains, we are asking Eet to give us strings
2239 * directly from the mapped file, which avoids having to load it in memory
2240 * and data duplication.
2241 * Of course, there are things to take into account when doing things this
2242 * way, and they will be mentioned as we encounter those special cases.
2244 * Next comes the actual description of our data, just like we did in the
2245 * previous examples.
2251 * And the account struct's description doesn't add much new, but it's worth
2254 * @until _my_post_descriptor
2256 * How to add a list we've seen before, but now we are also adding an array.
2257 * There's nothing really special about it, but it's important to note that
2258 * the EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY is used to add arrays of variable
2259 * length to a descriptor. That is, arrays just like the one we defined.
2260 * Since there's no way in C to know how long they are, we need to keep
2261 * track of the count ourselves and Eet needs to know how to do so as well.
2262 * That's what the @p posts_count member of our struct is for. When adding
2263 * our array member, this macro will look for another variable in the struct
2264 * named just like the array, but with @p _count attached to the end.
2265 * When saving our data, Eet will know how many elements the array contains
2266 * by looking into this count variable. When loading back from a file, this
2267 * variable will be set to the right number of elements.
2269 * Another option for arrays is to use EET_DATA_DESCRIPTOR_ADD_ARRAY, which
2270 * takes care of fixed sized arrays.
2271 * For example, let's suppose that we want to keep track of only the last
2272 * ten posts the user sent, and we declare our account struct as follows
2278 * Eina_List *messages;
2279 * My_Post posts[10];
2282 * Then we would add the array to our descriptor with
2284 * EET_DATA_DESCRIPTOR_ADD_ARRAY(_my_account_descriptor, My_Account, "posts",
2285 * posts, _my_post_descriptor);
2288 * Notice how this time we don't have a @p posts_count variable in our struct.
2289 * We could have it for the program to keep track of how many posts the
2290 * array actually contains, but Eet no longer needs it. Being defined that
2291 * way the array is already taking up all the memory needed for the ten
2292 * elements, and it is possible in C to determine how much it is in code.
2293 * When saving our data, Eet will just dump the entire memory blob into the
2294 * file, regardless of how much of it is really used. So it's important to
2295 * take into consideration this kind of things when defining your data types.
2296 * Each has its uses, its advantages and disadvantages and it's up to you
2297 * to decide which to use.
2299 * Now, going back to our example, we have to finish adding our data to the
2300 * descriptors. We are only missing the main one for the cache, which
2301 * contains our hash of accounts.
2302 * Unless you are using your own hash functions when setting the descriptor
2303 * class, always use hashes with string type keys.
2307 * If you remember, we told Eet not to duplicate memory when possible at the
2308 * time of loading back our data. But this doesn't mean everything will be
2309 * loaded straight from disk and we don't have to worry about freeing it.
2310 * Data in the Eet file is compressed and encoded, so it still needs to be
2311 * decoded and memory will be allocated to convert it back into something we
2312 * can use. We also need to take care of anything we add in the current
2313 * instance of the program.
2314 * To summarize, any string we get from Eet is likely to be a pointer to the
2315 * internal dictionary, and trying to free it will, in the best case, crash
2316 * our application right away.
2318 * So how do we know if we have to free a string? We check if it's part of
2319 * the dictionary, and if it's not there we can be sure it's safe to get
2326 * See how this is used when adding a new message to our cache.
2327 * @skip static My_Message
2332 * Skipping all the utility functions used by our program (remember you can
2333 * look at the full example @ref eet-data-file_descriptor_01.c "here") we get to
2334 * our cache loading code. Nothing out of the ordinary at first, just the
2335 * same old open file, read data using our main descriptor to decode it
2336 * into something we can use and check version of loaded data and if it doesn't
2337 * match, do something accordingly.
2338 * @skip static My_Cache
2343 * Then comes the interesting part. Remember how we kept two more global
2344 * variables with our descriptors? One of them we already used to check if
2345 * it was right to free a string or not, but we didn't know where it came from.
2346 * Loading our data straight from the mmapped file means that we can't close
2347 * it until we are done using it, so we need to keep its handler around until
2348 * then. It also means that any changes done to the file can, and will,
2349 * invalidate all our pointers to the file backed data, so if we add something
2350 * and save the file, we need to reload our cache.
2352 * Thus our load function checks if we had an open file, if there is it gets
2353 * closed and our variable is updated to the new handler. Then we get the
2354 * string dictionary we use to check if a string is part of it or not.
2355 * Updating any references to the cache data is up you as a programmer to
2356 * handle properly, there's nothing Eet can do in this situation.
2359 * The save function doesn't have anything new, and all that's left after it
2360 * is the main program, which doesn't really have anything of interest within
2361 * the scope of what we are learning.
2365 * @addtogroup Eet_Data_Group
2368 #define EET_T_UNKNOW 0 /**< Unknown data encoding type */
2369 #define EET_T_CHAR 1 /**< Data type: char */
2370 #define EET_T_SHORT 2 /**< Data type: short */
2371 #define EET_T_INT 3 /**< Data type: int */
2372 #define EET_T_LONG_LONG 4 /**< Data type: long long */
2373 #define EET_T_FLOAT 5 /**< Data type: float */
2374 #define EET_T_DOUBLE 6 /**< Data type: double */
2375 #define EET_T_UCHAR 7 /**< Data type: unsigned char */
2376 #define EET_T_USHORT 8 /**< Data type: unsigned short */
2377 #define EET_T_UINT 9 /**< Data type: unsigned int */
2378 #define EET_T_ULONG_LONG 10 /**< Data type: unsigned long long */
2379 #define EET_T_STRING 11 /**< Data type: char * */
2380 #define EET_T_INLINED_STRING 12 /**< Data type: char * (but compressed inside the resulting eet) */
2381 #define EET_T_NULL 13 /**< Data type: (void *) (only use it if you know why) */
2382 #define EET_T_F32P32 14 /**< Data type: fixed point 32.32 */
2383 #define EET_T_F16P16 15 /**< Data type: fixed point 16.16 */
2384 #define EET_T_F8P24 16 /**< Data type: fixed point 8.24 */
2385 #define EET_T_VALUE 17 /**< Data type: pointer to Eina_Value @since 1.8 */
2386 #define EET_T_LAST 18 /**< Last data type */
2388 #define EET_G_UNKNOWN 100 /**< Unknown group data encoding type */
2389 #define EET_G_ARRAY 101 /**< Fixed size array group type */
2390 #define EET_G_VAR_ARRAY 102 /**< Variable size array group type */
2391 #define EET_G_LIST 103 /**< Linked list group type */
2392 #define EET_G_HASH 104 /**< Hash table group type */
2393 #define EET_G_UNION 105 /**< Union group type */
2394 #define EET_G_VARIANT 106 /**< Selectable subtype group */
2395 #define EET_G_UNKNOWN_NESTED 107 /**< Unknown nested group type. @since 1.8 */
2396 #define EET_G_LAST 108 /**< Last group type */
2398 #define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */
2401 * @typedef Eet_Data_Descriptor
2403 * Opaque handle that have information on a type members.
2405 * Descriptors are created using an #Eet_Data_Descriptor_Class, and they
2406 * describe the contents of the structure that will be serialized by Eet.
2407 * Not all members need be described by it, just those that should be handled
2408 * by Eet. This way it's possible to have one structure with both data to be
2409 * saved to a file, like application configuration, and runtime information
2410 * that would be meaningless to store, but is appropriate to keep together
2411 * during the program execution.
2412 * The members are added by means of
2413 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(),
2414 * EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH()
2415 * or eet_data_descriptor_element_add().
2417 * @see eet_data_descriptor_stream_new()
2418 * @see eet_data_descriptor_file_new()
2419 * @see eet_data_descriptor_free()
2421 typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor;
2424 * @def EET_DATA_DESCRIPTOR_CLASS_VERSION
2425 * The version of #Eet_Data_Descriptor_Class at the time of the
2426 * distribution of the sources. One should define this to its
2427 * version member so it is compatible with abi changes, or at least
2428 * will not crash with them.
2430 #define EET_DATA_DESCRIPTOR_CLASS_VERSION 4
2433 * @typedef Eet_Data_Descriptor_Class
2435 * Instructs Eet about memory management for different needs under
2436 * serialization and parse process.
2438 typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
2440 typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt);
2442 typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size);
2443 typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem);
2444 typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str);
2445 typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str);
2446 typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l);
2447 typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d);
2448 typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l);
2449 typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l);
2450 typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt);
2451 typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d);
2452 typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h);
2453 typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str);
2454 typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str);
2455 typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow);
2456 typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow);
2457 typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size);
2458 typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem);
2460 * @struct _Eet_Data_Descriptor_Class
2462 * Instructs Eet about memory management for different needs under
2463 * serialization and parse process.
2465 * The list and hash methods match the Eina API, so for a more detailed
2466 * reference on them, look at the Eina_List and Eina_Hash documentation,
2468 * For the most part these will be used with the standard Eina functions,
2469 * so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
2470 * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything
2473 struct _Eet_Data_Descriptor_Class
2475 int version; /**< ABI version. Should always be set to #EET_DATA_DESCRIPTOR_CLASS_VERSION */
2476 const char *name; /**< Name of the user data type to be serialized */
2477 int size; /**< Size in bytes of the user data type to be serialized */
2480 Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to allocate memory (usually malloc()) */
2481 Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free memory (usually free()) */
2482 Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to allocate a string */
2483 Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a string */
2484 Eet_Descriptor_List_Next_Callback list_next; /**< how to iterate to the next element of a list. Receives and should return the list node. */
2485 Eet_Descriptor_List_Append_Callback list_append; /**< how to append data @p d to list which head node is @p l */
2486 Eet_Descriptor_List_Data_Callback list_data; /**< retrieves the data from node @p l */
2487 Eet_Descriptor_List_Free_Callback list_free; /**< free all the nodes from the list which head node is @p l */
2488 Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates over all elements in the hash @p h in no specific order */
2489 Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new data @p d with key @p k in hash @p h */
2490 Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all entries from the hash @p h */
2491 Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */
2492 Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to free a string returned by str_direct_alloc */
2493 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. */
2494 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 */
2495 Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to allocate memory for array (usually malloc()) */
2496 Eet_Descriptor_Array_Free_Callback array_free; /**< how to free memory for array (usually free()) */
2505 * Create a new empty data structure descriptor.
2506 * @param name The string name of this data structure (most be a
2507 * global constant and never change).
2508 * @param size The size of the struct (in bytes).
2509 * @param func_list_next The function to get the next list node.
2510 * @param func_list_append The function to append a member to a list.
2511 * @param func_list_data The function to get the data from a list node.
2512 * @param func_list_free The function to free an entire linked list.
2513 * @param func_hash_foreach The function to iterate through all
2514 * hash table entries.
2515 * @param func_hash_add The function to add a member to a hash table.
2516 * @param func_hash_free The function to free an entire hash table.
2517 * @return A new empty data descriptor.
2519 * This function creates a new data descriptor and returns a handle to the
2520 * new data descriptor. On creation it will be empty, containing no contents
2521 * describing anything other than the shell of the data structure.
2523 * You add structure members to the data descriptor using the macros
2524 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
2525 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
2526 * adding to the description.
2528 * Once you have described all the members of a struct you want loaded, or
2529 * saved eet can load and save those members for you, encode them into
2530 * endian-independent serialised data chunks for transmission across a
2531 * a network or more.
2533 * The function pointers to the list and hash table functions are only
2534 * needed if you use those data types, else you can pass NULL instead.
2537 * @ingroup Eet_Data_Group
2539 * @deprecated use eet_data_descriptor_stream_new() or
2540 * eet_data_descriptor_file_new()
2542 EINA_DEPRECATED EAPI Eet_Data_Descriptor *
2543 eet_data_descriptor_new(const char *name,
2545 Eet_Descriptor_List_Next_Callback func_list_next,
2546 Eet_Descriptor_List_Append_Callback func_list_append,
2547 Eet_Descriptor_List_Data_Callback func_list_data,
2548 Eet_Descriptor_List_Free_Callback func_list_free,
2549 Eet_Descriptor_Hash_Foreach_Callback func_hash_foreach,
2550 Eet_Descriptor_Hash_Add_Callback func_hash_add,
2551 Eet_Descriptor_Hash_Free_Callback func_hash_free);
2555 * moving to this api from the old above. this will break things when the
2556 * move happens - but be warned
2558 EINA_DEPRECATED EAPI Eet_Data_Descriptor *
2559 eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc);
2560 EINA_DEPRECATED EAPI Eet_Data_Descriptor *
2561 eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc);
2564 * This function creates a new data descriptor and returns a handle to the
2565 * new data descriptor. On creation it will be empty, containing no contents
2566 * describing anything other than the shell of the data structure.
2567 * @param eddc The class from where to create the data descriptor.
2568 * @return A handle to the new data descriptor.
2570 * You add structure members to the data descriptor using the macros
2571 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
2572 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
2573 * adding to the description.
2575 * Once you have described all the members of a struct you want loaded or
2576 * saved, eet can load and save those members for you, encode them into
2577 * endian-independent serialised data chunks for transmission across a
2580 * This function specially ignores str_direct_alloc and str_direct_free. It
2581 * is useful when the eet_data you are reading doesn't have a dictionary,
2582 * like network stream or IPC. It also mean that all string will be allocated
2583 * and duplicated in memory.
2586 * @ingroup Eet_Data_Group
2588 EAPI Eet_Data_Descriptor *
2589 eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc);
2592 * This function creates a new data descriptor and returns a handle to the
2593 * new data descriptor. On creation it will be empty, containing no contents
2594 * describing anything other than the shell of the data structure.
2595 * @param eddc The class from where to create the data descriptor.
2596 * @return A handle to the new data descriptor.
2598 * You add structure members to the data descriptor using the macros
2599 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
2600 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
2601 * adding to the description.
2603 * Once you have described all the members of a struct you want loaded or
2604 * saved, eet can load and save those members for you, encode them into
2605 * endian-independent serialised data chunks for transmission across a
2606 * a network or more.
2608 * This function uses str_direct_alloc and str_direct_free. It is
2609 * useful when the eet_data you are reading come from a file and
2610 * have a dictionary. This will reduce memory use and improve the
2611 * possibility for the OS to page this string out.
2612 * However, the load speed and memory saving comes with some drawbacks to keep
2613 * in mind. If you never modify the contents of the structures loaded from
2614 * the file, all you need to remember is that closing the eet file will make
2615 * the strings go away. On the other hand, should you need to free a string,
2616 * before doing so you have to verify that it's not part of the eet dictionary.
2617 * You can do this in the following way, assuming @p ef is a valid Eet_File
2618 * and @p str is a string loaded from said file.
2621 * void eet_string_free(Eet_File *ef, const char *str)
2623 * Eet_Dictionary *dict = eet_dictionary_get(ef);
2624 * if (dict && eet_dictionary_string_check(dict, str))
2626 * // The file contains a dictionary and the given string is a part of
2627 * // of it, so we can't free it, just return.
2630 * // We assume eina_stringshare was used on the descriptor
2631 * eina_stringshare_del(str);
2636 * @ingroup Eet_Data_Group
2638 EAPI Eet_Data_Descriptor *
2639 eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc);
2642 * This function is an helper that set all the parameters of an
2643 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2645 * @param eddc The Eet_Data_Descriptor_Class you want to set.
2646 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
2647 * @param name The name of the structure described by this class.
2648 * @param size The size of the structure described by this class.
2649 * @return EINA_TRUE if the structure was correctly set (The only
2650 * reason that could make it fail is if you did give wrong
2653 * @note Unless there's a very specific reason to use this function directly,
2654 * the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
2657 * @ingroup Eet_Data_Group
2660 eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
2661 unsigned int eddc_size,
2666 * This macro is an helper that set all the parameter of an
2667 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2669 * @param clas The Eet_Data_Descriptor_Class you want to set.
2670 * @param type The type of the structure described by this class.
2671 * @return EINA_TRUE if the structure was correctly set (The only
2672 * reason that could make it fail is if you did give wrong
2675 * @see eet_data_descriptor_stream_new
2677 * @ingroup Eet_Data_Group
2679 #define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
2680 (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
2683 * This function is an helper that set all the parameter of an
2684 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2686 * @param eddc The Eet_Data_Descriptor_Class you want to set.
2687 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
2688 * @param name The name of the structure described by this class.
2689 * @param size The size of the structure described by this class.
2690 * @return EINA_TRUE if the structure was correctly set (The only
2691 * reason that could make it fail is if you did give wrong
2694 * @note Unless there's a very specific reason to use this function directly,
2695 * the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
2698 * @ingroup Eet_Data_Group
2701 eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
2702 unsigned int eddc_size,
2707 * This macro is an helper that set all the parameter of an
2708 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2710 * @param clas The Eet_Data_Descriptor_Class you want to set.
2711 * @param type The type of the structure described by this class.
2712 * @return EINA_TRUE if the structure was correctly set (The only
2713 * reason that could make it fail is if you did give wrong
2716 * @see eet_data_descriptor_file_new
2718 * @ingroup Eet_Data_Group
2720 #define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
2721 (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
2724 * This function frees a data descriptor when it is not needed anymore.
2725 * @param edd The data descriptor to free.
2727 * This function takes a data descriptor handle as a parameter and frees all
2728 * data allocated for the data descriptor and the handle itself. After this
2729 * call the descriptor is no longer valid.
2732 * @ingroup Eet_Data_Group
2735 eet_data_descriptor_free(Eet_Data_Descriptor *edd);
2738 * This function returns the name of a data descriptor.
2741 * @ingroup Eet_Data_Group
2743 EAPI const char *eet_data_descriptor_name_get(const Eet_Data_Descriptor *edd);
2746 * This function is an internal used by macros.
2748 * This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(),
2749 * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is
2750 * complex to use by hand and should be left to be used by the macros, and
2751 * thus is not documented.
2753 * @param edd The data descriptor handle to add element (member).
2754 * @param name The name of element to be serialized.
2755 * @param type The type of element to be serialized, like
2756 * #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a
2757 * group, list or hash.
2758 * @param group_type If element type is #EET_T_UNKNOW, then the @p
2759 * group_type will specify if it is a list (#EET_G_LIST),
2760 * array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then
2761 * the member is a subtype (pointer to another type defined by
2762 * another #Eet_Data_Descriptor).
2763 * @param offset byte offset inside the source memory to be serialized.
2764 * @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY).
2765 * @param counter_name variable that defines the name of number of elements.
2766 * @param subtype If contains a subtype, then its data descriptor.
2769 * @ingroup Eet_Data_Group
2772 eet_data_descriptor_element_add(Eet_Data_Descriptor *edd,
2777 /* int count_offset, */
2779 const char *counter_name,
2780 Eet_Data_Descriptor *subtype);
2783 * Read a data structure from an eet file and decodes it.
2784 * @param ef The eet file handle to read from.
2785 * @param edd The data descriptor handle to use when decoding.
2786 * @param name The key the data is stored under in the eet file.
2787 * @return A pointer to the decoded data structure.
2789 * This function decodes a data structure stored in an eet file, returning
2790 * a pointer to it if it decoded successfully, or NULL on failure. This
2791 * can save a programmer dozens of hours of work in writing configuration
2792 * file parsing and writing code, as eet does all that work for the program
2793 * and presents a program-friendly data structure, just as the programmer
2794 * likes. Eet can handle members being added or deleted from the data in
2795 * storage and safely zero-fills unfilled members if they were not found
2796 * in the data. It checks sizes and headers whenever it reads data, allowing
2797 * the programmer to not worry about corrupt data.
2799 * Once a data structure has been described by the programmer with the
2800 * fields they wish to save or load, storing or retrieving a data structure
2801 * from an eet file, or from a chunk of memory is as simple as a single
2804 * @see eet_data_read_cipher()
2807 * @ingroup Eet_Data_Group
2810 eet_data_read(Eet_File *ef,
2811 Eet_Data_Descriptor *edd,
2815 * Write a data structure from memory and store in an eet file.
2816 * @param ef The eet file handle to write to.
2817 * @param edd The data descriptor to use when encoding.
2818 * @param name The key to store the data under in the eet file.
2819 * @param data A pointer to the data structure to save and encode.
2820 * @param compress Compression flags for storage.
2821 * @return bytes written on successful write, 0 on failure.
2823 * This function is the reverse of eet_data_read(), saving a data structure
2824 * to an eet file. The file must have been opening in write mode and the data
2825 * will be kept in memory until the file is either closed or eet_sync() is
2826 * called to flush any unwritten changes.
2828 * @see eet_data_write_cipher()
2831 * @ingroup Eet_Data_Group
2834 eet_data_write(Eet_File *ef,
2835 Eet_Data_Descriptor *edd,
2840 typedef void (*Eet_Dump_Callback)(void *data, const char *str);
2843 * Dump an eet encoded data structure into ascii text
2844 * @param data_in The pointer to the data to decode into a struct.
2845 * @param size_in The size of the data pointed to in bytes.
2846 * @param dumpfunc The function to call passed a string when new
2847 * data is converted to text
2848 * @param dumpdata The data to pass to the @p dumpfunc callback.
2849 * @return 1 on success, 0 on failure
2851 * This function will take a chunk of data encoded by
2852 * eet_data_descriptor_encode() and convert it into human readable
2853 * ascii text. It does this by calling the @p dumpfunc callback
2854 * for all new text that is generated. This callback should append
2855 * to any existing text buffer and will be passed the pointer @p
2856 * dumpdata as a parameter as well as a string with new text to be
2862 * void output(void *data, const char *string)
2864 * printf("%s", string);
2867 * void dump(const char *file)
2873 * f = fopen(file, "r");
2874 * fseek(f, 0, SEEK_END);
2877 * data = malloc(len);
2878 * fread(data, len, 1, f);
2880 * eet_data_text_dump(data, len, output, NULL);
2884 * @see eet_data_text_dump_cipher()
2887 * @ingroup Eet_Data_Group
2890 eet_data_text_dump(const void *data_in,
2892 Eet_Dump_Callback dumpfunc,
2896 * Take an ascii encoding from eet_data_text_dump() and re-encode in binary.
2897 * @param text The pointer to the string data to parse and encode.
2898 * @param textlen The size of the string in bytes (not including 0
2900 * @param size_ret This gets filled in with the encoded data blob
2902 * @return The encoded data on success, NULL on failure.
2904 * This function will parse the string pointed to by @p text and return
2905 * an encoded data lump the same way eet_data_descriptor_encode() takes an
2906 * in-memory data struct and encodes into a binary blob. @p text is a normal
2909 * @see eet_data_text_undump_cipher()
2912 * @ingroup Eet_Data_Group
2915 eet_data_text_undump(const char *text,
2920 * Dump an eet encoded data structure from an eet file into ascii text
2921 * @param ef A valid eet file handle.
2922 * @param name Name of the entry. eg: "/base/file_i_want".
2923 * @param dumpfunc The function to call passed a string when new
2924 * data is converted to text
2925 * @param dumpdata The data to pass to the @p dumpfunc callback.
2926 * @return 1 on success, 0 on failure
2928 * This function will take an open and valid eet file from
2929 * eet_open() request the data encoded by
2930 * eet_data_descriptor_encode() corresponding to the key @p name
2931 * and convert it into human readable ascii text. It does this by
2932 * calling the @p dumpfunc callback for all new text that is
2933 * generated. This callback should append to any existing text
2934 * buffer and will be passed the pointer @p dumpdata as a parameter
2935 * as well as a string with new text to be appended.
2937 * @see eet_data_dump_cipher()
2940 * @ingroup Eet_Data_Group
2943 eet_data_dump(Eet_File *ef,
2945 Eet_Dump_Callback dumpfunc,
2949 * Take an ascii encoding from eet_data_dump() and re-encode in binary.
2950 * @param ef A valid eet file handle.
2951 * @param name Name of the entry. eg: "/base/file_i_want".
2952 * @param text The pointer to the string data to parse and encode.
2953 * @param textlen The size of the string in bytes (not including 0
2955 * @param compress Compression flags (1 == compress, 0 = don't compress).
2956 * @return 1 on success, 0 on failure
2958 * This function will parse the string pointed to by @p text,
2959 * encode it the same way eet_data_descriptor_encode() takes an
2960 * in-memory data struct and encodes into a binary blob.
2962 * The data (optionally compressed) will be in ram, pending a flush to
2963 * disk (it will stay in ram till the eet file handle is closed though).
2965 * @see eet_data_undump_cipher()
2968 * @ingroup Eet_Data_Group
2971 eet_data_undump(Eet_File *ef,
2978 * Decode a data structure from an arbitrary location in memory.
2979 * @param edd The data descriptor to use when decoding.
2980 * @param data_in The pointer to the data to decode into a struct.
2981 * @param size_in The size of the data pointed to in bytes.
2982 * @return NULL on failure, or a valid decoded struct pointer on success.
2984 * This function will decode a data structure that has been encoded using
2985 * eet_data_descriptor_encode(), and return a data structure with all its
2986 * elements filled out, if successful, or NULL on failure.
2988 * The data to be decoded is stored at the memory pointed to by @p data_in,
2989 * and is described by the descriptor pointed to by @p edd. The data size is
2990 * passed in as the value to @p size_in, ande must be greater than 0 to
2993 * This function is useful for decoding data structures delivered to the
2994 * application by means other than an eet file, such as an IPC or socket
2995 * connection, raw files, shared memory etc.
2997 * Please see eet_data_read() for more information.
2999 * @see eet_data_descriptor_decode_cipher()
3002 * @ingroup Eet_Data_Group
3005 eet_data_descriptor_decode(Eet_Data_Descriptor *edd,
3006 const void *data_in,
3010 * Encode a dsata struct to memory and return that encoded data.
3011 * @param edd The data descriptor to use when encoding.
3012 * @param data_in The pointer to the struct to encode into data.
3013 * @param size_ret pointer to the an int to be filled with the decoded size.
3014 * @return NULL on failure, or a valid encoded data chunk on success.
3016 * This function takes a data structutre in memory and encodes it into a
3017 * serialised chunk of data that can be decoded again by
3018 * eet_data_descriptor_decode(). This is useful for being able to transmit
3019 * data structures across sockets, pipes, IPC or shared file mechanisms,
3020 * without having to worry about memory space, machine type, endianness etc.
3022 * The parameter @p edd must point to a valid data descriptor, and
3023 * @p data_in must point to the right data structure to encode. If not, the
3024 * encoding may fail.
3026 * On success a non NULL valid pointer is returned and what @p size_ret
3027 * points to is set to the size of this decoded data, in bytes. When the
3028 * encoded data is no longer needed, call free() on it. On failure NULL is
3029 * returned and what @p size_ret points to is set to 0.
3031 * Please see eet_data_write() for more information.
3033 * @see eet_data_descriptor_encode_cipher()
3036 * @ingroup Eet_Data_Group
3039 eet_data_descriptor_encode(Eet_Data_Descriptor *edd,
3040 const void *data_in,
3044 * Add a basic data element to a data descriptor.
3045 * @param edd The data descriptor to add the type to.
3046 * @param struct_type The type of the struct.
3047 * @param name The string name to use to encode/decode this member
3048 * (must be a constant global and never change).
3049 * @param member The struct member itself to be encoded.
3050 * @param type The type of the member to encode.
3052 * This macro is a convenience macro provided to add a member to
3053 * the data descriptor @p edd. The type of the structure is
3054 * provided as the @p struct_type parameter (for example: struct
3055 * my_struct). The @p name parameter defines a string that will be
3056 * used to uniquely name that member of the struct (it is suggested
3057 * to use the struct member itself). The @p member parameter is
3058 * the actual struct member itself (for example: values), and @p type is the
3059 * basic data type of the member which must be one of: EET_T_CHAR, EET_T_SHORT,
3060 * EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR,
3061 * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING.
3064 * @ingroup Eet_Data_Group
3066 #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
3068 struct_type ___ett; \
3069 eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
3070 (char *)(& (___ett.member)) - \
3071 (char *)(& (___ett)), \
3072 0, /* 0, */ NULL, NULL); \
3076 * Add a sub-element type to a data descriptor
3077 * @param edd The data descriptor to add the type to.
3078 * @param struct_type The type of the struct.
3079 * @param name The string name to use to encode/decode this member
3080 * (must be a constant global and never change).
3081 * @param member The struct member itself to be encoded.
3082 * @param subtype The type of sub-type struct to add.
3084 * This macro lets you easily add a sub-type (a struct that's pointed to
3085 * by this one). All the parameters are the same as for
3086 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception.
3087 * This must be the data descriptor of the struct that is pointed to by
3091 * @ingroup Eet_Data_Group
3093 #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
3095 struct_type ___ett; \
3096 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
3097 (char *)(& (___ett.member)) - \
3098 (char *)(& (___ett)), \
3099 0, /* 0, */ NULL, subtype); \
3103 * Add a nested sub-element type to a data descriptor
3104 * @param edd The data descriptor to add the type to.
3105 * @param struct_type The type of the struct.
3106 * @param name The string name to use to encode/decode this member
3107 * (must be a constant global and never change).
3108 * @param member The struct member itself to be encoded.
3109 * @param subtype The type of sub-type struct to add.
3111 * This macro lets you easily add a sub-type: a struct that is nested into
3112 * this one. If your data is pointed by this element instead of being nested,
3113 * you should use EET_DATA_DESCRIPTOR_ADD_SUB().
3114 * All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_SUB().
3117 * @ingroup Eet_Data_Group
3119 #define EET_DATA_DESCRIPTOR_ADD_SUB_NESTED(edd, struct_type, name, member, subtype) \
3121 struct_type ___ett; \
3122 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN_NESTED, \
3123 (char *)(& (___ett.member)) - \
3124 (char *)(& (___ett)), \
3125 0, /* 0, */ NULL, subtype); \
3129 * Add a linked list type to a data descriptor
3130 * @param edd The data descriptor to add the type to.
3131 * @param struct_type The type of the struct.
3132 * @param name The string name to use to encode/decode this member
3133 * (must be a constant global and never change).
3134 * @param member The struct member itself to be encoded.
3135 * @param subtype The type of linked list member to add.
3137 * This macro lets you easily add a linked list of other data types. All the
3138 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
3139 * @p subtype being the exception. This must be the data descriptor of the
3140 * element that is in each member of the linked list to be stored.
3143 * @ingroup Eet_Data_Group
3145 #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \
3147 struct_type ___ett; \
3148 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
3149 (char *)(& (___ett.member)) - \
3150 (char *)(& (___ett)), \
3151 0, /* 0, */ NULL, subtype); \
3155 * Add a linked list of string to a data descriptor
3156 * @param edd The data descriptor to add the type to.
3157 * @param struct_type The type of the struct.
3158 * @param name The string name to use to encode/decode this member
3159 * (must be a constant global and never change).
3160 * @param member The struct member itself to be encoded.
3162 * This macro lets you easily add a linked list of char *. All the
3163 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
3166 * @ingroup Eet_Data_Group
3168 #define EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member) \
3170 struct_type ___ett; \
3171 eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_LIST, \
3172 (char *)(& (___ett.member)) - \
3173 (char *)(& (___ett)), \
3174 0, /* 0, */ NULL, NULL); \
3178 * Add a hash type to a data descriptor
3179 * @param edd The data descriptor to add the type to.
3180 * @param struct_type The type of the struct.
3181 * @param name The string name to use to encode/decode this member
3182 * (must be a constant global and never change).
3183 * @param member The struct member itself to be encoded.
3184 * @param subtype The type of hash member to add.
3186 * This macro lets you easily add a hash of other data types. All the
3187 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
3188 * @p subtype being the exception. This must be the data descriptor of the
3189 * element that is in each member of the hash to be stored.
3190 * The hash keys must be strings.
3193 * @ingroup Eet_Data_Group
3195 #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \
3197 struct_type ___ett; \
3198 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \
3199 (char *)(& (___ett.member)) - \
3200 (char *)(& (___ett)), \
3201 0, /* 0, */ NULL, subtype); \
3205 * Add a hash of string to a data descriptor
3206 * @param edd The data descriptor to add the type to.
3207 * @param struct_type The type of the struct.
3208 * @param name The string name to use to encode/decode this member
3209 * (must be a constant global and never change).
3210 * @param member The struct member itself to be encoded.
3212 * This macro lets you easily add a hash of string elements. All the
3213 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH().
3216 * @ingroup Eet_Data_Group
3218 #define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \
3220 struct_type ___ett; \
3221 eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH, \
3222 (char *)(& (___ett.member)) - \
3223 (char *)(& (___ett)), \
3224 0, /* 0, */ NULL, NULL); \
3228 * Add an array of basic data elements to a data descriptor.
3229 * @param edd The data descriptor to add the type to.
3230 * @param struct_type The type of the struct.
3231 * @param name The string name to use to encode/decode this member
3232 * (must be a constant global and never change).
3233 * @param member The struct member itself to be encoded.
3234 * @param type The type of the member to encode.
3236 * This macro lets you easily add a fixed size array of basic data
3237 * types. All the parameters are the same as for
3238 * EET_DATA_DESCRIPTOR_ADD_BASIC().
3239 * The array must be defined with a fixed size in the declaration of the
3240 * struct containing it.
3243 * @ingroup Eet_Data_Group
3245 #define EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member, type) \
3247 struct_type ___ett; \
3248 eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY, \
3249 (char *)(& (___ett.member)) - \
3250 (char *)(& (___ett)), \
3251 sizeof(___ett.member) / \
3252 sizeof(___ett.member[0]), \
3257 * Add a variable array of basic data elements to a data descriptor.
3258 * @param edd The data descriptor to add the type to.
3259 * @param struct_type The type of the struct.
3260 * @param name The string name to use to encode/decode this member
3261 * (must be a constant global and never change).
3262 * @param member The struct member itself to be encoded.
3263 * @param type The type of the member to encode.
3265 * This macro lets you easily add a variable size array of basic data
3266 * types. All the parameters are the same as for
3267 * EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have
3268 * a struct member (of type EET_T_INT) called member_count (note the
3269 * _count appended to the member) that holds the number of items in
3270 * the array. This array will be allocated separately to the struct it
3274 * @ingroup Eet_Data_Group
3276 #define EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, member, type) \
3278 struct_type ___ett; \
3279 eet_data_descriptor_element_add(edd, name, type, EET_G_VAR_ARRAY, \
3280 (char *)(& (___ett.member)) - \
3281 (char *)(& (___ett)), \
3282 (char *)(& (___ett.member ## _count)) - \
3283 (char *)(& (___ett)), \
3289 * Add a fixed size array type to a data descriptor
3290 * @param edd The data descriptor to add the type to.
3291 * @param struct_type The type of the struct.
3292 * @param name The string name to use to encode/decode this member
3293 * (must be a constant global and never change).
3294 * @param member The struct member itself to be encoded.
3295 * @param subtype The type of hash member to add.
3297 * This macro lets you easily add a fixed size array of other data
3298 * types. All the parameters are the same as for
3299 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
3300 * exception. This must be the data descriptor of the element that
3301 * is in each member of the array to be stored.
3302 * The array must be defined with a fixed size in the declaration of the
3303 * struct containing it.
3306 * @ingroup Eet_Data_Group
3308 #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \
3310 struct_type ___ett; \
3311 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \
3312 (char *)(& (___ett.member)) - \
3313 (char *)(& (___ett)), \
3314 /* 0, */ sizeof(___ett.member) / \
3315 sizeof(___ett.member[0]), NULL, subtype); \
3319 * Add a variable size array type to a data descriptor
3320 * @param edd The data descriptor to add the type to.
3321 * @param struct_type The type of the struct.
3322 * @param name The string name to use to encode/decode this member
3323 * (must be a constant global and never change).
3324 * @param member The struct member itself to be encoded.
3325 * @param subtype The type of hash member to add.
3327 * This macro lets you easily add a variable size array of other data
3328 * types. All the parameters are the same as for
3329 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
3330 * exception. This must be the data descriptor of the element that
3331 * is in each member of the array to be stored. This assumes you have
3332 * a struct member (of type EET_T_INT) called member_count (note the
3333 * _count appended to the member) that holds the number of items in
3334 * the array. This array will be allocated separately to the struct it
3338 * @ingroup Eet_Data_Group
3340 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \
3342 struct_type ___ett; \
3343 eet_data_descriptor_element_add(edd, \
3347 (char *)(& (___ett.member)) - \
3348 (char *)(& (___ett)), \
3349 (char *)(& (___ett.member ## _count)) - \
3350 (char *)(& (___ett)), \
3356 * Add a variable size array type to a data descriptor
3357 * @param edd The data descriptor to add the type to.
3358 * @param struct_type The type of the struct.
3359 * @param name The string name to use to encode/decode this member
3360 * (must be a constant global and never change).
3361 * @param member The struct member itself to be encoded.
3363 * This macro lets you easily add a variable size array of strings. All
3364 * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
3367 * @ingroup Eet_Data_Group
3369 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member) \
3371 struct_type ___ett; \
3372 eet_data_descriptor_element_add(edd, \
3376 (char *)(& (___ett.member)) - \
3377 (char *)(& (___ett)), \
3378 (char *)(& (___ett.member ## _count)) - \
3379 (char *)(& (___ett)), \
3385 * Add an union type to a data descriptor
3386 * @param edd The data descriptor to add the type to.
3387 * @param struct_type The type of the struct.
3388 * @param name The string name to use to encode/decode this member
3389 * (must be a constant global and never change).
3390 * @param member The struct member itself to be encoded.
3391 * @param type_member The member that give hints on what is in the union.
3392 * @param unified_type Describe all possible type the union could handle.
3394 * This macro lets you easily add an union with a member that specify what is inside.
3395 * The @p unified_type is an Eet_Data_Descriptor, but only the entry that match the name
3396 * returned by type_get will be used for each serialized data. The type_get and type_set
3397 * callback of unified_type should be defined.
3400 * @ingroup Eet_Data_Group
3401 * @see Eet_Data_Descriptor_Class
3403 #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type) \
3405 struct_type ___ett; \
3406 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, \
3407 (char *)(& (___ett.member)) - \
3408 (char *)(& (___ett)), \
3409 (char *)(& (___ett.type_member)) - \
3410 (char *)(& (___ett)), \
3411 NULL, unified_type); \
3415 * Add a automatically selectable type to a data descriptor
3416 * @param edd The data descriptor to add the type to.
3417 * @param struct_type The type of the struct.
3418 * @param name The string name to use to encode/decode this member
3419 * (must be a constant global and never change).
3420 * @param member The struct member itself to be encoded.
3421 * @param type_member The member that give hints on what is in the union.
3422 * @param unified_type Describe all possible type the union could handle.
3424 * This macro lets you easily define what the content of @p member points to depending of
3425 * the content of @p type_member. The type_get and type_set callback of unified_type should
3426 * be defined. If the the type is not know at the time of restoring it, eet will still call
3427 * type_set of @p unified_type but the pointer will be set to a serialized binary representation
3428 * of what eet know. This make it possible, to save this pointer again by just returning the string
3429 * given previously and telling it by setting unknow to EINA_TRUE.
3432 * @ingroup Eet_Data_Group
3433 * @see Eet_Data_Descriptor_Class
3435 #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type) \
3437 struct_type ___ett; \
3438 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT, \
3439 (char *)(& (___ett.member)) - \
3440 (char *)(& (___ett)), \
3441 (char *)(& (___ett.type_member)) - \
3442 (char *)(& (___ett)), \
3443 NULL, unified_type); \
3447 * Add a mapping to a data descriptor that will be used by union, variant or inherited type
3448 * @param unified_type The data descriptor to add the mapping to.
3449 * @param name The string name to get/set type.
3450 * @param subtype The matching data descriptor.
3453 * @ingroup Eet_Data_Group
3454 * @see Eet_Data_Descriptor_Class
3456 #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \
3457 eet_data_descriptor_element_add(unified_type, \
3467 * Add a mapping of a basic type to a data descriptor that will be used by a union type.
3468 * @param unified_type The data descriptor to add the mapping to.
3469 * @param name The string name to get/set type.
3470 * @param basic_type The matching basic type.
3473 * @ingroup Eet_Data_Group
3474 * @see Eet_Data_Descriptor_Class
3476 #define EET_DATA_DESCRIPTOR_ADD_MAPPING_BASIC(unified_type, name, basic_type) \
3477 eet_data_descriptor_element_add(unified_type, \
3486 * @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers
3488 * Most of the @ref Eet_Data_Group have alternative versions that
3489 * accounts for ciphers to protect their content.
3491 * @see @ref Eet_Cipher_Group
3493 * @ingroup Eet_Data_Group
3497 * Read a data structure from an eet file and decodes it using a cipher.
3498 * @param ef The eet file handle to read from.
3499 * @param edd The data descriptor handle to use when decoding.
3500 * @param name The key the data is stored under in the eet file.
3501 * @param cipher_key The key to use as cipher.
3502 * @return A pointer to the decoded data structure.
3504 * This function decodes a data structure stored in an eet file, returning
3505 * a pointer to it if it decoded successfully, or NULL on failure. This
3506 * can save a programmer dozens of hours of work in writing configuration
3507 * file parsing and writing code, as eet does all that work for the program
3508 * and presents a program-friendly data structure, just as the programmer
3509 * likes. Eet can handle members being added or deleted from the data in
3510 * storage and safely zero-fills unfilled members if they were not found
3511 * in the data. It checks sizes and headers whenever it reads data, allowing
3512 * the programmer to not worry about corrupt data.
3514 * Once a data structure has been described by the programmer with the
3515 * fields they wish to save or load, storing or retrieving a data structure
3516 * from an eet file, or from a chunk of memory is as simple as a single
3519 * @see eet_data_read()
3522 * @ingroup Eet_Data_Cipher_Group
3525 eet_data_read_cipher(Eet_File *ef,
3526 Eet_Data_Descriptor *edd,
3528 const char *cipher_key);
3531 * Read a data structure from an eet extended attribute and decodes it using a cipher.
3532 * @param filename The file to extract the extended attribute from.
3533 * @param attribute The attribute to get the data from.
3534 * @param edd The data descriptor handle to use when decoding.
3535 * @param cipher_key The key to use as cipher.
3536 * @return A pointer to the decoded data structure.
3538 * This function decodes a data structure stored in an eet extended attribute,
3539 * returning a pointer to it if it decoded successfully, or NULL on failure.
3540 * Eet can handle members being added or deleted from the data in
3541 * storage and safely zero-fills unfilled members if they were not found
3542 * in the data. It checks sizes and headers whenever it reads data, allowing
3543 * the programmer to not worry about corrupt data.
3545 * Once a data structure has been described by the programmer with the
3546 * fields they wish to save or load, storing or retrieving a data structure
3547 * from an eet file, from a chunk of memory or from an extended attribute
3548 * is as simple as a single function call.
3551 * @ingroup Eet_Data_Cipher_Group
3554 eet_data_xattr_cipher_get(const char *filename,
3555 const char *attribute,
3556 Eet_Data_Descriptor *edd,
3557 const char *cipher_key);
3560 * Write a data structure from memory and store in an eet file
3562 * @param ef The eet file handle to write to.
3563 * @param edd The data descriptor to use when encoding.
3564 * @param name The key to store the data under in the eet file.
3565 * @param cipher_key The key to use as cipher.
3566 * @param data A pointer to the data structure to save and encode.
3567 * @param compress Compression flags for storage.
3568 * @return bytes written on successful write, 0 on failure.
3570 * This function is the reverse of eet_data_read_cipher(), saving a data structure
3574 * @ingroup Eet_Data_Cipher_Group
3577 eet_data_write_cipher(Eet_File *ef,
3578 Eet_Data_Descriptor *edd,
3580 const char *cipher_key,
3585 * Write a data structure from memory and store in an eet extended attribute
3587 * @param filename The file to write the extended attribute to.
3588 * @param attribute The attribute to store the data to.
3589 * @param edd The data descriptor to use when encoding.
3590 * @param cipher_key The key to use as cipher.
3591 * @param data A pointer to the data structure to save and encode.
3592 * @param flags The policy to use when setting the data.
3593 * @return EINA_TRUE on success, EINA_FALSE on failure.
3595 * This function is the reverse of eet_data_xattr_cipher_get(), saving a data structure
3596 * to an eet extended attribute.
3599 * @ingroup Eet_Data_Cipher_Group
3602 eet_data_xattr_cipher_set(const char *filename,
3603 const char *attribute,
3604 Eet_Data_Descriptor *edd,
3605 const char *cipher_key,
3607 Eina_Xattr_Flags flags);
3610 * Dump an eet encoded data structure into ascii text using a cipher.
3611 * @param data_in The pointer to the data to decode into a struct.
3612 * @param cipher_key The key to use as cipher.
3613 * @param size_in The size of the data pointed to in bytes.
3614 * @param dumpfunc The function to call passed a string when new
3615 * data is converted to text
3616 * @param dumpdata The data to pass to the @p dumpfunc callback.
3617 * @return 1 on success, 0 on failure
3619 * This function will take a chunk of data encoded by
3620 * eet_data_descriptor_encode() and convert it into human readable
3621 * ascii text. It does this by calling the @p dumpfunc callback
3622 * for all new text that is generated. This callback should append
3623 * to any existing text buffer and will be passed the pointer @p
3624 * dumpdata as a parameter as well as a string with new text to be
3630 * void output(void *data, const char *string)
3632 * printf("%s", string);
3635 * void dump(const char *file)
3641 * f = fopen(file, "r");
3642 * fseek(f, 0, SEEK_END);
3645 * data = malloc(len);
3646 * fread(data, len, 1, f);
3648 * eet_data_text_dump_cipher(data, cipher_key, len, output, NULL);
3652 * @see eet_data_text_dump()
3655 * @ingroup Eet_Data_Cipher_Group
3658 eet_data_text_dump_cipher(const void *data_in,
3659 const char *cipher_key,
3661 Eet_Dump_Callback dumpfunc,
3665 * Take an ascii encoding from eet_data_text_dump() and re-encode
3666 * in binary using a cipher.
3667 * @param text The pointer to the string data to parse and encode.
3668 * @param cipher_key The key to use as cipher.
3669 * @param textlen The size of the string in bytes (not including 0
3671 * @param size_ret This gets filled in with the encoded data blob
3673 * @return The encoded data on success, NULL on failure.
3675 * This function will parse the string pointed to by @p text and return
3676 * an encoded data lump the same way eet_data_descriptor_encode() takes an
3677 * in-memory data struct and encodes into a binary blob. @p text is a normal
3680 * @see eet_data_text_undump()
3683 * @ingroup Eet_Data_Cipher_Group
3686 eet_data_text_undump_cipher(const char *text,
3687 const char *cipher_key,
3692 * Dump an eet encoded data structure from an eet file into ascii
3693 * text using a cipher.
3694 * @param ef A valid eet file handle.
3695 * @param name Name of the entry. eg: "/base/file_i_want".
3696 * @param cipher_key The key to use as cipher.
3697 * @param dumpfunc The function to call passed a string when new
3698 * data is converted to text
3699 * @param dumpdata The data to pass to the @p dumpfunc callback.
3700 * @return 1 on success, 0 on failure
3702 * This function will take an open and valid eet file from
3703 * eet_open() request the data encoded by
3704 * eet_data_descriptor_encode() corresponding to the key @p name
3705 * and convert it into human readable ascii text. It does this by
3706 * calling the @p dumpfunc callback for all new text that is
3707 * generated. This callback should append to any existing text
3708 * buffer and will be passed the pointer @p dumpdata as a parameter
3709 * as well as a string with new text to be appended.
3711 * @see eet_data_dump()
3714 * @ingroup Eet_Data_Cipher_Group
3717 eet_data_dump_cipher(Eet_File *ef,
3719 const char *cipher_key,
3720 Eet_Dump_Callback dumpfunc,
3724 * Take an ascii encoding from eet_data_dump() and re-encode in
3725 * binary using a cipher.
3726 * @param ef A valid eet file handle.
3727 * @param name Name of the entry. eg: "/base/file_i_want".
3728 * @param cipher_key The key to use as cipher.
3729 * @param text The pointer to the string data to parse and encode.
3730 * @param textlen The size of the string in bytes (not including 0
3732 * @param compress Compression flags (1 == compress, 0 = don't compress).
3733 * @return 1 on success, 0 on failure
3735 * This function will parse the string pointed to by @p text,
3736 * encode it the same way eet_data_descriptor_encode() takes an
3737 * in-memory data struct and encodes into a binary blob.
3739 * The data (optionally compressed) will be in ram, pending a flush to
3740 * disk (it will stay in ram till the eet file handle is closed though).
3742 * @see eet_data_undump()
3745 * @ingroup Eet_Data_Cipher_Group
3748 eet_data_undump_cipher(Eet_File *ef,
3750 const char *cipher_key,
3756 * Decode a data structure from an arbitrary location in memory
3758 * @param edd The data descriptor to use when decoding.
3759 * @param data_in The pointer to the data to decode into a struct.
3760 * @param cipher_key The key to use as cipher.
3761 * @param size_in The size of the data pointed to in bytes.
3762 * @return NULL on failure, or a valid decoded struct pointer on success.
3764 * This function will decode a data structure that has been encoded using
3765 * eet_data_descriptor_encode(), and return a data structure with all its
3766 * elements filled out, if successful, or NULL on failure.
3768 * The data to be decoded is stored at the memory pointed to by @p data_in,
3769 * and is described by the descriptor pointed to by @p edd. The data size is
3770 * passed in as the value to @p size_in, ande must be greater than 0 to
3773 * This function is useful for decoding data structures delivered to the
3774 * application by means other than an eet file, such as an IPC or socket
3775 * connection, raw files, shared memory etc.
3777 * Please see eet_data_read() for more information.
3779 * @see eet_data_descriptor_decode()
3782 * @ingroup Eet_Data_Cipher_Group
3785 eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd,
3786 const void *data_in,
3787 const char *cipher_key,
3791 * Encode a data struct to memory and return that encoded data
3793 * @param edd The data descriptor to use when encoding.
3794 * @param data_in The pointer to the struct to encode into data.
3795 * @param cipher_key The key to use as cipher.
3796 * @param size_ret pointer to the an int to be filled with the decoded size.
3797 * @return NULL on failure, or a valid encoded data chunk on success.
3799 * This function takes a data structutre in memory and encodes it into a
3800 * serialised chunk of data that can be decoded again by
3801 * eet_data_descriptor_decode(). This is useful for being able to transmit
3802 * data structures across sockets, pipes, IPC or shared file mechanisms,
3803 * without having to worry about memory space, machine type, endianess etc.
3805 * The parameter @p edd must point to a valid data descriptor, and
3806 * @p data_in must point to the right data structure to encode. If not, the
3807 * encoding may fail.
3809 * On success a non NULL valid pointer is returned and what @p size_ret
3810 * points to is set to the size of this decoded data, in bytes. When the
3811 * encoded data is no longer needed, call free() on it. On failure NULL is
3812 * returned and what @p size_ret points to is set to 0.
3814 * Please see eet_data_write() for more information.
3816 * @see eet_data_descriptor_encode()
3819 * @ingroup Eet_Data_Cipher_Group
3822 eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd,
3823 const void *data_in,
3824 const char *cipher_key,
3828 * @defgroup Eet_Node_Group Low-level Serialization Structures.
3831 * Functions that create, destroy and manipulate serialization nodes
3832 * used by @ref Eet_Data_Group.
3839 * Opaque handle to manage serialization node.
3841 typedef struct _Eet_Node Eet_Node;
3844 * @typedef Eet_Node_Data
3845 * Contains an union that can fit any kind of node.
3847 typedef struct _Eet_Node_Data Eet_Node_Data;
3850 * @struct _Eet_Node_Data
3851 * Contains an union that can fit any kind of node.
3853 struct _Eet_Node_Data
3865 unsigned long long ul;
3876 * @ingroup Eet_Node_Group
3879 eet_node_char_new(const char *name,
3884 * @ingroup Eet_Node_Group
3887 eet_node_short_new(const char *name,
3892 * @ingroup Eet_Node_Group
3895 eet_node_int_new(const char *name,
3900 * @ingroup Eet_Node_Group
3903 eet_node_long_long_new(const char *name,
3908 * @ingroup Eet_Node_Group
3911 eet_node_float_new(const char *name,
3916 * @ingroup Eet_Node_Group
3919 eet_node_double_new(const char *name,
3924 * @ingroup Eet_Node_Group
3927 eet_node_unsigned_char_new(const char *name,
3932 * @ingroup Eet_Node_Group
3935 eet_node_unsigned_short_new(const char *name,
3940 * @ingroup Eet_Node_Group
3943 eet_node_unsigned_int_new(const char *name,
3948 * @ingroup Eet_Node_Group
3951 eet_node_unsigned_long_long_new(const char *name,
3952 unsigned long long l);
3956 * @ingroup Eet_Node_Group
3959 eet_node_string_new(const char *name,
3964 * @ingroup Eet_Node_Group
3967 eet_node_inlined_string_new(const char *name,
3972 * @ingroup Eet_Node_Group
3975 eet_node_null_new(const char *name);
3979 * @ingroup Eet_Node_Group
3982 eet_node_list_new(const char *name,
3987 * @ingroup Eet_Node_Group
3990 eet_node_array_new(const char *name,
3996 * @ingroup Eet_Node_Group
3999 eet_node_var_array_new(const char *name,
4004 * @ingroup Eet_Node_Group
4007 eet_node_hash_new(const char *name,
4013 * @ingroup Eet_Node_Group
4016 eet_node_struct_new(const char *name,
4021 * @ingroup Eet_Node_Group
4024 eet_node_struct_child_new(const char *parent,
4028 * @brief Get a node's child nodes
4029 * @param node The node
4030 * @return The first child node which contains a pointer to the
4031 * next child node and the parent.
4035 eet_node_children_get(Eet_Node *node);
4038 * @brief Get the next node in a list of nodes
4039 * @param node The node
4040 * @return A node which contains a pointer to the
4041 * next child node and the parent.
4045 eet_node_next_get(Eet_Node *node);
4048 * @brief Get the parent node of a node
4049 * @param node The node
4050 * @return The parent node of @p node
4054 eet_node_parent_get(Eet_Node *node);
4058 * @ingroup Eet_Node_Group
4061 eet_node_list_append(Eet_Node *parent,
4067 * @ingroup Eet_Node_Group
4070 eet_node_struct_append(Eet_Node *parent,
4076 * @ingroup Eet_Node_Group
4079 eet_node_hash_add(Eet_Node *parent,
4086 * @ingroup Eet_Node_Group
4089 eet_node_dump(Eet_Node *n,
4091 Eet_Dump_Callback dumpfunc,
4095 * @brief Return the type of a node
4096 * @param node The node
4097 * @return The node's type (EET_T_$TYPE)
4101 eet_node_type_get(Eet_Node *node);
4104 * @brief Return the node's data
4105 * @param node The node
4106 * @return The data contained in the node
4109 EAPI Eet_Node_Data *
4110 eet_node_value_get(Eet_Node *node);
4114 * @ingroup Eet_Node_Group
4117 eet_node_del(Eet_Node *n);
4121 * @ingroup Eet_Node_Group
4124 eet_data_node_encode_cipher(Eet_Node *node,
4125 const char *cipher_key,
4130 * @ingroup Eet_Node_Group
4133 eet_data_node_decode_cipher(const void *data_in,
4134 const char *cipher_key,
4139 * @ingroup Eet_Node_Group
4142 eet_data_node_read_cipher(Eet_File *ef,
4144 const char *cipher_key);
4148 * @ingroup Eet_Node_Group
4151 eet_data_node_write_cipher(Eet_File *ef,
4153 const char *cipher_key,
4157 /* EXPERIMENTAL: THIS API MAY CHANGE IN THE FUTURE, USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING. */
4160 * @typedef Eet_Node_Walk
4161 * Describes how to walk trees of #Eet_Node.
4163 typedef struct _Eet_Node_Walk Eet_Node_Walk;
4165 typedef void * (*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void *user_data);
4166 typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char *name, void *child, void *user_data);
4167 typedef void * (*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const char *name, int count, void *user_data);
4168 typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void *child, void *user_data);
4169 typedef void * (*Eet_Node_Walk_List_Callback)(const char *name, void *user_data);
4170 typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, void *user_data);
4171 typedef void * (*Eet_Node_Walk_Hash_Callback)(void *parent, const char *name, const char *key, void *value, void *user_data);
4172 typedef void * (*Eet_Node_Walk_Simple_Callback)(int type, Eet_Node_Data *data, void *user_data);
4175 * @struct _Eet_Node_Walk
4176 * Describes how to walk trees of #Eet_Node.
4178 struct _Eet_Node_Walk
4180 Eet_Node_Walk_Struct_Alloc_Callback struct_alloc;
4181 Eet_Node_Walk_Struct_Add_Callback struct_add;
4182 Eet_Node_Walk_Array_Callback array;
4183 Eet_Node_Walk_Insert_Callback insert;
4184 Eet_Node_Walk_List_Callback list;
4185 Eet_Node_Walk_Append_Callback append;
4186 Eet_Node_Walk_Hash_Callback hash;
4187 Eet_Node_Walk_Simple_Callback simple;
4191 eet_node_walk(void *parent,
4200 * @defgroup Eet_Connection_Group Helper function to use eet over a network link
4203 * Function that reconstruct and prepare packet of @ref Eet_Data_Group to be send.
4208 * @typedef Eet_Connection
4209 * Opaque handle to track paquet for a specific connection.
4211 * @ingroup Eet_Connection_Group
4213 typedef struct _Eet_Connection Eet_Connection;
4216 * @typedef Eet_Read_Cb
4217 * Called back when an @ref Eet_Data_Group has been received completely and could be used.
4219 * @ingroup Eet_Connection_Group
4221 typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *user_data);
4224 * @typedef Eet_Write_Cb
4225 * Called back when a packet containing @ref Eet_Data_Group data is ready to be send.
4227 * @ingroup Eet_Connection_Group
4229 typedef Eina_Bool Eet_Write_Cb (const void *data, size_t size, void *user_data);
4232 * Instanciate a new connection to track.
4233 * @param eet_read_cb Function to call when one Eet_Data packet has been fully assemble.
4234 * @param eet_write_cb Function to call when one Eet_Data packet is ready to be send over the wire.
4235 * @param user_data Pointer provided to both functions to be used as a context handler.
4236 * @return NULL on failure, or a valid Eet_Connection handler.
4238 * For every connection to track you will need a separate Eet_Connection provider.
4241 * @ingroup Eet_Connection_Group
4243 EAPI Eet_Connection *
4244 eet_connection_new(Eet_Read_Cb *eet_read_cb,
4245 Eet_Write_Cb *eet_write_cb,
4246 const void *user_data);
4249 * Process a raw packet received over the link
4250 * @param conn Connection handler to track.
4251 * @param data Raw data packet.
4252 * @param size The size of that packet.
4253 * @return 0 on complete success, any other value indicate where in the stream it got wrong (It could be before that packet).
4255 * Every time you receive a packet related to your connection, you should pass
4256 * it to that function so that it could process and assemble packet has you
4257 * receive it. It will automatically call Eet_Read_Cb when one is fully received.
4260 * @ingroup Eet_Connection_Group
4263 eet_connection_received(Eet_Connection *conn,
4268 * Tell if the Eet_Connection as received some partial data.
4269 * @param conn Connection handler to request.
4270 * @return EINA_TRUE if there is some data pending inside, EINA_FALSE otherwise.
4272 * Eet_Connection buffer data until the received data can be unserialized correctly. This
4273 * function let you know if there is some data inside that buffer waiting for more data to
4274 * be received before being processed.
4277 * @ingroup Eet_Connection_Group
4279 EAPI Eina_Bool eet_connection_empty(Eet_Connection *conn);
4282 * Convert a complex structure and prepare it to be send.
4283 * @param conn Connection handler to track.
4284 * @param edd The data descriptor to use when encoding.
4285 * @param data_in The pointer to the struct to encode into data.
4286 * @param cipher_key The key to use as cipher.
4287 * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
4289 * This function serialize data_in with edd, assemble the packet and call
4290 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
4291 * and will vanish just after the return of the callback.
4293 * @see eet_data_descriptor_encode_cipher
4296 * @ingroup Eet_Connection_Group
4299 eet_connection_send(Eet_Connection *conn,
4300 Eet_Data_Descriptor *edd,
4301 const void *data_in,
4302 const char *cipher_key);
4305 * Convert a Eet_Node tree and prepare it to be send.
4306 * @param conn Connection handler to track.
4307 * @param node The data tree to use when encoding.
4308 * @param cipher_key The key to use as cipher.
4309 * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
4311 * This function serialize node, assemble the packet and call
4312 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
4313 * and will vanish just after the return of the callback.
4315 * @see eet_data_node_encode_cipher
4318 * @ingroup Eet_Connection_Group
4321 eet_connection_node_send(Eet_Connection *conn,
4323 const char *cipher_key);
4326 * Close a connection and lost its track.
4327 * @param conn Connection handler to close.
4328 * @param on_going Signal if a partial packet wasn't completed.
4329 * @return the user_data passed to both callback.
4332 * @ingroup Eet_Connection_Group
4335 eet_connection_close(Eet_Connection *conn,
4336 Eina_Bool *on_going);
4338 /***************************************************************************/
4342 #endif /* ifdef __cplusplus */
4344 #endif /* ifndef _EET_H */
projects / platform / upstream / efl.git / blob