10 #endif /* ifdef EAPI */
15 # define EAPI __declspec(dllexport)
16 # else /* ifdef DLL_EXPORT */
18 # endif /* ! DLL_EXPORT */
19 # else /* ifdef EFL_EET_BUILD */
20 # define EAPI __declspec(dllimport)
21 # endif /* ! EFL_EET_BUILD */
22 #else /* ifdef _WIN32 */
25 # define EAPI __attribute__ ((visibility("default")))
26 # else /* if __GNUC__ >= 4 */
28 # endif /* if __GNUC__ >= 4 */
29 # else /* ifdef __GNUC__ */
31 # endif /* ifdef __GNUC__ */
36 #endif /* ifdef __cplusplus */
40 * @brief The file that provides the eet functions.
42 * This header provides the Eet management functions.
46 #define EET_VERSION_MAJOR 1
47 #define EET_VERSION_MINOR 4
49 * @typedef Eet_Version
51 * This is the Eet version information structure that can be used at
52 * runtiime to detect which version of eet is being used and adapt
53 * appropriately as follows for example:
56 * #if defined(EET_VERSION_MAJOR) && (EET_VERSION_MAJOR >= 1) && defined(EET_VERSION_MINOR) && (EET_VERSION_MINOR > 2)
57 * printf("Eet version: %i.%i.%i\n",
60 * eet_version->micro);
61 * if (eet_version->revision > 0)
63 * printf(" Built from SVN revision # %i\n", eet_version->revision);
68 * Note the #if check can be dropped if your program refuses to compile or
69 * work with an Eet version less than 1.3.0.
71 typedef struct _Eet_Version
73 int major; /** < major (binary or source incompatible changes) */
74 int minor; /** < minor (new features, bugfixes, major improvements version) */
75 int micro; /** < micro (bugfix, internal improvements, no new features version) */
76 int revision; /** < svn revision (0 if a proper rlease or the svn revsion number Eet is built from) */
79 EAPI extern Eet_Version *eet_version;
82 * @defgroup Eet_Group Top level functions
83 * Functions that affect Eet as a whole.
90 * All the error identifiers known by Eet.
92 typedef enum _Eet_Error
94 EET_ERROR_NONE, /**< No error, it's all fine! */
95 EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */
96 EET_ERROR_EMPTY, /**< There was nothing to do */
97 EET_ERROR_NOT_WRITABLE, /**< Could not write to file or fine is #EET_FILE_MODE_READ */
98 EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */
99 EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */
100 EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it is too big */
101 EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write since generic Input/Output error */
102 EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of space */
103 EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */
104 EET_ERROR_MMAP_FAILED, /**< Could not mmap file */
105 EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */
106 EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */
107 EET_ERROR_INVALID_SIGNATURE, /**< Signature is invalid */
108 EET_ERROR_NOT_SIGNED, /**< File or contents are not signed */
109 EET_ERROR_NOT_IMPLEMENTED, /**< Function is not implemented */
110 EET_ERROR_PRNG_NOT_SEEDED, /**< Could not introduce random seed */
111 EET_ERROR_ENCRYPT_FAILED, /**< Could not encrypt contents */
112 EET_ERROR_DECRYPT_FAILED /**< Could not decrypt contents */
113 } Eet_Error; /**< Eet error identifiers */
120 * Initialize the EET library.
122 * @return The new init count.
131 * Shut down the EET library.
133 * @return The new init count.
144 * Eet didn't free items by default. If you are under memory
145 * presure, just call this function to recall all memory that are
146 * not yet referenced anymore. The cache take care of modification
153 eet_clearcache(void);
156 * @defgroup Eet_File_Group Eet File Main Functions
158 * Functions to create, destroy and do basic manipulation of
165 * @enum _Eet_File_Mode
166 * Modes that a file can be opened.
168 typedef enum _Eet_File_Mode
170 EET_FILE_MODE_INVALID = -1,
171 EET_FILE_MODE_READ, /**< File is read-only. */
172 EET_FILE_MODE_WRITE, /**< File is write-only. */
173 EET_FILE_MODE_READ_WRITE /**< File is for both read and write */
174 } Eet_File_Mode; /**< Modes that a file can be opened. */
178 * Opaque handle that defines an Eet file (or memory).
181 * @see eet_memopen_read()
184 typedef struct _Eet_File Eet_File;
187 * @typedef Eet_Dictionary
188 * Opaque handle that defines a file-backed (mmaped) dictionary of strings.
190 typedef struct _Eet_Dictionary Eet_Dictionary;
197 * Open an eet file on disk, and returns a handle to it.
198 * @param file The file path to the eet file. eg: @c "/tmp/file.eet".
199 * @param mode The mode for opening. Either #EET_FILE_MODE_READ,
200 * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE.
201 * @return An opened eet file handle.
202 * @ingroup Eet_File_Group
204 * This function will open an exiting eet file for reading, and build
205 * the directory table in memory and return a handle to the file, if it
206 * exists and can be read, and no memory errors occur on the way, otherwise
207 * NULL will be returned.
209 * It will also open an eet file for writing. This will, if successful,
210 * delete the original file and replace it with a new empty file, till
211 * the eet file handle is closed or flushed. If it cannot be opened for
212 * writing or a memory error occurs, NULL is returned.
214 * You can also open the file for read/write. If you then write a key that
215 * does not exist it will be created, if the key exists it will be replaced
218 * If the same file is opened multiple times, then the same file handle will
219 * be returned as eet maintains an internal list of all currently open
220 * files. Note that it considers files opened for read only and those opened
221 * for read/write and write only as 2 separate sets. Those that do not write
222 * to the file and those that do. Eet will allow 2 handles to the same file
223 * if they are in the 2 separate lists/groups. That means opening a file for
224 * read only looks in the read only set, and returns a handle to that file
225 * handle and increments its reference count. If you open a file for read/write
226 * or write only it looks in the write set and returns a handle after
227 * incrementing the reference count. You need to close an eet file handle
228 * as many times as it has been opened to maintain correct reference counts.
229 * Files whose modified timestamp or size do not match those of the existing
230 * referenced file handles will not be returned and a new handle will be
237 * #include <string.h>
240 * main(int argc, char **argv)
243 * char buf[1024], *ret, **list;
248 * strcpy(buf, "Here is a string of data to save!");
250 * ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE);
251 * if (!ef) return -1;
252 * if (!eet_write(ef, "/key/to_store/at", buf, 1024, 1))
253 * fprintf(stderr, "Error writing data!\n");
256 * ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_READ);
257 * if (!ef) return -1;
258 * list = eet_list(ef, "*", &num);
261 * for (i = 0; i < num; i++)
262 * printf("Key stored: %s\n", list[i]);
265 * ret = eet_read(ef, "/key/to_store/at", &size);
268 * printf("Data read (%i bytes):\n%s\n", size, ret);
282 eet_open(const char *file,
286 * Open an eet file directly from a memory location. The data is not copied,
287 * so you must keep it around as long as the eet file is open. There is
288 * currently no cache for this kind of Eet_File, so it's reopened every time
289 * you use eet_memopen_read.
292 * @ingroup Eet_File_Group
295 eet_memopen_read(const void *data,
299 * Get the mode an Eet_File was opened with.
300 * @param ef A valid eet file handle.
301 * @return The mode ef was opened with.
304 * @ingroup Eet_File_Group
307 eet_mode_get(Eet_File *ef);
310 * Close an eet file handle and flush and writes pending.
311 * @param ef A valid eet file handle.
313 * This function will flush any pending writes to disk if the eet file
314 * was opened for write, and free all data associated with the file handle
315 * and file, and close the file.
317 * If the eet file handle is not valid nothing will be done.
320 * @ingroup Eet_File_Group
323 eet_close(Eet_File *ef);
326 * Sync content of an eet file handle, flushing pending writes.
327 * @param ef A valid eet file handle.
329 * This function will flush any pending writes to disk. The eet file must
330 * be opened for write.
332 * If the eet file handle is not valid nothing will be done.
335 * @ingroup Eet_File_Group
338 eet_sync(Eet_File *ef);
341 * Return a handle to the shared string dictionary of the Eet file
342 * @param ef A valid eet file handle.
343 * @return A handle to the dictionary of the file
345 * This function returns a handle to the dictionary of an Eet file whose
346 * handle is @p ef, if a dictionary exists. NULL is returned otherwise or
347 * if the file handle is known to be invalid.
349 * @see eet_dictionary_string_check() to know if given string came
350 * from the dictionary or it was dynamically allocated using
351 * the #Eet_Data_Descriptor_Class instructrions.
354 * @ingroup Eet_File_Group
356 EAPI Eet_Dictionary *
357 eet_dictionary_get(Eet_File *ef);
360 * Check if a given string comes from a given dictionary
361 * @param ed A valid dictionary handle
362 * @param string A valid 0 byte terminated C string
363 * @return 1 if it is in the dictionary, 0 otherwise
365 * This checks the given dictionary to see if the given string is actually
366 * inside that dictionary (i.e. comes from it) and returns 1 if it does.
367 * If the dictionary handle is invlide, the string is NULL or the string is
368 * not in the dictionary, 0 is returned.
371 * @ingroup Eet_File_Group
374 eet_dictionary_string_check(Eet_Dictionary *ed,
378 * Read a specified entry from an eet file and return data
379 * @param ef A valid eet file handle opened for reading.
380 * @param name Name of the entry. eg: "/base/file_i_want".
381 * @param size_ret Number of bytes read from entry and returned.
382 * @return The data stored in that entry in the eet file.
384 * This function finds an entry in the eet file that is stored under the
385 * name specified, and returns that data, decompressed, if successful.
386 * NULL is returned if the lookup fails or if memory errors are
387 * encountered. It is the job of the calling program to call free() on
388 * the returned data. The number of bytes in the returned data chunk are
389 * placed in size_ret.
391 * If the eet file handle is not valid NULL is returned and size_ret is
394 * @see eet_read_cipher()
397 * @ingroup Eet_File_Group
400 eet_read(Eet_File *ef,
405 * Read a specified entry from an eet file and return data
406 * @param ef A valid eet file handle opened for reading.
407 * @param name Name of the entry. eg: "/base/file_i_want".
408 * @param size_ret Number of bytes read from entry and returned.
409 * @return The data stored in that entry in the eet file.
411 * This function finds an entry in the eet file that is stored under the
412 * name specified, and returns that data if not compressed and successful.
413 * NULL is returned if the lookup fails or if memory errors are
414 * encountered or if the data is comrpessed. The calling program must never
415 * call free() on the returned data. The number of bytes in the returned
416 * data chunk are placed in size_ret.
418 * If the eet file handle is not valid NULL is returned and size_ret is
422 * @ingroup Eet_File_Group
425 eet_read_direct(Eet_File *ef,
430 * Write a specified entry to an eet file handle
431 * @param ef A valid eet file handle opened for writing.
432 * @param name Name of the entry. eg: "/base/file_i_want".
433 * @param data Pointer to the data to be stored.
434 * @param size Length in bytes in the data to be stored.
435 * @param compress Compression flags (1 == compress, 0 = don't compress).
436 * @return bytes written on successful write, 0 on failure.
438 * This function will write the specified chunk of data to the eet file
439 * and return greater than 0 on success. 0 will be returned on failure.
441 * The eet file handle must be a valid file handle for an eet file opened
442 * for writing. If it is not, 0 will be returned and no action will be
445 * Name, and data must not be NULL, and size must be > 0. If these
446 * conditions are not met, 0 will be returned.
448 * The data will be copied (and optionally compressed) in ram, pending
449 * a flush to disk (it will stay in ram till the eet file handle is
452 * @see eet_write_cipher()
455 * @ingroup Eet_File_Group
458 eet_write(Eet_File *ef,
465 * Delete a specified entry from an Eet file being written or re-written
466 * @param ef A valid eet file handle opened for writing.
467 * @param name Name of the entry. eg: "/base/file_i_want".
468 * @return Success or failure of the delete.
470 * This function will delete the specified chunk of data from the eet file
471 * and return greater than 0 on success. 0 will be returned on failure.
473 * The eet file handle must be a valid file handle for an eet file opened
474 * for writing. If it is not, 0 will be returned and no action will be
477 * Name, must not be NULL, otherwise 0 will be returned.
480 * @ingroup Eet_File_Group
483 eet_delete(Eet_File *ef,
487 * Alias a specific section to another one. Destination may exist or not,
489 * @param ef A valid eet file handle opened for writing.
490 * @param name Name of the entry. eg: "/base/file_i_want".
491 * @param destination Destionation of the alias. eg: "/base/the_real_stuff_i_want".
492 * @param compress Compression flags (1 == compress, 0 = don't compress).
493 * @return EINA_TRUE on success, EINA_FALSE on failure.
495 * Name and Destination must not be NULL, otherwhise EINA_FALSE will be returned.
498 * @ingroup Eet_File_Group
501 eet_alias(Eet_File *ef,
503 const char *destination,
507 * List all entries in eet file matching shell glob.
508 * @param ef A valid eet file handle.
509 * @param glob A shell glob to match against.
510 * @param count_ret Number of entries found to match.
511 * @return Pointer to an array of strings.
513 * This function will list all entries in the eet file matching the
514 * supplied shell glob and return an allocated list of their names, if
515 * there are any, and if no memory errors occur.
517 * The eet file handle must be valid and glob must not be NULL, or NULL
518 * will be returned and count_ret will be filled with 0.
520 * The calling program must call free() on the array returned, but NOT
521 * on the string pointers in the array. They are taken as read-only
522 * internals from the eet file handle. They are only valid as long as
523 * the file handle is not closed. When it is closed those pointers in the
524 * array are now not valid and should not be used.
526 * On success the array returned will have a list of string pointers
527 * that are the names of the entries that matched, and count_ret will have
528 * the number of entries in this array placed in it.
530 * Hint: an easy way to list all entries in an eet file is to use a glob
534 * @ingroup Eet_File_Group
537 eet_list(Eet_File *ef,
542 * Return the number of entries in the specified eet file.
543 * @param ef A valid eet file handle.
544 * @return Number of entries in ef or -1 if the number of entries
545 * cannot be read due to open mode restrictions.
548 * @ingroup Eet_File_Group
551 eet_num_entries(Eet_File *ef);
554 * @defgroup Eet_File_Cipher_Group Eet File Ciphered Main Functions
556 * Most of the @ref Eet_File_Group have alternative versions that
557 * accounts for ciphers to protect their content.
559 * @see @ref Eet_Cipher_Group
561 * @ingroup Eet_File_Group
565 * Read a specified entry from an eet file and return data using a cipher.
566 * @param ef A valid eet file handle opened for reading.
567 * @param name Name of the entry. eg: "/base/file_i_want".
568 * @param size_ret Number of bytes read from entry and returned.
569 * @param cipher_key The key to use as cipher.
570 * @return The data stored in that entry in the eet file.
572 * This function finds an entry in the eet file that is stored under the
573 * name specified, and returns that data, decompressed, if successful.
574 * NULL is returned if the lookup fails or if memory errors are
575 * encountered. It is the job of the calling program to call free() on
576 * the returned data. The number of bytes in the returned data chunk are
577 * placed in size_ret.
579 * If the eet file handle is not valid NULL is returned and size_ret is
585 * @ingroup Eet_File_Cipher_Group
588 eet_read_cipher(Eet_File *ef,
591 const char *cipher_key);
594 * Write a specified entry to an eet file handle using a cipher.
595 * @param ef A valid eet file handle opened for writing.
596 * @param name Name of the entry. eg: "/base/file_i_want".
597 * @param data Pointer to the data to be stored.
598 * @param size Length in bytes in the data to be stored.
599 * @param compress Compression flags (1 == compress, 0 = don't compress).
600 * @param cipher_key The key to use as cipher.
601 * @return bytes written on successful write, 0 on failure.
603 * This function will write the specified chunk of data to the eet file
604 * and return greater than 0 on success. 0 will be returned on failure.
606 * The eet file handle must be a valid file handle for an eet file opened
607 * for writing. If it is not, 0 will be returned and no action will be
610 * Name, and data must not be NULL, and size must be > 0. If these
611 * conditions are not met, 0 will be returned.
613 * The data will be copied (and optionally compressed) in ram, pending
614 * a flush to disk (it will stay in ram till the eet file handle is
620 * @ingroup Eet_File_Cipher_Group
623 eet_write_cipher(Eet_File *ef,
628 const char *cipher_key);
631 * @defgroup Eet_File_Image_Group Image Store and Load
633 * Eet efficiently stores and loads images, including alpha
634 * channels and lossy compressions.
638 * Read just the header data for an image and dont decode the pixels.
639 * @param ef A valid eet file handle opened for reading.
640 * @param name Name of the entry. eg: "/base/file_i_want".
641 * @param w A pointer to the unsigned int to hold the width in pixels.
642 * @param h A pointer to the unsigned int to hold the height in pixels.
643 * @param alpha A pointer to the int to hold the alpha flag.
644 * @param compress A pointer to the int to hold the compression amount.
645 * @param quality A pointer to the int to hold the quality amount.
646 * @param lossy A pointer to the int to hold the lossiness flag.
647 * @return 1 on successful decode, 0 otherwise
649 * This function reads an image from an eet file stored under the named
650 * key in the eet file and return a pointer to the decompressed pixel data.
652 * The other parameters of the image (width, height etc.) are placed into
653 * the values pointed to (they must be supplied). The pixel data is a linear
654 * array of pixels starting from the top-left of the image scanning row by
655 * row from left to right. Each pile is a 32bit value, with the high byte
656 * being the alpha channel, the next being red, then green, and the low byte
657 * being blue. The width and height are measured in pixels and will be
658 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
659 * that the alpha channel is not used. 1 denotes that it is significant.
660 * Compress is filled with the compression value/amount the image was
661 * stored with. The quality value is filled with the quality encoding of
662 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
663 * the image was encoded lossily or not.
665 * On success the function returns 1 indicating the header was read and
666 * decoded properly, or 0 on failure.
668 * @see eet_data_image_header_read_cipher()
671 * @ingroup Eet_File_Image_Group
674 eet_data_image_header_read(Eet_File *ef,
684 * Read image data from the named key in the eet file.
685 * @param ef A valid eet file handle opened for reading.
686 * @param name Name of the entry. eg: "/base/file_i_want".
687 * @param w A pointer to the unsigned int to hold the width in pixels.
688 * @param h A pointer to the unsigned int to hold the height in pixels.
689 * @param alpha A pointer to the int to hold the alpha flag.
690 * @param compress A pointer to the int to hold the compression amount.
691 * @param quality A pointer to the int to hold the quality amount.
692 * @param lossy A pointer to the int to hold the lossiness flag.
693 * @return The image pixel data decoded
695 * This function reads an image from an eet file stored under the named
696 * key in the eet file and return a pointer to the decompressed pixel data.
698 * The other parameters of the image (width, height etc.) are placed into
699 * the values pointed to (they must be supplied). The pixel data is a linear
700 * array of pixels starting from the top-left of the image scanning row by
701 * row from left to right. Each pile is a 32bit value, with the high byte
702 * being the alpha channel, the next being red, then green, and the low byte
703 * being blue. The width and height are measured in pixels and will be
704 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
705 * that the alpha channel is not used. 1 denotes that it is significant.
706 * Compress is filled with the compression value/amount the image was
707 * stored with. The quality value is filled with the quality encoding of
708 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
709 * the image was encoded lossily or not.
711 * On success the function returns a pointer to the image data decoded. The
712 * calling application is responsible for calling free() on the image data
713 * when it is done with it. On failure NULL is returned and the parameter
714 * values may not contain any sensible data.
716 * @see eet_data_image_read_cipher()
719 * @ingroup Eet_File_Image_Group
722 eet_data_image_read(Eet_File *ef,
732 * Read image data from the named key in the eet file.
733 * @param ef A valid eet file handle opened for reading.
734 * @param name Name of the entry. eg: "/base/file_i_want".
735 * @param src_x The starting x coordinate from where to dump the stream.
736 * @param src_y The starting y coordinate from where to dump the stream.
737 * @param d A pointer to the pixel surface.
738 * @param w The expected width in pixels of the pixel surface to decode.
739 * @param h The expected height in pixels of the pixel surface to decode.
740 * @param row_stride The length of a pixels line in the destination surface.
741 * @param alpha A pointer to the int to hold the alpha flag.
742 * @param compress A pointer to the int to hold the compression amount.
743 * @param quality A pointer to the int to hold the quality amount.
744 * @param lossy A pointer to the int to hold the lossiness flag.
745 * @return 1 on success, 0 otherwise.
747 * This function reads an image from an eet file stored under the named
748 * key in the eet file and return a pointer to the decompressed pixel data.
750 * The other parameters of the image (width, height etc.) are placed into
751 * the values pointed to (they must be supplied). The pixel data is a linear
752 * array of pixels starting from the top-left of the image scanning row by
753 * row from left to right. Each pile is a 32bit value, with the high byte
754 * being the alpha channel, the next being red, then green, and the low byte
755 * being blue. The width and height are measured in pixels and will be
756 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
757 * that the alpha channel is not used. 1 denotes that it is significant.
758 * Compress is filled with the compression value/amount the image was
759 * stored with. The quality value is filled with the quality encoding of
760 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
761 * the image was encoded lossily or not.
763 * On success the function returns 1, and 0 on failure. On failure the
764 * parameter values may not contain any sensible data.
766 * @see eet_data_image_read_to_surface_cipher()
769 * @ingroup Eet_File_Image_Group
772 eet_data_image_read_to_surface(Eet_File *ef,
779 unsigned int row_stride,
786 * Write image data to the named key in an eet file.
787 * @param ef A valid eet file handle opened for writing.
788 * @param name Name of the entry. eg: "/base/file_i_want".
789 * @param data A pointer to the image pixel data.
790 * @param w The width of the image in pixels.
791 * @param h The height of the image in pixels.
792 * @param alpha The alpha channel flag.
793 * @param compress The compression amount.
794 * @param quality The quality encoding amount.
795 * @param lossy The lossiness flag.
796 * @return Success if the data was encoded and written or not.
798 * This function takes image pixel data and encodes it in an eet file
799 * stored under the supplied name key, and returns how many bytes were
800 * actually written to encode the image data.
802 * The data expected is the same format as returned by eet_data_image_read.
803 * If this is not the case weird things may happen. Width and height must
804 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
805 * the alpha values are not useful and 1 meaning they are). Compress can
806 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
807 * This is only used if the image is not lossily encoded. Quality is used on
808 * lossy compression and should be a value from 0 to 100. The lossy flag
809 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
810 * image quality loss (but then have a much smaller encoding).
812 * On success this function returns the number of bytes that were required
813 * to encode the image data, or on failure it returns 0.
815 * @see eet_data_image_write_cipher()
818 * @ingroup Eet_File_Image_Group
821 eet_data_image_write(Eet_File *ef,
832 * Decode Image data header only to get information.
833 * @param data The encoded pixel data.
834 * @param size The size, in bytes, of the encoded pixel data.
835 * @param w A pointer to the unsigned int to hold the width in pixels.
836 * @param h A pointer to the unsigned int to hold the height in pixels.
837 * @param alpha A pointer to the int to hold the alpha flag.
838 * @param compress A pointer to the int to hold the compression amount.
839 * @param quality A pointer to the int to hold the quality amount.
840 * @param lossy A pointer to the int to hold the lossiness flag.
841 * @return 1 on success, 0 on failure.
843 * This function takes encoded pixel data and decodes it into raw RGBA
846 * The other parameters of the image (width, height etc.) are placed into
847 * the values pointed to (they must be supplied). The pixel data is a linear
848 * array of pixels starting from the top-left of the image scanning row by
849 * row from left to right. Each pixel is a 32bit value, with the high byte
850 * being the alpha channel, the next being red, then green, and the low byte
851 * being blue. The width and height are measured in pixels and will be
852 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
853 * that the alpha channel is not used. 1 denotes that it is significant.
854 * Compress is filled with the compression value/amount the image was
855 * stored with. The quality value is filled with the quality encoding of
856 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
857 * the image was encoded lossily or not.
859 * On success the function returns 1 indicating the header was read and
860 * decoded properly, or 0 on failure.
862 * @see eet_data_image_header_decode_cipher()
865 * @ingroup Eet_File_Image_Group
868 eet_data_image_header_decode(const void *data,
878 * Decode Image data into pixel data.
879 * @param data The encoded pixel data.
880 * @param size The size, in bytes, of the encoded pixel data.
881 * @param w A pointer to the unsigned int to hold the width in pixels.
882 * @param h A pointer to the unsigned int to hold the height in pixels.
883 * @param alpha A pointer to the int to hold the alpha flag.
884 * @param compress A pointer to the int to hold the compression amount.
885 * @param quality A pointer to the int to hold the quality amount.
886 * @param lossy A pointer to the int to hold the lossiness flag.
887 * @return The image pixel data decoded
889 * This function takes encoded pixel data and decodes it into raw RGBA
892 * The other parameters of the image (width, height etc.) are placed into
893 * the values pointed to (they must be supplied). The pixel data is a linear
894 * array of pixels starting from the top-left of the image scanning row by
895 * row from left to right. Each pixel is a 32bit value, with the high byte
896 * being the alpha channel, the next being red, then green, and the low byte
897 * being blue. The width and height are measured in pixels and will be
898 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
899 * that the alpha channel is not used. 1 denotes that it is significant.
900 * Compress is filled with the compression value/amount the image was
901 * stored with. The quality value is filled with the quality encoding of
902 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
903 * the image was encoded lossily or not.
905 * On success the function returns a pointer to the image data decoded. The
906 * calling application is responsible for calling free() on the image data
907 * when it is done with it. On failure NULL is returned and the parameter
908 * values may not contain any sensible data.
910 * @see eet_data_image_decode_cipher()
913 * @ingroup Eet_File_Image_Group
916 eet_data_image_decode(const void *data,
926 * Decode Image data into pixel data.
927 * @param data The encoded pixel data.
928 * @param size The size, in bytes, of the encoded pixel data.
929 * @param src_x The starting x coordinate from where to dump the stream.
930 * @param src_y The starting y coordinate from where to dump the stream.
931 * @param d A pointer to the pixel surface.
932 * @param w The expected width in pixels of the pixel surface to decode.
933 * @param h The expected height in pixels of the pixel surface to decode.
934 * @param row_stride The length of a pixels line in the destination surface.
935 * @param alpha A pointer to the int to hold the alpha flag.
936 * @param compress A pointer to the int to hold the compression amount.
937 * @param quality A pointer to the int to hold the quality amount.
938 * @param lossy A pointer to the int to hold the lossiness flag.
939 * @return 1 on success, 0 otherwise.
941 * This function takes encoded pixel data and decodes it into raw RGBA
944 * The other parameters of the image (alpha, compress etc.) are placed into
945 * the values pointed to (they must be supplied). The pixel data is a linear
946 * array of pixels starting from the top-left of the image scanning row by
947 * row from left to right. Each pixel is a 32bit value, with the high byte
948 * being the alpha channel, the next being red, then green, and the low byte
949 * being blue. The width and height are measured in pixels and will be
950 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
951 * that the alpha channel is not used. 1 denotes that it is significant.
952 * Compress is filled with the compression value/amount the image was
953 * stored with. The quality value is filled with the quality encoding of
954 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
955 * the image was encoded lossily or not.
957 * On success the function returns 1, and 0 on failure. On failure the
958 * parameter values may not contain any sensible data.
960 * @see eet_data_image_decode_to_surface_cipher()
963 * @ingroup Eet_File_Image_Group
966 eet_data_image_decode_to_surface(const void *data,
973 unsigned int row_stride,
980 * Encode image data for storage or transmission.
981 * @param data A pointer to the image pixel data.
982 * @param size_ret A pointer to an int to hold the size of the returned data.
983 * @param w The width of the image in pixels.
984 * @param h The height of the image in pixels.
985 * @param alpha The alpha channel flag.
986 * @param compress The compression amount.
987 * @param quality The quality encoding amount.
988 * @param lossy The lossiness flag.
989 * @return The encoded image data.
991 * This function stakes image pixel data and encodes it with compression and
992 * possible loss of quality (as a trade off for size) for storage or
993 * transmission to another system.
995 * The data expected is the same format as returned by eet_data_image_read.
996 * If this is not the case weird things may happen. Width and height must
997 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
998 * the alpha values are not useful and 1 meaning they are). Compress can
999 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1000 * This is only used if the image is not lossily encoded. Quality is used on
1001 * lossy compression and should be a value from 0 to 100. The lossy flag
1002 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1003 * image quality loss (but then have a much smaller encoding).
1005 * On success this function returns a pointer to the encoded data that you
1006 * can free with free() when no longer needed.
1008 * @see eet_data_image_encode_cipher()
1011 * @ingroup Eet_File_Image_Group
1014 eet_data_image_encode(const void *data,
1024 * @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Cipher
1026 * Most of the @ref Eet_File_Image_Group have alternative versions
1027 * that accounts for ciphers to protect their content.
1029 * @see @ref Eet_Cipher_Group
1031 * @ingroup Eet_File_Image_Group
1035 * Read just the header data for an image and dont decode the pixels using a cipher.
1036 * @param ef A valid eet file handle opened for reading.
1037 * @param name Name of the entry. eg: "/base/file_i_want".
1038 * @param cipher_key The key to use as cipher.
1039 * @param w A pointer to the unsigned int to hold the width in pixels.
1040 * @param h A pointer to the unsigned int to hold the height in pixels.
1041 * @param alpha A pointer to the int to hold the alpha flag.
1042 * @param compress A pointer to the int to hold the compression amount.
1043 * @param quality A pointer to the int to hold the quality amount.
1044 * @param lossy A pointer to the int to hold the lossiness flag.
1045 * @return 1 on successful decode, 0 otherwise
1047 * This function reads an image from an eet file stored under the named
1048 * key in the eet file and return a pointer to the decompressed pixel data.
1050 * The other parameters of the image (width, height etc.) are placed into
1051 * the values pointed to (they must be supplied). The pixel data is a linear
1052 * array of pixels starting from the top-left of the image scanning row by
1053 * row from left to right. Each pile is a 32bit value, with the high byte
1054 * being the alpha channel, the next being red, then green, and the low byte
1055 * being blue. The width and height are measured in pixels and will be
1056 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1057 * that the alpha channel is not used. 1 denotes that it is significant.
1058 * Compress is filled with the compression value/amount the image was
1059 * stored with. The quality value is filled with the quality encoding of
1060 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1061 * the image was encoded lossily or not.
1063 * On success the function returns 1 indicating the header was read and
1064 * decoded properly, or 0 on failure.
1066 * @see eet_data_image_header_read()
1069 * @ingroup Eet_File_Image_Cipher_Group
1072 eet_data_image_header_read_cipher(Eet_File *ef,
1074 const char *cipher_key,
1083 * Read image data from the named key in the eet file using a cipher.
1084 * @param ef A valid eet file handle opened for reading.
1085 * @param name Name of the entry. eg: "/base/file_i_want".
1086 * @param cipher_key The key to use as cipher.
1087 * @param w A pointer to the unsigned int to hold the width in pixels.
1088 * @param h A pointer to the unsigned int to hold the height in pixels.
1089 * @param alpha A pointer to the int to hold the alpha flag.
1090 * @param compress A pointer to the int to hold the compression amount.
1091 * @param quality A pointer to the int to hold the quality amount.
1092 * @param lossy A pointer to the int to hold the lossiness flag.
1093 * @return The image pixel data decoded
1095 * This function reads an image from an eet file stored under the named
1096 * key in the eet file and return a pointer to the decompressed pixel data.
1098 * The other parameters of the image (width, height etc.) are placed into
1099 * the values pointed to (they must be supplied). The pixel data is a linear
1100 * array of pixels starting from the top-left of the image scanning row by
1101 * row from left to right. Each pile is a 32bit value, with the high byte
1102 * being the alpha channel, the next being red, then green, and the low byte
1103 * being blue. The width and height are measured in pixels and will be
1104 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1105 * that the alpha channel is not used. 1 denotes that it is significant.
1106 * Compress is filled with the compression value/amount the image was
1107 * stored with. The quality value is filled with the quality encoding of
1108 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1109 * the image was encoded lossily or not.
1111 * On success the function returns a pointer to the image data decoded. The
1112 * calling application is responsible for calling free() on the image data
1113 * when it is done with it. On failure NULL is returned and the parameter
1114 * values may not contain any sensible data.
1116 * @see eet_data_image_read()
1119 * @ingroup Eet_File_Image_Cipher_Group
1122 eet_data_image_read_cipher(Eet_File *ef,
1124 const char *cipher_key,
1133 * Read image data from the named key in the eet file using a cipher.
1134 * @param ef A valid eet file handle opened for reading.
1135 * @param name Name of the entry. eg: "/base/file_i_want".
1136 * @param cipher_key The key to use as cipher.
1137 * @param src_x The starting x coordinate from where to dump the stream.
1138 * @param src_y The starting y coordinate from where to dump the stream.
1139 * @param d A pointer to the pixel surface.
1140 * @param w The expected width in pixels of the pixel surface to decode.
1141 * @param h The expected height in pixels of the pixel surface to decode.
1142 * @param row_stride The length of a pixels line in the destination surface.
1143 * @param alpha A pointer to the int to hold the alpha flag.
1144 * @param compress A pointer to the int to hold the compression amount.
1145 * @param quality A pointer to the int to hold the quality amount.
1146 * @param lossy A pointer to the int to hold the lossiness flag.
1147 * @return 1 on success, 0 otherwise.
1149 * This function reads an image from an eet file stored under the named
1150 * key in the eet file and return a pointer to the decompressed pixel data.
1152 * The other parameters of the image (width, height etc.) are placed into
1153 * the values pointed to (they must be supplied). The pixel data is a linear
1154 * array of pixels starting from the top-left of the image scanning row by
1155 * row from left to right. Each pile is a 32bit value, with the high byte
1156 * being the alpha channel, the next being red, then green, and the low byte
1157 * being blue. The width and height are measured in pixels and will be
1158 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1159 * that the alpha channel is not used. 1 denotes that it is significant.
1160 * Compress is filled with the compression value/amount the image was
1161 * stored with. The quality value is filled with the quality encoding of
1162 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1163 * the image was encoded lossily or not.
1165 * On success the function returns 1, and 0 on failure. On failure the
1166 * parameter values may not contain any sensible data.
1168 * @see eet_data_image_read_to_surface()
1171 * @ingroup Eet_File_Image_Cipher_Group
1174 eet_data_image_read_to_surface_cipher(Eet_File *ef,
1176 const char *cipher_key,
1182 unsigned int row_stride,
1189 * Write image data to the named key in an eet file using a cipher.
1190 * @param ef A valid eet file handle opened for writing.
1191 * @param name Name of the entry. eg: "/base/file_i_want".
1192 * @param cipher_key The key to use as cipher.
1193 * @param data A pointer to the image pixel data.
1194 * @param w The width of the image in pixels.
1195 * @param h The height of the image in pixels.
1196 * @param alpha The alpha channel flag.
1197 * @param compress The compression amount.
1198 * @param quality The quality encoding amount.
1199 * @param lossy The lossiness flag.
1200 * @return Success if the data was encoded and written or not.
1202 * This function takes image pixel data and encodes it in an eet file
1203 * stored under the supplied name key, and returns how many bytes were
1204 * actually written to encode the image data.
1206 * The data expected is the same format as returned by eet_data_image_read.
1207 * If this is not the case weird things may happen. Width and height must
1208 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1209 * the alpha values are not useful and 1 meaning they are). Compress can
1210 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1211 * This is only used if the image is not lossily encoded. Quality is used on
1212 * lossy compression and should be a value from 0 to 100. The lossy flag
1213 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1214 * image quality loss (but then have a much smaller encoding).
1216 * On success this function returns the number of bytes that were required
1217 * to encode the image data, or on failure it returns 0.
1219 * @see eet_data_image_write()
1222 * @ingroup Eet_File_Image_Cipher_Group
1225 eet_data_image_write_cipher(Eet_File *ef,
1227 const char *cipher_key,
1237 * Decode Image data header only to get information using a cipher.
1238 * @param data The encoded pixel data.
1239 * @param cipher_key The key to use as cipher.
1240 * @param size The size, in bytes, of the encoded pixel data.
1241 * @param w A pointer to the unsigned int to hold the width in pixels.
1242 * @param h A pointer to the unsigned int to hold the height in pixels.
1243 * @param alpha A pointer to the int to hold the alpha flag.
1244 * @param compress A pointer to the int to hold the compression amount.
1245 * @param quality A pointer to the int to hold the quality amount.
1246 * @param lossy A pointer to the int to hold the lossiness flag.
1247 * @return 1 on success, 0 on failure.
1249 * This function takes encoded pixel data and decodes it into raw RGBA
1250 * pixels on success.
1252 * The other parameters of the image (width, height etc.) are placed into
1253 * the values pointed to (they must be supplied). The pixel data is a linear
1254 * array of pixels starting from the top-left of the image scanning row by
1255 * row from left to right. Each pixel is a 32bit value, with the high byte
1256 * being the alpha channel, the next being red, then green, and the low byte
1257 * being blue. The width and height are measured in pixels and will be
1258 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1259 * that the alpha channel is not used. 1 denotes that it is significant.
1260 * Compress is filled with the compression value/amount the image was
1261 * stored with. The quality value is filled with the quality encoding of
1262 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1263 * the image was encoded lossily or not.
1265 * On success the function returns 1 indicating the header was read and
1266 * decoded properly, or 0 on failure.
1268 * @see eet_data_image_header_decode()
1271 * @ingroup Eet_File_Image_Cipher_Group
1274 eet_data_image_header_decode_cipher(const void *data,
1275 const char *cipher_key,
1285 * Decode Image data into pixel data using a cipher.
1286 * @param data The encoded pixel data.
1287 * @param cipher_key The key to use as cipher.
1288 * @param size The size, in bytes, of the encoded pixel data.
1289 * @param w A pointer to the unsigned int to hold the width in pixels.
1290 * @param h A pointer to the unsigned int to hold the height in pixels.
1291 * @param alpha A pointer to the int to hold the alpha flag.
1292 * @param compress A pointer to the int to hold the compression amount.
1293 * @param quality A pointer to the int to hold the quality amount.
1294 * @param lossy A pointer to the int to hold the lossiness flag.
1295 * @return The image pixel data decoded
1297 * This function takes encoded pixel data and decodes it into raw RGBA
1298 * pixels on success.
1300 * The other parameters of the image (width, height etc.) are placed into
1301 * the values pointed to (they must be supplied). The pixel data is a linear
1302 * array of pixels starting from the top-left of the image scanning row by
1303 * row from left to right. Each pixel is a 32bit value, with the high byte
1304 * being the alpha channel, the next being red, then green, and the low byte
1305 * being blue. The width and height are measured in pixels and will be
1306 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1307 * that the alpha channel is not used. 1 denotes that it is significant.
1308 * Compress is filled with the compression value/amount the image was
1309 * stored with. The quality value is filled with the quality encoding of
1310 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1311 * the image was encoded lossily or not.
1313 * On success the function returns a pointer to the image data decoded. The
1314 * calling application is responsible for calling free() on the image data
1315 * when it is done with it. On failure NULL is returned and the parameter
1316 * values may not contain any sensible data.
1318 * @see eet_data_image_decode()
1321 * @ingroup Eet_File_Image_Cipher_Group
1324 eet_data_image_decode_cipher(const void *data,
1325 const char *cipher_key,
1335 * Decode Image data into pixel data using a cipher.
1336 * @param data The encoded pixel data.
1337 * @param cipher_key The key to use as cipher.
1338 * @param size The size, in bytes, of the encoded pixel data.
1339 * @param src_x The starting x coordinate from where to dump the stream.
1340 * @param src_y The starting y coordinate from where to dump the stream.
1341 * @param d A pointer to the pixel surface.
1342 * @param w The expected width in pixels of the pixel surface to decode.
1343 * @param h The expected height in pixels of the pixel surface to decode.
1344 * @param row_stride The length of a pixels line in the destination surface.
1345 * @param alpha A pointer to the int to hold the alpha flag.
1346 * @param compress A pointer to the int to hold the compression amount.
1347 * @param quality A pointer to the int to hold the quality amount.
1348 * @param lossy A pointer to the int to hold the lossiness flag.
1349 * @return 1 on success, 0 otherwise.
1351 * This function takes encoded pixel data and decodes it into raw RGBA
1352 * pixels on success.
1354 * The other parameters of the image (alpha, compress etc.) are placed into
1355 * the values pointed to (they must be supplied). The pixel data is a linear
1356 * array of pixels starting from the top-left of the image scanning row by
1357 * row from left to right. Each pixel is a 32bit value, with the high byte
1358 * being the alpha channel, the next being red, then green, and the low byte
1359 * being blue. The width and height are measured in pixels and will be
1360 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1361 * that the alpha channel is not used. 1 denotes that it is significant.
1362 * Compress is filled with the compression value/amount the image was
1363 * stored with. The quality value is filled with the quality encoding of
1364 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1365 * the image was encoded lossily or not.
1367 * On success the function returns 1, and 0 on failure. On failure the
1368 * parameter values may not contain any sensible data.
1370 * @see eet_data_image_decode_to_surface()
1373 * @ingroup Eet_File_Image_Cipher_Group
1376 eet_data_image_decode_to_surface_cipher(const void *data,
1377 const char *cipher_key,
1384 unsigned int row_stride,
1391 * Encode image data for storage or transmission using a cipher.
1392 * @param data A pointer to the image pixel data.
1393 * @param cipher_key The key to use as cipher.
1394 * @param size_ret A pointer to an int to hold the size of the returned data.
1395 * @param w The width of the image in pixels.
1396 * @param h The height of the image in pixels.
1397 * @param alpha The alpha channel flag.
1398 * @param compress The compression amount.
1399 * @param quality The quality encoding amount.
1400 * @param lossy The lossiness flag.
1401 * @return The encoded image data.
1403 * This function stakes image pixel data and encodes it with compression and
1404 * possible loss of quality (as a trade off for size) for storage or
1405 * transmission to another system.
1407 * The data expected is the same format as returned by eet_data_image_read.
1408 * If this is not the case weird things may happen. Width and height must
1409 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1410 * the alpha values are not useful and 1 meaning they are). Compress can
1411 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1412 * This is only used if the image is not lossily encoded. Quality is used on
1413 * lossy compression and should be a value from 0 to 100. The lossy flag
1414 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1415 * image quality loss (but then have a much smaller encoding).
1417 * On success this function returns a pointer to the encoded data that you
1418 * can free with free() when no longer needed.
1420 * @see eet_data_image_encode()
1423 * @ingroup Eet_File_Image_Cipher_Group
1426 eet_data_image_encode_cipher(const void *data,
1427 const char *cipher_key,
1437 * @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms
1439 * Eet allows one to protect entries of an #Eet_File
1440 * individually. This may be used to ensure data was not tampered or
1441 * that third party does not read your data.
1443 * @see @ref Eet_File_Cipher_Group
1444 * @see @ref Eet_File_Image_Cipher_Group
1451 * Opaque handle that defines an identity (also known as key)
1452 * in Eet's cipher system.
1454 typedef struct _Eet_Key Eet_Key;
1461 * Callback used to request if needed the password of a private key.
1463 * @param buffer the buffer where to store the password.
1464 * @param size the maximum password size (size of buffer, including '@\0').
1465 * @param rwflag if the buffer is also readable or just writable.
1466 * @param data currently unused, may contain some context in future.
1467 * @return 1 on success and password was set to @p buffer, 0 on failure.
1470 * @ingroup Eet_Cipher_Group
1472 typedef int (*Eet_Key_Password_Callback) (char *buffer, int size, int rwflag, void *data);
1475 * Create an Eet_Key needed for signing an eet file.
1477 * The certificate should provide the public that match the private key.
1478 * No verification is done to ensure that.
1480 * @param certificate_file The file where to find the certificate.
1481 * @param private_key_file The file that contains the private key.
1482 * @param cb Function to callback if password is required to unlock
1484 * @return A key handle to use, or @c NULL on failure.
1486 * @see eet_identity_close()
1489 * @ingroup Eet_Cipher_Group
1492 eet_identity_open(const char *certificate_file,
1493 const char *private_key_file,
1494 Eet_Key_Password_Callback cb);
1497 * Close and release all ressource used by an Eet_Key. An
1498 * reference counter prevent it from being freed until all file
1499 * using it are also closed.
1501 * @param key the key handle to close and free resources.
1504 * @ingroup Eet_Cipher_Group
1507 eet_identity_close(Eet_Key *key);
1510 * Set a key to sign a file
1512 * @param ef the file to set the identity.
1513 * @param key the key handle to set as identity.
1514 * @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or
1515 * #EET_ERROR_NONE on success.
1518 * @ingroup Eet_Cipher_Group
1521 eet_identity_set(Eet_File *ef,
1525 * Display both private and public key of an Eet_Key.
1527 * @param key the handle to print.
1528 * @param out where to print.
1531 * @ingroup Eet_Cipher_Group
1534 eet_identity_print(Eet_Key *key,
1538 * Get the x509 der certificate associated with an Eet_File. Will return NULL
1539 * if the file is not signed.
1541 * @param ef The file handle to query.
1542 * @param der_length The length of returned data, may be @c NULL.
1543 * @return the x509 certificate or @c NULL on error.
1546 * @ingroup Eet_Cipher_Group
1549 eet_identity_x509(Eet_File *ef,
1553 * Get the raw signature associated with an Eet_File. Will return NULL
1554 * if the file is not signed.
1556 * @param ef The file handle to query.
1557 * @param signature_length The length of returned data, may be @c NULL.
1558 * @return the raw signature or @c NULL on error.
1560 * @ingroup Eet_Cipher_Group
1563 eet_identity_signature(Eet_File *ef,
1564 int *signature_length);
1567 * Get the SHA1 associated with a file. Could be the one used to
1568 * sign the data or if the data where not signed, it will be the
1571 * @param ef The file handle to query.
1572 * @param sha1_length The length of returned data, may be @c NULL.
1573 * @return the associated SHA1 or @c NULL on error.
1576 * @ingroup Eet_Cipher_Group
1579 eet_identity_sha1(Eet_File *ef,
1583 * Display the x509 der certificate to out.
1585 * @param certificate the x509 certificate to print
1586 * @param der_length The length the certificate.
1587 * @param out where to print.
1590 * @ingroup Eet_Cipher_Group
1593 eet_identity_certificate_print(const unsigned char *certificate,
1598 * @defgroup Eet_Data_Group Eet Data Serialization
1600 * Convenience functions to serialize and parse complex data
1601 * structures to binary blobs.
1603 * While Eet core just handles binary blobs, it is often required
1604 * to save some structured data of different types, such as
1605 * strings, integers, lists, hashes and so on.
1607 * Eet can serialize and then parse data types given some
1608 * construction instructions. These are defined in two levels:
1610 * - #Eet_Data_Descriptor_Class to tell generic memory handling,
1611 * such as the size of the type, how to allocate memory, strings,
1612 * lists, hashes and so on.
1614 * - #Eet_Data_Descriptor to tell inside such type, the members and
1615 * their offsets inside the memory blob, their types and
1616 * names. These members can be simple types or other
1617 * #Eet_Data_Descriptor, allowing hierarchical types to be
1620 * Given that C provides no introspection, this process can be
1621 * quite cumbersome, so we provide lots of macros and convenience
1622 * functions to aid creating the types.
1630 * typedef struct _blah2
1635 * typedef struct _blah3
1640 * typedef struct _blah
1647 * double floating_lots;
1654 * main(int argc, char **argv)
1659 * Eet_Data_Descriptor *edd, *edd2, *edd3;
1660 * Eet_Data_Descriptor_Class eddc, eddc2, eddc3;
1668 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc3, Blah3);
1669 * edd3 = eet_data_descriptor_stream_new(&eddc3);
1670 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd3, Blah3, "string3", string, EET_T_STRING);
1672 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc2, Blah2);
1673 * edd2 = eet_data_descriptor_stream_new(&eddc2);
1674 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd2, Blah2, "string2", string, EET_T_STRING);
1676 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc, Blah);
1677 * edd = eet_data_descriptor_stream_new(&eddc);
1678 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "character", character, EET_T_CHAR);
1679 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "sixteen", sixteen, EET_T_SHORT);
1680 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "integer", integer, EET_T_INT);
1681 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "lots", lots, EET_T_LONG_LONG);
1682 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating", floating, EET_T_FLOAT);
1683 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating_lots", floating_lots, EET_T_DOUBLE);
1684 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "string", string, EET_T_STRING);
1685 * EET_DATA_DESCRIPTOR_ADD_SUB(edd, Blah, "blah2", blah2, edd2);
1686 * EET_DATA_DESCRIPTOR_ADD_LIST(edd, Blah, "blah3", blah3, edd3);
1688 * blah3.string = "PANTS";
1690 * blah2.string = "subtype string here!";
1692 * blah.character = '7';
1693 * blah.sixteen = 0x7777;
1694 * blah.integer = 0xc0def00d;
1695 * blah.lots = 0xdeadbeef31337777;
1696 * blah.floating = 3.141592654;
1697 * blah.floating_lots = 0.777777777777777;
1698 * blah.string = "bite me like a turnip";
1699 * blah.blah2 = &blah2;
1700 * blah.blah3 = eina_list_append(NULL, &blah3);
1701 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1702 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1703 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1704 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1705 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1706 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1708 * data = eet_data_descriptor_encode(edd, &blah, &size);
1709 * printf("-----DECODING\n");
1710 * blah_in = eet_data_descriptor_decode(edd, data, size);
1712 * printf("-----DECODED!\n");
1713 * printf("%c\n", blah_in->character);
1714 * printf("%x\n", (int)blah_in->sixteen);
1715 * printf("%x\n", blah_in->integer);
1716 * printf("%lx\n", blah_in->lots);
1717 * printf("%f\n", (double)blah_in->floating);
1718 * printf("%f\n", (double)blah_in->floating_lots);
1719 * printf("%s\n", blah_in->string);
1720 * printf("%p\n", blah_in->blah2);
1721 * printf(" %s\n", blah_in->blah2->string);
1726 * EINA_LIST_FOREACH(blah_in->blah3, l, blah3_in)
1728 * printf("%p\n", blah3_in);
1729 * printf(" %s\n", blah3_in->string);
1732 * eet_data_descriptor_free(edd);
1733 * eet_data_descriptor_free(edd2);
1734 * eet_data_descriptor_free(edd3);
1744 #define EET_T_UNKNOW 0 /**< Unknown data encoding type */
1745 #define EET_T_CHAR 1 /**< Data type: char */
1746 #define EET_T_SHORT 2 /**< Data type: short */
1747 #define EET_T_INT 3 /**< Data type: int */
1748 #define EET_T_LONG_LONG 4 /**< Data type: long long */
1749 #define EET_T_FLOAT 5 /**< Data type: float */
1750 #define EET_T_DOUBLE 6 /**< Data type: double */
1751 #define EET_T_UCHAR 7 /**< Data type: unsigned char */
1752 #define EET_T_USHORT 8 /**< Data type: unsigned short */
1753 #define EET_T_UINT 9 /**< Data type: unsigned int */
1754 #define EET_T_ULONG_LONG 10 /**< Data type: unsigned long long */
1755 #define EET_T_STRING 11 /**< Data type: char * */
1756 #define EET_T_INLINED_STRING 12 /**< Data type: char * (but compressed inside the resulting eet) */
1757 #define EET_T_NULL 13 /**< Data type: (void *) (only use it if you know why) */
1758 #define EET_T_F32P32 14 /**< Data type: fixed point 32.32 */
1759 #define EET_T_F16P16 15 /**< Data type: fixed point 16.16 */
1760 #define EET_T_F8P24 16 /**< Data type: fixed point 8.24 */
1761 #define EET_T_LAST 18 /**< Last data type */
1763 #define EET_G_UNKNOWN 100 /**< Unknown group data encoding type */
1764 #define EET_G_ARRAY 101 /**< Fixed size array group type */
1765 #define EET_G_VAR_ARRAY 102 /**< Variable size array group type */
1766 #define EET_G_LIST 103 /**< Linked list group type */
1767 #define EET_G_HASH 104 /**< Hash table group type */
1768 #define EET_G_UNION 105 /**< Union group type */
1769 #define EET_G_VARIANT 106 /**< Selectable subtype group */
1770 #define EET_G_LAST 107 /**< Last group type */
1772 #define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */
1775 * @typedef Eet_Data_Descriptor
1777 * Opaque handle that have information on a type members.
1779 * The members are added by means of
1780 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(),
1781 * EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH()
1782 * or eet_data_descriptor_element_add().
1784 * @see eet_data_descriptor_stream_new()
1785 * @see eet_data_descriptor_file_new()
1786 * @see eet_data_descriptor_free()
1788 typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor;
1791 * @def EET_DATA_DESCRIPTOR_CLASS_VERSION
1792 * The version of #Eet_Data_Descriptor_Class at the time of the
1793 * distribution of the sources. One should define this to its
1794 * version member so it is compatible with abi changes, or at least
1795 * will not crash with them.
1797 #define EET_DATA_DESCRIPTOR_CLASS_VERSION 4
1800 * @typedef Eet_Data_Descriptor_Class
1802 * Instructs Eet about memory management for different needs under
1803 * serialization and parse process.
1805 typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
1807 typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt);
1809 typedef void *(*Eet_Descriptor_Mem_Alloc_Callback)(size_t size);
1810 typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem);
1811 typedef char *(*Eet_Descriptor_Str_Alloc_Callback)(const char *str);
1812 typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str);
1813 typedef void *(*Eet_Descriptor_List_Next_Callback)(void *l);
1814 typedef void *(*Eet_Descriptor_List_Append_Callback)(void *l, void *d);
1815 typedef void *(*Eet_Descriptor_List_Data_Callback)(void *l);
1816 typedef void *(*Eet_Descriptor_List_Free_Callback)(void *l);
1817 typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt);
1818 typedef void *(*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d);
1819 typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h);
1820 typedef char *(*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str);
1821 typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str);
1822 typedef const char *(*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow);
1823 typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow);
1824 typedef void *(*Eet_Descriptor_Array_Alloc_Callback)(size_t size);
1825 typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem);
1827 * @struct _Eet_Data_Descriptor_Class
1829 * Instructs Eet about memory management for different needs under
1830 * serialization and parse process.
1832 * If using Eina data types, it is advised to use the helpers
1833 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
1834 * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET().
1836 struct _Eet_Data_Descriptor_Class
1838 int version; /**< ABI version as #EET_DATA_DESCRIPTOR_CLASS_VERSION */
1839 const char *name; /**< Name of data type to be serialized */
1840 int size; /**< Size in bytes of data type to be serialized */
1842 Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to allocate memory (usually malloc()) */
1843 Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free memory (usually free()) */
1844 Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to allocate a string */
1845 Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a string */
1846 Eet_Descriptor_List_Next_Callback list_next; /**< how to iterate to the next element of a list. Receives and should return the list node. */
1847 Eet_Descriptor_List_Append_Callback list_append; /**< how to append data @p d to list which head node is @p l */
1848 Eet_Descriptor_List_Data_Callback list_data; /**< retrieves the data from node @p l */
1849 Eet_Descriptor_List_Free_Callback list_free; /**< free all the nodes from the list which head node is @p l */
1850 Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates over all elements in the hash @p h in no specific order */
1851 Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new data @p d as key @p k in hash @p h */
1852 Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all entries from the hash @p h */
1853 Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */
1854 Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to free a string returned by str_direct_alloc */
1855 Eet_Descriptor_Type_Get_Callback type_get; /**< convert any kind of data type to a name that define an Eet_Data_Element. */
1856 Eet_Descriptor_Type_Set_Callback type_set; /**< set the type at a particular address */
1857 Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to allocate memory for array (usually malloc()) */
1858 Eet_Descriptor_Array_Free_Callback array_free; /**< how to free memory for array (usually free()) */
1868 * Create a new empty data structure descriptor.
1869 * @param name The string name of this data structure (most be a
1870 * global constant and never change).
1871 * @param size The size of the struct (in bytes).
1872 * @param func_list_next The function to get the next list node.
1873 * @param func_list_append The function to append a member to a list.
1874 * @param func_list_data The function to get the data from a list node.
1875 * @param func_list_free The function to free an entire linked list.
1876 * @param func_hash_foreach The function to iterate through all
1877 * hash table entries.
1878 * @param func_hash_add The function to add a member to a hash table.
1879 * @param func_hash_free The function to free an entire hash table.
1880 * @return A new empty data descriptor.
1882 * This function creates a new data descriptore and returns a handle to the
1883 * new data descriptor. On creation it will be empty, containing no contents
1884 * describing anything other than the shell of the data structure.
1886 * You add structure members to the data descriptor using the macros
1887 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
1888 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
1889 * adding to the description.
1891 * Once you have described all the members of a struct you want loaded, or
1892 * saved eet can load and save those members for you, encode them into
1893 * endian-independent serialised data chunks for transmission across a
1894 * a network or more.
1896 * The function pointers to the list and hash table functions are only
1897 * needed if you use those data types, else you can pass NULL instead.
1900 * @ingroup Eet_Data_Group
1902 * @deprecated use eet_data_descriptor_stream_new() or
1903 * eet_data_descriptor_file_new()
1905 EINA_DEPRECATED EAPI Eet_Data_Descriptor *
1906 eet_data_descriptor_new(const char *name,
1908 Eet_Descriptor_List_Next_Callback func_list_next,
1909 Eet_Descriptor_List_Append_Callback func_list_append,
1910 Eet_Descriptor_List_Data_Callback func_list_data,
1911 Eet_Descriptor_List_Free_Callback func_list_free,
1912 Eet_Descriptor_Hash_Foreach_Callback func_hash_foreach,
1913 Eet_Descriptor_Hash_Add_Callback func_hash_add,
1914 Eet_Descriptor_Hash_Free_Callback func_hash_free);
1918 * moving to this api from the old above. this will break things when the
1919 * move happens - but be warned
1921 EINA_DEPRECATED EAPI Eet_Data_Descriptor *
1922 eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc);
1923 EINA_DEPRECATED EAPI Eet_Data_Descriptor *
1924 eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc);
1927 * This function creates a new data descriptore and returns a handle to the
1928 * new data descriptor. On creation it will be empty, containing no contents
1929 * describing anything other than the shell of the data structure.
1930 * @param eddc The data descriptor to free.
1932 * You add structure members to the data descriptor using the macros
1933 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
1934 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
1935 * adding to the description.
1937 * Once you have described all the members of a struct you want loaded, or
1938 * saved eet can load and save those members for you, encode them into
1939 * endian-independent serialised data chunks for transmission across a
1940 * a network or more.
1942 * This function specially ignore str_direct_alloc and str_direct_free. It
1943 * is useful when the eet_data you are reading don't have a dictionnary
1944 * like network stream or ipc. It also mean that all string will be allocated
1945 * and duplicated in memory.
1948 * @ingroup Eet_Data_Group
1950 EAPI Eet_Data_Descriptor *
1951 eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc);
1954 * This function creates a new data descriptore and returns a handle to the
1955 * new data descriptor. On creation it will be empty, containing no contents
1956 * describing anything other than the shell of the data structure.
1957 * @param eddc The data descriptor to free.
1959 * You add structure members to the data descriptor using the macros
1960 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
1961 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
1962 * adding to the description.
1964 * Once you have described all the members of a struct you want loaded, or
1965 * saved eet can load and save those members for you, encode them into
1966 * endian-independent serialised data chunks for transmission across a
1967 * a network or more.
1969 * This function use str_direct_alloc and str_direct_free. It is
1970 * useful when the eet_data you are reading come from a file and
1971 * have a dictionnary. This will reduce memory use, improve the
1972 * possibility for the OS to page this string out. But be carrefull
1973 * all EET_T_STRING are pointer to a mmapped area and it will point
1974 * to nowhere if you close the file. So as long as you use this
1975 * strings, you need to have the Eet_File open.
1978 * @ingroup Eet_Data_Group
1980 EAPI Eet_Data_Descriptor *
1981 eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc);
1984 * This function is an helper that set all the parameter of an
1985 * Eet_Data_Descriptor_Class correctly when you use Eina data type
1987 * @param eddc The Eet_Data_Descriptor_Class you want to set.
1988 * @param name The name of the structure described by this class.
1989 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
1990 * @param size The size of the structure described by this class.
1991 * @return EINA_TRUE if the structure was correctly set (The only
1992 * reason that could make it fail is if you did give wrong
1996 * @ingroup Eet_Data_Group
1999 eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
2000 unsigned int eddc_size,
2005 * This macro is an helper that set all the parameter of an
2006 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2008 * @param clas The Eet_Data_Descriptor_Class you want to set.
2009 * @param type The type of the structure described by this class.
2010 * @return EINA_TRUE if the structure was correctly set (The only
2011 * reason that could make it fail is if you did give wrong
2015 * @ingroup Eet_Data_Group
2017 #define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type)\
2018 (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
2021 * This function is an helper that set all the parameter of an
2022 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2024 * @param eddc The Eet_Data_Descriptor_Class you want to set.
2025 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
2026 * @param name The name of the structure described by this class.
2027 * @param size The size of the structure described by this class.
2028 * @return EINA_TRUE if the structure was correctly set (The only
2029 * reason that could make it fail is if you did give wrong
2033 * @ingroup Eet_Data_Group
2036 eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
2037 unsigned int eddc_size,
2042 * This macro is an helper that set all the parameter of an
2043 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2045 * @param clas The Eet_Data_Descriptor_Class you want to set.
2046 * @param type The type of the structure described by this class.
2047 * @return EINA_TRUE if the structure was correctly set (The only
2048 * reason that could make it fail is if you did give wrong
2052 * @ingroup Eet_Data_Group
2054 #define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type)\
2055 (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
2058 * This function frees a data descriptor when it is not needed anymore.
2059 * @param edd The data descriptor to free.
2061 * This function takes a data descriptor handle as a parameter and frees all
2062 * data allocated for the data descriptor and the handle itself. After this
2063 * call the descriptor is no longer valid.
2066 * @ingroup Eet_Data_Group
2069 eet_data_descriptor_free(Eet_Data_Descriptor *edd);
2072 * This function is an internal used by macros.
2074 * This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(),
2075 * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is
2076 * complex to use by hand and should be left to be used by the macros, and
2077 * thus is not documented.
2079 * @param edd The data descriptor handle to add element (member).
2080 * @param name The name of element to be serialized.
2081 * @param type The type of element to be serialized, like
2082 * #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a
2083 * group, list or hash.
2084 * @param group_type If element type is #EET_T_UNKNOW, then the @p
2085 * group_type will speficy if it is a list (#EET_G_LIST),
2086 * array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then
2087 * the member is a subtype (pointer to another type defined by
2088 * another #Eet_Data_Descriptor).
2089 * @param offset byte offset inside the source memory to be serialized.
2090 * @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY).
2091 * @param counter_name variable that defines the name of number of elements.
2092 * @param subtype If contains a subtype, then its data descriptor.
2095 * @ingroup Eet_Data_Group
2098 eet_data_descriptor_element_add(Eet_Data_Descriptor *edd,
2103 /* int count_offset, */
2105 const char *counter_name,
2106 Eet_Data_Descriptor *subtype);
2109 * Read a data structure from an eet file and decodes it.
2110 * @param ef The eet file handle to read from.
2111 * @param edd The data descriptor handle to use when decoding.
2112 * @param name The key the data is stored under in the eet file.
2113 * @return A pointer to the decoded data structure.
2115 * This function decodes a data structure stored in an eet file, returning
2116 * a pointer to it if it decoded successfully, or NULL on failure. This
2117 * can save a programmer dozens of hours of work in writing configuration
2118 * file parsing and writing code, as eet does all that work for the program
2119 * and presents a program-friendly data structure, just as the programmer
2120 * likes. Eet can handle members being added or deleted from the data in
2121 * storage and safely zero-fills unfilled members if they were not found
2122 * in the data. It checks sizes and headers whenever it reads data, allowing
2123 * the programmer to not worry about corrupt data.
2125 * Once a data structure has been described by the programmer with the
2126 * fields they wish to save or load, storing or retrieving a data structure
2127 * from an eet file, or from a chunk of memory is as simple as a single
2130 * @see eet_data_read_cipher()
2133 * @ingroup Eet_Data_Group
2136 eet_data_read(Eet_File *ef,
2137 Eet_Data_Descriptor *edd,
2141 * Write a data structure from memory and store in an eet file.
2142 * @param ef The eet file handle to write to.
2143 * @param edd The data descriptor to use when encoding.
2144 * @param name The key to store the data under in the eet file.
2145 * @param data A pointer to the data structure to ssave and encode.
2146 * @param compress Compression flags for storage.
2147 * @return bytes written on successful write, 0 on failure.
2149 * This function is the reverse of eet_data_read(), saving a data structure
2152 * @see eet_data_write_cipher()
2155 * @ingroup Eet_Data_Group
2158 eet_data_write(Eet_File *ef,
2159 Eet_Data_Descriptor *edd,
2164 typedef void (*Eet_Dump_Callback)(void *data, const char *str);
2167 * Dump an eet encoded data structure into ascii text
2168 * @param data_in The pointer to the data to decode into a struct.
2169 * @param size_in The size of the data pointed to in bytes.
2170 * @param dumpfunc The function to call passed a string when new
2171 * data is converted to text
2172 * @param dumpdata The data to pass to the @p dumpfunc callback.
2173 * @return 1 on success, 0 on failure
2175 * This function will take a chunk of data encoded by
2176 * eet_data_descriptor_encode() and convert it into human readable
2177 * ascii text. It does this by calling the @p dumpfunc callback
2178 * for all new text that is generated. This callback should append
2179 * to any existing text buffer and will be passed the pointer @p
2180 * dumpdata as a parameter as well as a string with new text to be
2186 * void output(void *data, const char *string)
2188 * printf("%s", string);
2191 * void dump(const char *file)
2197 * f = fopen(file, "r");
2198 * fseek(f, 0, SEEK_END);
2201 * data = malloc(len);
2202 * fread(data, len, 1, f);
2204 * eet_data_text_dump(data, len, output, NULL);
2208 * @see eet_data_text_dump_cipher()
2211 * @ingroup Eet_Data_Group
2214 eet_data_text_dump(const void *data_in,
2216 Eet_Dump_Callback dumpfunc,
2220 * Take an ascii encoding from eet_data_text_dump() and re-encode in binary.
2221 * @param text The pointer to the string data to parse and encode.
2222 * @param textlen The size of the string in bytes (not including 0
2224 * @param size_ret This gets filled in with the encoded data blob
2226 * @return The encoded data on success, NULL on failure.
2228 * This function will parse the string pointed to by @p text and return
2229 * an encoded data lump the same way eet_data_descriptor_encode() takes an
2230 * in-memory data struct and encodes into a binary blob. @p text is a normal
2233 * @see eet_data_text_undump_cipher()
2236 * @ingroup Eet_Data_Group
2239 eet_data_text_undump(const char *text,
2244 * Dump an eet encoded data structure from an eet file into ascii text
2245 * @param ef A valid eet file handle.
2246 * @param name Name of the entry. eg: "/base/file_i_want".
2247 * @param dumpfunc The function to call passed a string when new
2248 * data is converted to text
2249 * @param dumpdata The data to pass to the @p dumpfunc callback.
2250 * @return 1 on success, 0 on failure
2252 * This function will take an open and valid eet file from
2253 * eet_open() request the data encoded by
2254 * eet_data_descriptor_encode() corresponding to the key @p name
2255 * and convert it into human readable ascii text. It does this by
2256 * calling the @p dumpfunc callback for all new text that is
2257 * generated. This callback should append to any existing text
2258 * buffer and will be passed the pointer @p dumpdata as a parameter
2259 * as well as a string with new text to be appended.
2261 * @see eet_data_dump_cipher()
2264 * @ingroup Eet_Data_Group
2267 eet_data_dump(Eet_File *ef,
2269 Eet_Dump_Callback dumpfunc,
2273 * Take an ascii encoding from eet_data_dump() and re-encode in binary.
2274 * @param ef A valid eet file handle.
2275 * @param name Name of the entry. eg: "/base/file_i_want".
2276 * @param text The pointer to the string data to parse and encode.
2277 * @param textlen The size of the string in bytes (not including 0
2279 * @param compress Compression flags (1 == compress, 0 = don't compress).
2280 * @return 1 on success, 0 on failure
2282 * This function will parse the string pointed to by @p text,
2283 * encode it the same way eet_data_descriptor_encode() takes an
2284 * in-memory data struct and encodes into a binary blob.
2286 * The data (optionally compressed) will be in ram, pending a flush to
2287 * disk (it will stay in ram till the eet file handle is closed though).
2289 * @see eet_data_undump_cipher()
2292 * @ingroup Eet_Data_Group
2295 eet_data_undump(Eet_File *ef,
2302 * Decode a data structure from an arbitrary location in memory.
2303 * @param edd The data descriptor to use when decoding.
2304 * @param data_in The pointer to the data to decode into a struct.
2305 * @param size_in The size of the data pointed to in bytes.
2306 * @return NULL on failure, or a valid decoded struct pointer on success.
2308 * This function will decode a data structure that has been encoded using
2309 * eet_data_descriptor_encode(), and return a data structure with all its
2310 * elements filled out, if successful, or NULL on failure.
2312 * The data to be decoded is stored at the memory pointed to by @p data_in,
2313 * and is described by the descriptor pointed to by @p edd. The data size is
2314 * passed in as the value to @p size_in, ande must be greater than 0 to
2317 * This function is useful for decoding data structures delivered to the
2318 * application by means other than an eet file, such as an IPC or socket
2319 * connection, raw files, shared memory etc.
2321 * Please see eet_data_read() for more information.
2323 * @see eet_data_descriptor_decode_cipher()
2326 * @ingroup Eet_Data_Group
2329 eet_data_descriptor_decode(Eet_Data_Descriptor *edd,
2330 const void *data_in,
2334 * Encode a dsata struct to memory and return that encoded data.
2335 * @param edd The data descriptor to use when encoding.
2336 * @param data_in The pointer to the struct to encode into data.
2337 * @param size_ret pointer to the an int to be filled with the decoded size.
2338 * @return NULL on failure, or a valid encoded data chunk on success.
2340 * This function takes a data structutre in memory and encodes it into a
2341 * serialised chunk of data that can be decoded again by
2342 * eet_data_descriptor_decode(). This is useful for being able to transmit
2343 * data structures across sockets, pipes, IPC or shared file mechanisms,
2344 * without having to worry about memory space, machine type, endianess etc.
2346 * The parameter @p edd must point to a valid data descriptor, and
2347 * @p data_in must point to the right data structure to encode. If not, the
2348 * encoding may fail.
2350 * On success a non NULL valid pointer is returned and what @p size_ret
2351 * points to is set to the size of this decoded data, in bytes. When the
2352 * encoded data is no longer needed, call free() on it. On failure NULL is
2353 * returned and what @p size_ret points to is set to 0.
2355 * Please see eet_data_write() for more information.
2357 * @see eet_data_descriptor_encode_cipher()
2360 * @ingroup Eet_Data_Group
2363 eet_data_descriptor_encode(Eet_Data_Descriptor *edd,
2364 const void *data_in,
2368 * Add a basic data element to a data descriptor.
2369 * @param edd The data descriptor to add the type to.
2370 * @param struct_type The type of the struct.
2371 * @param name The string name to use to encode/decode this member
2372 * (must be a constant global and never change).
2373 * @param member The struct member itself to be encoded.
2374 * @param type The type of the member to encode.
2376 * This macro is a convenience macro provided to add a member to
2377 * the data descriptor @p edd. The type of the structure is
2378 * provided as the @p struct_type parameter (for example: struct
2379 * my_struct). The @p name parameter defines a string that will be
2380 * used to uniquely name that member of the struct (it is suggested
2381 * to use the struct member itself). The @p member parameter is
2382 * the actual struct member itself (for eet_dictionary_string_check
2383 * example: values), and @p type is the basic data type of the
2384 * member which must be one of: EET_T_CHAR, EET_T_SHORT, EET_T_INT,
2385 * EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR,
2386 * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING.
2389 * @ingroup Eet_Data_Group
2391 #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
2393 struct_type ___ett; \
2394 eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
2395 (char *)(& (___ett.member)) - \
2396 (char *)(& (___ett)), \
2397 0, /* 0, */ NULL, NULL); \
2401 * Add a sub-element type to a data descriptor
2402 * @param edd The data descriptor to add the type to.
2403 * @param struct_type The type of the struct.
2404 * @param name The string name to use to encode/decode this member
2405 * (must be a constant global and never change).
2406 * @param member The struct member itself to be encoded.
2407 * @param subtype The type of sub-type struct to add.
2409 * This macro lets you easily add a sub-type (a struct that's pointed to
2410 * by this one). All the parameters are the same as for
2411 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception.
2412 * This must be the data descriptor of the struct that is pointed to by
2416 * @ingroup Eet_Data_Group
2418 #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
2420 struct_type ___ett; \
2421 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
2422 (char *)(& (___ett.member)) - \
2423 (char *)(& (___ett)), \
2424 0, /* 0, */ NULL, subtype); \
2428 * Add a linked list type to a data descriptor
2429 * @param edd The data descriptor to add the type to.
2430 * @param struct_type The type of the struct.
2431 * @param name The string name to use to encode/decode this member
2432 * (must be a constant global and never change).
2433 * @param member The struct member itself to be encoded.
2434 * @param subtype The type of linked list member to add.
2436 * This macro lets you easily add a linked list of other data types. All the
2437 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
2438 * @p subtype being the exception. This must be the data descriptor of the
2439 * element that is in each member of the linked list to be stored.
2442 * @ingroup Eet_Data_Group
2444 #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \
2446 struct_type ___ett; \
2447 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
2448 (char *)(& (___ett.member)) - \
2449 (char *)(& (___ett)), \
2450 0, /* 0, */ NULL, subtype); \
2454 * Add a hash type to a data descriptor
2455 * @param edd The data descriptor to add the type to.
2456 * @param struct_type The type of the struct.
2457 * @param name The string name to use to encode/decode this member
2458 * (must be a constant global and never change).
2459 * @param member The struct member itself to be encoded.
2460 * @param subtype The type of hash member to add.
2462 * This macro lets you easily add a hash of other data types. All the
2463 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
2464 * @p subtype being the exception. This must be the data descriptor of the
2465 * element that is in each member of the hash to be stored.
2468 * @ingroup Eet_Data_Group
2470 #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \
2472 struct_type ___ett; \
2473 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \
2474 (char *)(& (___ett.member)) - \
2475 (char *)(& (___ett)), \
2476 0, /* 0, */ NULL, subtype); \
2480 * Add a hash of string to a data descriptor
2481 * @param edd The data descriptor to add the type to.
2482 * @param struct_type The type of the struct.
2483 * @param name The string name to use to encode/decode this member
2484 * (must be a constant global and never change).
2485 * @param member The struct member itself to be encoded.
2487 * This macro lets you easily add a hash of string. All the
2488 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
2491 * @ingroup Eet_Data_Group
2493 #define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \
2495 struct_type ___ett; \
2496 eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH, \
2497 (char *)(& (___ett.member)) - \
2498 (char *)(& (___ett)), \
2499 0, /* 0, */ NULL, NULL); \
2503 * Add a fixed size array type to a data descriptor
2504 * @param edd The data descriptor to add the type to.
2505 * @param struct_type The type of the struct.
2506 * @param name The string name to use to encode/decode this member
2507 * (must be a constant global and never change).
2508 * @param member The struct member itself to be encoded.
2509 * @param subtype The type of hash member to add.
2511 * This macro lets you easily add a fixed size array of other data
2512 * types. All the parameters are the same as for
2513 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
2514 * exception. This must be the data descriptor of the element that
2515 * is in each member of the hash to be stored.
2518 * @ingroup Eet_Data_Group
2520 #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \
2522 struct_type ___ett; \
2523 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \
2524 (char *)(& (___ett.member)) - \
2525 (char *)(& (___ett)), \
2526 /* 0, */ sizeof(___ett.member) / \
2527 sizeof(___ett.member[0]), NULL, subtype); \
2531 * Add a variable size array type to a data descriptor
2532 * @param edd The data descriptor to add the type to.
2533 * @param struct_type The type of the struct.
2534 * @param name The string name to use to encode/decode this member
2535 * (must be a constant global and never change).
2536 * @param member The struct member itself to be encoded.
2537 * @param subtype The type of hash member to add.
2539 * This macro lets you easily add a fixed size array of other data
2540 * types. All the parameters are the same as for
2541 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
2542 * exception. This must be the data descriptor of the element that
2543 * is in each member of the hash to be stored.
2546 * @ingroup Eet_Data_Group
2548 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \
2550 struct_type ___ett; \
2551 eet_data_descriptor_element_add(edd, \
2555 (char *)(& (___ett.member)) - \
2556 (char *)(& (___ett)), \
2557 (char *)(& (___ett.member ## _count)) - \
2558 (char *)(& (___ett)), \
2564 * Add a variable size array type to a data descriptor
2565 * @param edd The data descriptor to add the type to.
2566 * @param struct_type The type of the struct.
2567 * @param name The string name to use to encode/decode this member
2568 * (must be a constant global and never change).
2569 * @param member The struct member itself to be encoded.
2571 * This macro lets you easily add a fixed size array of string. All
2572 * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
2575 * @ingroup Eet_Data_Group
2577 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member) \
2579 struct_type ___ett; \
2580 eet_data_descriptor_element_add(edd, \
2584 (char *)(& (___ett.member)) - \
2585 (char *)(& (___ett)), \
2586 (char *)(& (___ett.member ## _count)) - \
2587 (char *)(& (___ett)), \
2593 * Add an union type to a data descriptor
2594 * @param edd The data descriptor to add the type to.
2595 * @param struct_type The type of the struct.
2596 * @param name The string name to use to encode/decode this member
2597 * (must be a constant global and never change).
2598 * @param member The struct member itself to be encoded.
2599 * @param type_member The member that give hints on what is in the union.
2600 * @param unified_type Describe all possible type the union could handle.
2602 * This macro lets you easily add an union with a member that specify what is inside.
2603 * The @p unified_type is an Eet_Data_Descriptor, but only the entry that match the name
2604 * returned by type_get will be used for each serialized data. The type_get and type_set
2605 * callback of unified_type should be defined.
2608 * @ingroup Eet_Data_Group
2609 * @see Eet_Data_Descriptor_Class
2611 #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type) \
2613 struct_type ___ett; \
2614 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, \
2615 (char *)(& (___ett.member)) - \
2616 (char *)(& (___ett)), \
2617 (char *)(& (___ett.type_member)) - \
2618 (char *)(& (___ett)), \
2619 NULL, unified_type); \
2623 * Add a automatically selectable type to a data descriptor
2624 * @param edd The data descriptor to add the type to.
2625 * @param struct_type The type of the struct.
2626 * @param name The string name to use to encode/decode this member
2627 * (must be a constant global and never change).
2628 * @param member The struct member itself to be encoded.
2629 * @param type_member The member that give hints on what is in the union.
2630 * @param unified_type Describe all possible type the union could handle.
2632 * This macro lets you easily define what the content of @p member points to depending of
2633 * the content of @p type_member. The type_get and type_set callback of unified_type should
2634 * be defined. If the the type is not know at the time of restoring it, eet will still call
2635 * type_set of @p unified_type but the pointer will be set to a serialized binary representation
2636 * of what eet know. This make it possible, to save this pointer again by just returning the string
2637 * given previously and telling it by setting unknow to EINA_TRUE.
2640 * @ingroup Eet_Data_Group
2641 * @see Eet_Data_Descriptor_Class
2643 #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type) \
2645 struct_type ___ett; \
2646 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT, \
2647 (char *)(& (___ett.member)) - \
2648 (char *)(& (___ett)), \
2649 (char *)(& (___ett.type_member)) - \
2650 (char *)(& (___ett)), \
2651 NULL, unified_type); \
2655 * Add a mapping to a data descriptor that will be used by union, variant or inherited type
2656 * @param unified_type The data descriptor to add the mapping to.
2657 * @param name The string name to get/set type.
2658 * @param subtype The matching data descriptor.
2661 * @ingroup Eet_Data_Group
2662 * @see Eet_Data_Descriptor_Class
2664 #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \
2665 eet_data_descriptor_element_add(unified_type, \
2675 * @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers
2677 * Most of the @ref Eet_Data_Group have alternative versions that
2678 * accounts for ciphers to protect their content.
2680 * @see @ref Eet_Cipher_Group
2682 * @ingroup Eet_Data_Group
2686 * Read a data structure from an eet file and decodes it using a cipher.
2687 * @param ef The eet file handle to read from.
2688 * @param edd The data descriptor handle to use when decoding.
2689 * @param name The key the data is stored under in the eet file.
2690 * @param cipher_key The key to use as cipher.
2691 * @return A pointer to the decoded data structure.
2693 * This function decodes a data structure stored in an eet file, returning
2694 * a pointer to it if it decoded successfully, or NULL on failure. This
2695 * can save a programmer dozens of hours of work in writing configuration
2696 * file parsing and writing code, as eet does all that work for the program
2697 * and presents a program-friendly data structure, just as the programmer
2698 * likes. Eet can handle members being added or deleted from the data in
2699 * storage and safely zero-fills unfilled members if they were not found
2700 * in the data. It checks sizes and headers whenever it reads data, allowing
2701 * the programmer to not worry about corrupt data.
2703 * Once a data structure has been described by the programmer with the
2704 * fields they wish to save or load, storing or retrieving a data structure
2705 * from an eet file, or from a chunk of memory is as simple as a single
2708 * @see eet_data_read()
2711 * @ingroup Eet_Data_Cipher_Group
2714 eet_data_read_cipher(Eet_File *ef,
2715 Eet_Data_Descriptor *edd,
2717 const char *cipher_key);
2720 * Write a data structure from memory and store in an eet file
2722 * @param ef The eet file handle to write to.
2723 * @param edd The data descriptor to use when encoding.
2724 * @param name The key to store the data under in the eet file.
2725 * @param cipher_key The key to use as cipher.
2726 * @param data A pointer to the data structure to ssave and encode.
2727 * @param compress Compression flags for storage.
2728 * @return bytes written on successful write, 0 on failure.
2730 * This function is the reverse of eet_data_read(), saving a data structure
2733 * @see eet_data_write_cipher()
2736 * @ingroup Eet_Data_Cipher_Group
2739 eet_data_write_cipher(Eet_File *ef,
2740 Eet_Data_Descriptor *edd,
2742 const char *cipher_key,
2747 * Dump an eet encoded data structure into ascii text using a cipher.
2748 * @param data_in The pointer to the data to decode into a struct.
2749 * @param cipher_key The key to use as cipher.
2750 * @param size_in The size of the data pointed to in bytes.
2751 * @param dumpfunc The function to call passed a string when new
2752 * data is converted to text
2753 * @param dumpdata The data to pass to the @p dumpfunc callback.
2754 * @return 1 on success, 0 on failure
2756 * This function will take a chunk of data encoded by
2757 * eet_data_descriptor_encode() and convert it into human readable
2758 * ascii text. It does this by calling the @p dumpfunc callback
2759 * for all new text that is generated. This callback should append
2760 * to any existing text buffer and will be passed the pointer @p
2761 * dumpdata as a parameter as well as a string with new text to be
2767 * void output(void *data, const char *string)
2769 * printf("%s", string);
2772 * void dump(const char *file)
2778 * f = fopen(file, "r");
2779 * fseek(f, 0, SEEK_END);
2782 * data = malloc(len);
2783 * fread(data, len, 1, f);
2785 * eet_data_text_dump_cipher(data, cipher_key, len, output, NULL);
2789 * @see eet_data_text_dump()
2792 * @ingroup Eet_Data_Cipher_Group
2795 eet_data_text_dump_cipher(const void *data_in,
2796 const char *cipher_key,
2798 Eet_Dump_Callback dumpfunc,
2802 * Take an ascii encoding from eet_data_text_dump() and re-encode
2803 * in binary using a cipher.
2804 * @param text The pointer to the string data to parse and encode.
2805 * @param cipher_key The key to use as cipher.
2806 * @param textlen The size of the string in bytes (not including 0
2808 * @param size_ret This gets filled in with the encoded data blob
2810 * @return The encoded data on success, NULL on failure.
2812 * This function will parse the string pointed to by @p text and return
2813 * an encoded data lump the same way eet_data_descriptor_encode() takes an
2814 * in-memory data struct and encodes into a binary blob. @p text is a normal
2817 * @see eet_data_text_undump()
2820 * @ingroup Eet_Data_Cipher_Group
2823 eet_data_text_undump_cipher(const char *text,
2824 const char *cipher_key,
2829 * Dump an eet encoded data structure from an eet file into ascii
2830 * text using a cipher.
2831 * @param ef A valid eet file handle.
2832 * @param name Name of the entry. eg: "/base/file_i_want".
2833 * @param cipher_key The key to use as cipher.
2834 * @param dumpfunc The function to call passed a string when new
2835 * data is converted to text
2836 * @param dumpdata The data to pass to the @p dumpfunc callback.
2837 * @return 1 on success, 0 on failure
2839 * This function will take an open and valid eet file from
2840 * eet_open() request the data encoded by
2841 * eet_data_descriptor_encode() corresponding to the key @p name
2842 * and convert it into human readable ascii text. It does this by
2843 * calling the @p dumpfunc callback for all new text that is
2844 * generated. This callback should append to any existing text
2845 * buffer and will be passed the pointer @p dumpdata as a parameter
2846 * as well as a string with new text to be appended.
2848 * @see eet_data_dump()
2851 * @ingroup Eet_Data_Cipher_Group
2854 eet_data_dump_cipher(Eet_File *ef,
2856 const char *cipher_key,
2857 Eet_Dump_Callback dumpfunc,
2861 * Take an ascii encoding from eet_data_dump() and re-encode in
2862 * binary using a cipher.
2863 * @param ef A valid eet file handle.
2864 * @param name Name of the entry. eg: "/base/file_i_want".
2865 * @param cipher_key The key to use as cipher.
2866 * @param text The pointer to the string data to parse and encode.
2867 * @param textlen The size of the string in bytes (not including 0
2869 * @param compress Compression flags (1 == compress, 0 = don't compress).
2870 * @return 1 on success, 0 on failure
2872 * This function will parse the string pointed to by @p text,
2873 * encode it the same way eet_data_descriptor_encode() takes an
2874 * in-memory data struct and encodes into a binary blob.
2876 * The data (optionally compressed) will be in ram, pending a flush to
2877 * disk (it will stay in ram till the eet file handle is closed though).
2879 * @see eet_data_undump()
2882 * @ingroup Eet_Data_Cipher_Group
2885 eet_data_undump_cipher(Eet_File *ef,
2887 const char *cipher_key,
2893 * Decode a data structure from an arbitrary location in memory
2895 * @param edd The data descriptor to use when decoding.
2896 * @param data_in The pointer to the data to decode into a struct.
2897 * @param cipher_key The key to use as cipher.
2898 * @param size_in The size of the data pointed to in bytes.
2899 * @return NULL on failure, or a valid decoded struct pointer on success.
2901 * This function will decode a data structure that has been encoded using
2902 * eet_data_descriptor_encode(), and return a data structure with all its
2903 * elements filled out, if successful, or NULL on failure.
2905 * The data to be decoded is stored at the memory pointed to by @p data_in,
2906 * and is described by the descriptor pointed to by @p edd. The data size is
2907 * passed in as the value to @p size_in, ande must be greater than 0 to
2910 * This function is useful for decoding data structures delivered to the
2911 * application by means other than an eet file, such as an IPC or socket
2912 * connection, raw files, shared memory etc.
2914 * Please see eet_data_read() for more information.
2916 * @see eet_data_descriptor_decode()
2919 * @ingroup Eet_Data_Cipher_Group
2922 eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd,
2923 const void *data_in,
2924 const char *cipher_key,
2928 * Encode a data struct to memory and return that encoded data
2930 * @param edd The data descriptor to use when encoding.
2931 * @param data_in The pointer to the struct to encode into data.
2932 * @param cipher_key The key to use as cipher.
2933 * @param size_ret pointer to the an int to be filled with the decoded size.
2934 * @return NULL on failure, or a valid encoded data chunk on success.
2936 * This function takes a data structutre in memory and encodes it into a
2937 * serialised chunk of data that can be decoded again by
2938 * eet_data_descriptor_decode(). This is useful for being able to transmit
2939 * data structures across sockets, pipes, IPC or shared file mechanisms,
2940 * without having to worry about memory space, machine type, endianess etc.
2942 * The parameter @p edd must point to a valid data descriptor, and
2943 * @p data_in must point to the right data structure to encode. If not, the
2944 * encoding may fail.
2946 * On success a non NULL valid pointer is returned and what @p size_ret
2947 * points to is set to the size of this decoded data, in bytes. When the
2948 * encoded data is no longer needed, call free() on it. On failure NULL is
2949 * returned and what @p size_ret points to is set to 0.
2951 * Please see eet_data_write() for more information.
2953 * @see eet_data_descriptor_encode()
2956 * @ingroup Eet_Data_Cipher_Group
2959 eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd,
2960 const void *data_in,
2961 const char *cipher_key,
2965 * @defgroup Eet_Node_Group Low-level Serialization Structures.
2967 * Functions that create, destroy and manipulate serialization nodes
2968 * used by @ref Eet_Data_Group.
2975 * Opaque handle to manage serialization node.
2977 typedef struct _Eet_Node Eet_Node;
2980 * @typedef Eet_Node_Data
2981 * Contains an union that can fit any kind of node.
2983 typedef struct _Eet_Node_Data Eet_Node_Data;
2986 * @struct _Eet_Node_Data
2987 * Contains an union that can fit any kind of node.
2989 struct _Eet_Node_Data
3001 unsigned long long ul;
3012 * @ingroup Eet_Node_Group
3015 eet_node_char_new(const char *name,
3020 * @ingroup Eet_Node_Group
3023 eet_node_short_new(const char *name,
3028 * @ingroup Eet_Node_Group
3031 eet_node_int_new(const char *name,
3036 * @ingroup Eet_Node_Group
3039 eet_node_long_long_new(const char *name,
3044 * @ingroup Eet_Node_Group
3047 eet_node_float_new(const char *name,
3052 * @ingroup Eet_Node_Group
3055 eet_node_double_new(const char *name,
3060 * @ingroup Eet_Node_Group
3063 eet_node_unsigned_char_new(const char *name,
3068 * @ingroup Eet_Node_Group
3071 eet_node_unsigned_short_new(const char *name,
3076 * @ingroup Eet_Node_Group
3079 eet_node_unsigned_int_new(const char *name,
3084 * @ingroup Eet_Node_Group
3087 eet_node_unsigned_long_long_new(const char *name,
3088 unsigned long long l);
3092 * @ingroup Eet_Node_Group
3095 eet_node_string_new(const char *name,
3100 * @ingroup Eet_Node_Group
3103 eet_node_inlined_string_new(const char *name,
3108 * @ingroup Eet_Node_Group
3111 eet_node_null_new(const char *name);
3115 * @ingroup Eet_Node_Group
3118 eet_node_list_new(const char *name,
3123 * @ingroup Eet_Node_Group
3126 eet_node_array_new(const char *name,
3132 * @ingroup Eet_Node_Group
3135 eet_node_var_array_new(const char *name,
3140 * @ingroup Eet_Node_Group
3143 eet_node_hash_new(const char *name,
3149 * @ingroup Eet_Node_Group
3152 eet_node_struct_new(const char *name,
3157 * @ingroup Eet_Node_Group
3160 eet_node_struct_child_new(const char *parent,
3165 * @ingroup Eet_Node_Group
3168 eet_node_list_append(Eet_Node *parent,
3174 * @ingroup Eet_Node_Group
3177 eet_node_struct_append(Eet_Node *parent,
3183 * @ingroup Eet_Node_Group
3186 eet_node_hash_add(Eet_Node *parent,
3193 * @ingroup Eet_Node_Group
3196 eet_node_dump(Eet_Node *n,
3198 Eet_Dump_Callback dumpfunc,
3203 * @ingroup Eet_Node_Group
3206 eet_node_del(Eet_Node *n);
3210 * @ingroup Eet_Node_Group
3213 eet_data_node_encode_cipher(Eet_Node *node,
3214 const char *cipher_key,
3219 * @ingroup Eet_Node_Group
3222 eet_data_node_decode_cipher(const void *data_in,
3223 const char *cipher_key,
3228 * @ingroup Eet_Node_Group
3231 eet_data_node_read_cipher(Eet_File *ef,
3233 const char *cipher_key);
3237 * @ingroup Eet_Node_Group
3240 eet_data_node_write_cipher(Eet_File *ef,
3242 const char *cipher_key,
3246 /* EXPERIMENTAL: THIS API MAY CHANGE IN THE FUTURE, USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING. */
3249 * @typedef Eet_Node_Walk
3250 * Describes how to walk trees of #Eet_Node.
3252 typedef struct _Eet_Node_Walk Eet_Node_Walk;
3254 typedef void *(*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void *user_data);
3255 typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char *name, void *child, void *user_data);
3256 typedef void *(*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const char *name, int count, void *user_data);
3257 typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void *child, void *user_data);
3258 typedef void *(*Eet_Node_Walk_List_Callback)(const char *name, void *user_data);
3259 typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, void *user_data);
3260 typedef void *(*Eet_Node_Walk_Hash_Callback)(void *parent, const char *name, const char *key, void *value, void *user_data);
3261 typedef void *(*Eet_Node_Walk_Simple_Callback)(int type, Eet_Node_Data *data, void *user_data);
3264 * @struct _Eet_Node_Walk
3265 * Describes how to walk trees of #Eet_Node.
3267 struct _Eet_Node_Walk
3269 Eet_Node_Walk_Struct_Alloc_Callback struct_alloc;
3270 Eet_Node_Walk_Struct_Add_Callback struct_add;
3271 Eet_Node_Walk_Array_Callback array;
3272 Eet_Node_Walk_Insert_Callback insert;
3273 Eet_Node_Walk_List_Callback list;
3274 Eet_Node_Walk_Append_Callback append;
3275 Eet_Node_Walk_Hash_Callback hash;
3276 Eet_Node_Walk_Simple_Callback simple;
3280 eet_node_walk(void *parent,
3289 * @defgroup Eet_Connection_Group Helper function to use eet over a network link
3291 * Function that reconstruct and prepare packet of @ref Eet_Data_Group to be send.
3296 * @typedef Eet_Connection
3297 * Opaque handle to track paquet for a specific connection.
3299 * @ingroup Eet_Connection_Group
3301 typedef struct _Eet_Connection Eet_Connection;
3304 * @typedef Eet_Read_Cb
3305 * Called back when an @ref Eet_Data_Group has been received completly and could be used.
3307 * @ingroup Eet_Connection_Group
3309 typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *user_data);
3312 * @typedef Eet_Write_Cb
3313 * Called back when a packet containing @ref Eet_Data_Group data is ready to be send.
3315 * @ingroup Eet_Connection_Group
3317 typedef Eina_Bool Eet_Write_Cb (const void *data, size_t size, void *user_data);
3320 * Instanciate a new connection to track.
3321 * @param eet_read_cb Function to call when one Eet_Data packet has been fully assemble.
3322 * @param eet_write_cb Function to call when one Eet_Data packet is ready to be send over the wire.
3323 * @param user_data Pointer provided to both functions to be used as a context handler.
3324 * @return NULL on failure, or a valid Eet_Connection handler.
3326 * For every connection to track you will need a separate Eet_Connection provider.
3329 * @ingroup Eet_Connection_Group
3331 EAPI Eet_Connection *
3332 eet_connection_new(Eet_Read_Cb *eet_read_cb,
3333 Eet_Write_Cb *eet_write_cb,
3334 const void *user_data);
3337 * Process a raw packet received over the link
3338 * @param conn Connection handler to track.
3339 * @param data Raw data packet.
3340 * @param size The size of that packet.
3341 * @return 0 on complete success, any other value indicate where in the stream it got wrong (It could be before that packet).
3343 * Every time you receive a packet related to your connection, you should pass
3344 * it to that function so that it could process and assemble packet has you
3345 * receive it. It will automatically call Eet_Read_Cb when one is fully received.
3348 * @ingroup Eet_Connection_Group
3351 eet_connection_received(Eet_Connection *conn,
3356 * Convert a complex structure and prepare it to be send.
3357 * @param conn Connection handler to track.
3358 * @param edd The data descriptor to use when encoding.
3359 * @param data_in The pointer to the struct to encode into data.
3360 * @param cipher_key The key to use as cipher.
3361 * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
3363 * This function serialize data_in with edd, assemble the packet and call
3364 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
3365 * and will vanish just after the return of the callback.
3367 * @see eet_data_descriptor_encode_cipher
3370 * @ingroup Eet_Connection_Group
3373 eet_connection_send(Eet_Connection *conn,
3374 Eet_Data_Descriptor *edd,
3375 const void *data_in,
3376 const char *cipher_key);
3379 * Convert a Eet_Node tree and prepare it to be send.
3380 * @param conn Connection handler to track.
3381 * @param node The data tree to use when encoding.
3382 * @param cipher_key The key to use as cipher.
3383 * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
3385 * This function serialize node, assemble the packet and call
3386 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
3387 * and will vanish just after the return of the callback.
3389 * @see eet_data_node_encode_cipher
3392 * @ingroup Eet_Connection_Group
3395 eet_connection_node_send(Eet_Connection *conn,
3397 const char *cipher_key);
3400 * Close a connection and lost its track.
3401 * @param conn Connection handler to close.
3402 * @param on_going Signal if a partial packet wasn't completed.
3403 * @return the user_data passed to both callback.
3406 * @ingroup Eet_Connection_Group
3409 eet_connection_close(Eet_Connection *conn,
3410 Eina_Bool *on_going);
3412 /***************************************************************************/
3416 #endif /* ifdef __cplusplus */
3418 #endif /* ifndef _EET_H */