15 # define EAPI __declspec(dllexport)
18 # endif /* ! DLL_EXPORT */
20 # define EAPI __declspec(dllimport)
21 # endif /* ! EFL_EET_BUILD */
25 # define EAPI __attribute__ ((visibility("default")))
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 2
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 define(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.
127 EAPI int eet_init(void);
130 * Shut down the EET library.
132 * @return The new init count.
137 EAPI int eet_shutdown(void);
142 * Eet didn't free items by default. If you are under memory
143 * presure, just call this function to recall all memory that are
144 * not yet referenced anymore. The cache take care of modification
150 EAPI void eet_clearcache(void);
154 * @defgroup Eet_File_Group Eet File Main Functions
156 * Functions to create, destroy and do basic manipulation of
163 * @enum _Eet_File_Mode
164 * Modes that a file can be opened.
166 typedef enum _Eet_File_Mode
168 EET_FILE_MODE_INVALID = -1,
169 EET_FILE_MODE_READ, /**< File is read-only. */
170 EET_FILE_MODE_WRITE, /**< File is write-only. */
171 EET_FILE_MODE_READ_WRITE /**< File is for both read and write */
172 } Eet_File_Mode; /**< Modes that a file can be opened. */
176 * Opaque handle that defines an Eet file (or memory).
179 * @see eet_memopen_read()
182 typedef struct _Eet_File Eet_File;
185 * @typedef Eet_Dictionary
186 * Opaque handle that defines a file-backed (mmaped) dictionary of strings.
188 typedef struct _Eet_Dictionary Eet_Dictionary;
196 * Open an eet file on disk, and returns a handle to it.
197 * @param file The file path to the eet file. eg: @c "/tmp/file.eet".
198 * @param mode The mode for opening. Either #EET_FILE_MODE_READ,
199 * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE.
200 * @return An opened eet file handle.
201 * @ingroup Eet_File_Group
203 * This function will open an exiting eet file for reading, and build
204 * the directory table in memory and return a handle to the file, if it
205 * exists and can be read, and no memory errors occur on the way, otherwise
206 * NULL will be returned.
208 * It will also open an eet file for writing. This will, if successful,
209 * delete the original file and replace it with a new empty file, till
210 * the eet file handle is closed or flushed. If it cannot be opened for
211 * writing or a memory error occurs, NULL is returned.
213 * You can also open the file for read/write. If you then write a key that
214 * does not exist it will be created, if the key exists it will be replaced
221 * #include <string.h>
224 * main(int argc, char **argv)
227 * char buf[1024], *ret, **list;
232 * strcpy(buf, "Here is a string of data to save!");
234 * ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE);
235 * if (!ef) return -1;
236 * if (!eet_write(ef, "/key/to_store/at", buf, 1024, 1))
237 * fprintf(stderr, "Error writing data!\n");
240 * ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_READ);
241 * if (!ef) return -1;
242 * list = eet_list(ef, "*", &num);
245 * for (i = 0; i < num; i++)
246 * printf("Key stored: %s\n", list[i]);
249 * ret = eet_read(ef, "/key/to_store/at", &size);
252 * printf("Data read (%i bytes):\n%s\n", size, ret);
265 EAPI Eet_File *eet_open(const char *file, Eet_File_Mode mode);
268 * Open an eet file directly from a memory location. The data are not copied,
269 * so you must keep them around as long as the eet file is open. Their is
270 * currently no cache for this kind of Eet_File, so it's reopen every time
271 * you do use eet_memopen_read.
274 * @ingroup Eet_File_Group
276 EAPI Eet_File *eet_memopen_read(const void *data, size_t size);
279 * Get the mode an Eet_File was opened with.
280 * @param ef A valid eet file handle.
281 * @return The mode ef was opened with.
284 * @ingroup Eet_File_Group
286 EAPI Eet_File_Mode eet_mode_get(Eet_File *ef);
289 * Close an eet file handle and flush and writes pending.
290 * @param ef A valid eet file handle.
292 * This function will flush any pending writes to disk if the eet file
293 * was opened for write, and free all data associated with the file handle
294 * and file, and close the file.
296 * If the eet file handle is not valid nothing will be done.
299 * @ingroup Eet_File_Group
301 EAPI Eet_Error eet_close(Eet_File *ef);
304 * Sync content of an eet file handle, flushing pending writes.
305 * @param ef A valid eet file handle.
307 * This function will flush any pending writes to disk. The eet file must
308 * be opened for write.
310 * If the eet file handle is not valid nothing will be done.
313 * @ingroup Eet_File_Group
315 EAPI Eet_Error eet_sync(Eet_File *ef);
318 * Return a handle to the shared string dictionary of the Eet file
319 * @param ef A valid eet file handle.
320 * @return A handle to the dictionary of the file
322 * This function returns a handle to the dictionary of an Eet file whose
323 * handle is @p ef, if a dictionary exists. NULL is returned otherwise or
324 * if the file handle is known to be invalid.
326 * @see eet_dictionary_string_check() to know if given string came
327 * from the dictionary or it was dynamically allocated using
328 * the #Eet_Data_Descriptor_Class instructrions.
331 * @ingroup Eet_File_Group
333 EAPI Eet_Dictionary *eet_dictionary_get(Eet_File *ef);
336 * Check if a given string comes from a given dictionary
337 * @param ed A valid dictionary handle
338 * @param string A valid 0 byte terminated C string
339 * @return 1 if it is in the dictionary, 0 otherwise
341 * This checks the given dictionary to see if the given string is actually
342 * inside that dictionary (i.e. comes from it) and returns 1 if it does.
343 * If the dictionary handle is invlide, the string is NULL or the string is
344 * not in the dictionary, 0 is returned.
347 * @ingroup Eet_File_Group
349 EAPI int eet_dictionary_string_check(Eet_Dictionary *ed, const char *string);
352 * Read a specified entry from an eet file and return data
353 * @param ef A valid eet file handle opened for reading.
354 * @param name Name of the entry. eg: "/base/file_i_want".
355 * @param size_ret Number of bytes read from entry and returned.
356 * @return The data stored in that entry in the eet file.
358 * This function finds an entry in the eet file that is stored under the
359 * name specified, and returns that data, decompressed, if successful.
360 * NULL is returned if the lookup fails or if memory errors are
361 * encountered. It is the job of the calling program to call free() on
362 * the returned data. The number of bytes in the returned data chunk are
363 * placed in size_ret.
365 * If the eet file handle is not valid NULL is returned and size_ret is
368 * @see eet_read_cipher()
371 * @ingroup Eet_File_Group
373 EAPI void *eet_read(Eet_File *ef, const char *name, int *size_ret);
376 * Read a specified entry from an eet file and return data
377 * @param ef A valid eet file handle opened for reading.
378 * @param name Name of the entry. eg: "/base/file_i_want".
379 * @param size_ret Number of bytes read from entry and returned.
380 * @return The data stored in that entry in the eet file.
382 * This function finds an entry in the eet file that is stored under the
383 * name specified, and returns that data if not compressed and successful.
384 * NULL is returned if the lookup fails or if memory errors are
385 * encountered or if the data is comrpessed. The calling program must never
386 * call free() on the returned data. The number of bytes in the returned
387 * data chunk are placed in size_ret.
389 * If the eet file handle is not valid NULL is returned and size_ret is
393 * @ingroup Eet_File_Group
395 EAPI const void *eet_read_direct(Eet_File *ef, const char *name, int *size_ret);
398 * Write a specified entry to an eet file handle
399 * @param ef A valid eet file handle opened for writing.
400 * @param name Name of the entry. eg: "/base/file_i_want".
401 * @param data Pointer to the data to be stored.
402 * @param size Length in bytes in the data to be stored.
403 * @param compress Compression flags (1 == compress, 0 = don't compress).
404 * @return bytes written on successful write, 0 on failure.
406 * This function will write the specified chunk of data to the eet file
407 * and return greater than 0 on success. 0 will be returned on failure.
409 * The eet file handle must be a valid file handle for an eet file opened
410 * for writing. If it is not, 0 will be returned and no action will be
413 * Name, and data must not be NULL, and size must be > 0. If these
414 * conditions are not met, 0 will be returned.
416 * The data will be copied (and optionally compressed) in ram, pending
417 * a flush to disk (it will stay in ram till the eet file handle is
420 * @see eet_write_cipher()
423 * @ingroup Eet_File_Group
425 EAPI int eet_write(Eet_File *ef, const char *name, const void *data, int size, int compress);
428 * Delete a specified entry from an Eet file being written or re-written
429 * @param ef A valid eet file handle opened for writing.
430 * @param name Name of the entry. eg: "/base/file_i_want".
431 * @return Success or failure of the delete.
433 * This function will delete the specified chunk of data from the eet file
434 * and return greater than 0 on success. 0 will be returned on failure.
436 * The eet file handle must be a valid file handle for an eet file opened
437 * for writing. If it is not, 0 will be returned and no action will be
440 * Name, must not be NULL, otherwise 0 will be returned.
443 * @ingroup Eet_File_Group
445 EAPI int eet_delete(Eet_File *ef, const char *name);
448 * List all entries in eet file matching shell glob.
449 * @param ef A valid eet file handle.
450 * @param glob A shell glob to match against.
451 * @param count_ret Number of entries found to match.
452 * @return Pointer to an array of strings.
454 * This function will list all entries in the eet file matching the
455 * supplied shell glob and return an allocated list of their names, if
456 * there are any, and if no memory errors occur.
458 * The eet file handle must be valid and glob must not be NULL, or NULL
459 * will be returned and count_ret will be filled with 0.
461 * The calling program must call free() on the array returned, but NOT
462 * on the string pointers in the array. They are taken as read-only
463 * internals from the eet file handle. They are only valid as long as
464 * the file handle is not closed. When it is closed those pointers in the
465 * array are now not valid and should not be used.
467 * On success the array returned will have a list of string pointers
468 * that are the names of the entries that matched, and count_ret will have
469 * the number of entries in this array placed in it.
471 * Hint: an easy way to list all entries in an eet file is to use a glob
475 * @ingroup Eet_File_Group
477 EAPI char **eet_list(Eet_File *ef, const char *glob, int *count_ret);
480 * Return the number of entries in the specified eet file.
481 * @param ef A valid eet file handle.
482 * @return Number of entries in ef or -1 if the number of entries
483 * cannot be read due to open mode restrictions.
486 * @ingroup Eet_File_Group
488 EAPI int eet_num_entries(Eet_File *ef);
491 * @defgroup Eet_File_Cipher_Group Eet File Ciphered Main Functions
493 * Most of the @ref Eet_File_Group have alternative versions that
494 * accounts for ciphers to protect their content.
496 * @see @ref Eet_Cipher_Group
498 * @ingroup Eet_File_Group
502 * Read a specified entry from an eet file and return data using a cipher.
503 * @param ef A valid eet file handle opened for reading.
504 * @param name Name of the entry. eg: "/base/file_i_want".
505 * @param size_ret Number of bytes read from entry and returned.
506 * @param cipher_key The key to use as cipher.
507 * @return The data stored in that entry in the eet file.
509 * This function finds an entry in the eet file that is stored under the
510 * name specified, and returns that data, decompressed, if successful.
511 * NULL is returned if the lookup fails or if memory errors are
512 * encountered. It is the job of the calling program to call free() on
513 * the returned data. The number of bytes in the returned data chunk are
514 * placed in size_ret.
516 * If the eet file handle is not valid NULL is returned and size_ret is
522 * @ingroup Eet_File_Cipher_Group
524 EAPI void *eet_read_cipher(Eet_File *ef, const char *name, int *size_ret, const char *cipher_key);
527 * Write a specified entry to an eet file handle using a cipher.
528 * @param ef A valid eet file handle opened for writing.
529 * @param name Name of the entry. eg: "/base/file_i_want".
530 * @param data Pointer to the data to be stored.
531 * @param size Length in bytes in the data to be stored.
532 * @param compress Compression flags (1 == compress, 0 = don't compress).
533 * @param cipher_key The key to use as cipher.
534 * @return bytes written on successful write, 0 on failure.
536 * This function will write the specified chunk of data to the eet file
537 * and return greater than 0 on success. 0 will be returned on failure.
539 * The eet file handle must be a valid file handle for an eet file opened
540 * for writing. If it is not, 0 will be returned and no action will be
543 * Name, and data must not be NULL, and size must be > 0. If these
544 * conditions are not met, 0 will be returned.
546 * The data will be copied (and optionally compressed) in ram, pending
547 * a flush to disk (it will stay in ram till the eet file handle is
553 * @ingroup Eet_File_Cipher_Group
555 EAPI int eet_write_cipher(Eet_File *ef, const char *name, const void *data, int size, int compress, const char *cipher_key);
559 * @defgroup Eet_File_Image_Group Image Store and Load
561 * Eet efficiently stores and loads images, including alpha
562 * channels and lossy compressions.
566 * Read just the header data for an image and dont decode the pixels.
567 * @param ef A valid eet file handle opened for reading.
568 * @param name Name of the entry. eg: "/base/file_i_want".
569 * @param w A pointer to the unsigned int to hold the width in pixels.
570 * @param h A pointer to the unsigned int to hold the height in pixels.
571 * @param alpha A pointer to the int to hold the alpha flag.
572 * @param compress A pointer to the int to hold the compression amount.
573 * @param quality A pointer to the int to hold the quality amount.
574 * @param lossy A pointer to the int to hold the lossiness flag.
575 * @return 1 on successfull decode, 0 otherwise
577 * This function reads an image from an eet file stored under the named
578 * key in the eet file and return a pointer to the decompressed pixel data.
580 * The other parameters of the image (width, height etc.) are placed into
581 * the values pointed to (they must be supplied). The pixel data is a linear
582 * array of pixels starting from the top-left of the image scanning row by
583 * row from left to right. Each pile is a 32bit value, with the high byte
584 * being the alpha channel, the next being red, then green, and the low byte
585 * being blue. The width and height are measured in pixels and will be
586 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
587 * that the alpha channel is not used. 1 denotes that it is significant.
588 * Compress is filled with the compression value/amount the image was
589 * stored with. The quality value is filled with the quality encoding of
590 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
591 * the image was encoded lossily or not.
593 * On success the function returns 1 indicating the header was read and
594 * decoded properly, or 0 on failure.
596 * @see eet_data_image_header_read_cipher()
599 * @ingroup Eet_File_Image_Group
601 EAPI int eet_data_image_header_read(Eet_File *ef, const char *name, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
604 * Read image data from the named key in the eet file.
605 * @param ef A valid eet file handle opened for reading.
606 * @param name Name of the entry. eg: "/base/file_i_want".
607 * @param w A pointer to the unsigned int to hold the width in pixels.
608 * @param h A pointer to the unsigned int to hold the height in pixels.
609 * @param alpha A pointer to the int to hold the alpha flag.
610 * @param compress A pointer to the int to hold the compression amount.
611 * @param quality A pointer to the int to hold the quality amount.
612 * @param lossy A pointer to the int to hold the lossiness flag.
613 * @return The image pixel data decoded
615 * This function reads an image from an eet file stored under the named
616 * key in the eet file and return a pointer to the decompressed pixel data.
618 * The other parameters of the image (width, height etc.) are placed into
619 * the values pointed to (they must be supplied). The pixel data is a linear
620 * array of pixels starting from the top-left of the image scanning row by
621 * row from left to right. Each pile is a 32bit value, with the high byte
622 * being the alpha channel, the next being red, then green, and the low byte
623 * being blue. The width and height are measured in pixels and will be
624 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
625 * that the alpha channel is not used. 1 denotes that it is significant.
626 * Compress is filled with the compression value/amount the image was
627 * stored with. The quality value is filled with the quality encoding of
628 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
629 * the image was encoded lossily or not.
631 * On success the function returns a pointer to the image data decoded. The
632 * calling application is responsible for calling free() on the image data
633 * when it is done with it. On failure NULL is returned and the parameter
634 * values may not contain any sensible data.
636 * @see eet_data_image_read_cipher()
639 * @ingroup Eet_File_Image_Group
641 EAPI void *eet_data_image_read(Eet_File *ef, const char *name, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
644 * Read image data from the named key in the eet file.
645 * @param ef A valid eet file handle opened for reading.
646 * @param name Name of the entry. eg: "/base/file_i_want".
647 * @param src_x The starting x coordinate from where to dump the stream.
648 * @param src_y The starting y coordinate from where to dump the stream.
649 * @param d A pointer to the pixel surface.
650 * @param w The expected width in pixels of the pixel surface to decode.
651 * @param h The expected height in pixels of the pixel surface to decode.
652 * @param row_stride The length of a pixels line in the destination surface.
653 * @param alpha A pointer to the int to hold the alpha flag.
654 * @param compress A pointer to the int to hold the compression amount.
655 * @param quality A pointer to the int to hold the quality amount.
656 * @param lossy A pointer to the int to hold the lossiness flag.
657 * @return 1 on success, 0 otherwise.
659 * This function reads an image from an eet file stored under the named
660 * key in the eet file and return a pointer to the decompressed pixel data.
662 * The other parameters of the image (width, height etc.) are placed into
663 * the values pointed to (they must be supplied). The pixel data is a linear
664 * array of pixels starting from the top-left of the image scanning row by
665 * row from left to right. Each pile is a 32bit value, with the high byte
666 * being the alpha channel, the next being red, then green, and the low byte
667 * being blue. The width and height are measured in pixels and will be
668 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
669 * that the alpha channel is not used. 1 denotes that it is significant.
670 * Compress is filled with the compression value/amount the image was
671 * stored with. The quality value is filled with the quality encoding of
672 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
673 * the image was encoded lossily or not.
675 * On success the function returns 1, and 0 on failure. On failure the
676 * parameter values may not contain any sensible data.
678 * @see eet_data_image_read_to_surface_cipher()
681 * @ingroup Eet_File_Image_Group
683 EAPI int eet_data_image_read_to_surface(Eet_File *ef, const char *name, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
686 * Write image data to the named key in an eet file.
687 * @param ef A valid eet file handle opened for writing.
688 * @param name Name of the entry. eg: "/base/file_i_want".
689 * @param data A pointer to the image pixel data.
690 * @param w The width of the image in pixels.
691 * @param h The height of the image in pixels.
692 * @param alpha The alpha channel flag.
693 * @param compress The compression amount.
694 * @param quality The quality encoding amount.
695 * @param lossy The lossiness flag.
696 * @return Success if the data was encoded and written or not.
698 * This function takes image pixel data and encodes it in an eet file
699 * stored under the supplied name key, and returns how many bytes were
700 * actually written to encode the image data.
702 * The data expected is the same format as returned by eet_data_image_read.
703 * If this is not the case weird things may happen. Width and height must
704 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
705 * the alpha values are not useful and 1 meaning they are). Compress can
706 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
707 * This is only used if the image is not lossily encoded. Quality is used on
708 * lossy compression and should be a value from 0 to 100. The lossy flag
709 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
710 * image quality loss (but then have a much smaller encoding).
712 * On success this function returns the number of bytes that were required
713 * to encode the image data, or on failure it returns 0.
715 * @see eet_data_image_write_cipher()
718 * @ingroup Eet_File_Image_Group
720 EAPI int eet_data_image_write(Eet_File *ef, const char *name, const void *data, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy);
723 * Decode Image data header only to get information.
724 * @param data The encoded pixel data.
725 * @param size The size, in bytes, of the encoded pixel data.
726 * @param w A pointer to the unsigned int to hold the width in pixels.
727 * @param h A pointer to the unsigned int to hold the height in pixels.
728 * @param alpha A pointer to the int to hold the alpha flag.
729 * @param compress A pointer to the int to hold the compression amount.
730 * @param quality A pointer to the int to hold the quality amount.
731 * @param lossy A pointer to the int to hold the lossiness flag.
732 * @return 1 on success, 0 on failure.
734 * This function takes encoded pixel data and decodes it into raw RGBA
737 * The other parameters of the image (width, height etc.) are placed into
738 * the values pointed to (they must be supplied). The pixel data is a linear
739 * array of pixels starting from the top-left of the image scanning row by
740 * row from left to right. Each pixel is a 32bit value, with the high byte
741 * being the alpha channel, the next being red, then green, and the low byte
742 * being blue. The width and height are measured in pixels and will be
743 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
744 * that the alpha channel is not used. 1 denotes that it is significant.
745 * Compress is filled with the compression value/amount the image was
746 * stored with. The quality value is filled with the quality encoding of
747 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
748 * the image was encoded lossily or not.
750 * On success the function returns 1 indicating the header was read and
751 * decoded properly, or 0 on failure.
753 * @see eet_data_image_header_decode_cipher()
756 * @ingroup Eet_File_Image_Group
758 EAPI int eet_data_image_header_decode(const void *data, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
761 * Decode Image data into pixel data.
762 * @param data The encoded pixel data.
763 * @param size The size, in bytes, of the encoded pixel data.
764 * @param w A pointer to the unsigned int to hold the width in pixels.
765 * @param h A pointer to the unsigned int to hold the height in pixels.
766 * @param alpha A pointer to the int to hold the alpha flag.
767 * @param compress A pointer to the int to hold the compression amount.
768 * @param quality A pointer to the int to hold the quality amount.
769 * @param lossy A pointer to the int to hold the lossiness flag.
770 * @return The image pixel data decoded
772 * This function takes encoded pixel data and decodes it into raw RGBA
775 * The other parameters of the image (width, height etc.) are placed into
776 * the values pointed to (they must be supplied). The pixel data is a linear
777 * array of pixels starting from the top-left of the image scanning row by
778 * row from left to right. Each pixel is a 32bit value, with the high byte
779 * being the alpha channel, the next being red, then green, and the low byte
780 * being blue. The width and height are measured in pixels and will be
781 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
782 * that the alpha channel is not used. 1 denotes that it is significant.
783 * Compress is filled with the compression value/amount the image was
784 * stored with. The quality value is filled with the quality encoding of
785 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
786 * the image was encoded lossily or not.
788 * On success the function returns a pointer to the image data decoded. The
789 * calling application is responsible for calling free() on the image data
790 * when it is done with it. On failure NULL is returned and the parameter
791 * values may not contain any sensible data.
793 * @see eet_data_image_decode_cipher()
796 * @ingroup Eet_File_Image_Group
798 EAPI void *eet_data_image_decode(const void *data, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
801 * Decode Image data into pixel data.
802 * @param data The encoded pixel data.
803 * @param size The size, in bytes, of the encoded pixel data.
804 * @param src_x The starting x coordinate from where to dump the stream.
805 * @param src_y The starting y coordinate from where to dump the stream.
806 * @param d A pointer to the pixel surface.
807 * @param w The expected width in pixels of the pixel surface to decode.
808 * @param h The expected height in pixels of the pixel surface to decode.
809 * @param row_stride The length of a pixels line in the destination surface.
810 * @param alpha A pointer to the int to hold the alpha flag.
811 * @param compress A pointer to the int to hold the compression amount.
812 * @param quality A pointer to the int to hold the quality amount.
813 * @param lossy A pointer to the int to hold the lossiness flag.
814 * @return 1 on success, 0 otherwise.
816 * This function takes encoded pixel data and decodes it into raw RGBA
819 * The other parameters of the image (alpha, compress etc.) are placed into
820 * the values pointed to (they must be supplied). The pixel data is a linear
821 * array of pixels starting from the top-left of the image scanning row by
822 * row from left to right. Each pixel is a 32bit value, with the high byte
823 * being the alpha channel, the next being red, then green, and the low byte
824 * being blue. The width and height are measured in pixels and will be
825 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
826 * that the alpha channel is not used. 1 denotes that it is significant.
827 * Compress is filled with the compression value/amount the image was
828 * stored with. The quality value is filled with the quality encoding of
829 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
830 * the image was encoded lossily or not.
832 * On success the function returns 1, and 0 on failure. On failure the
833 * parameter values may not contain any sensible data.
835 * @see eet_data_image_decode_to_surface_cipher()
838 * @ingroup Eet_File_Image_Group
840 EAPI int eet_data_image_decode_to_surface(const void *data, int size, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
843 * Encode image data for storage or transmission.
844 * @param data A pointer to the image pixel data.
845 * @param size_ret A pointer to an int to hold the size of the returned data.
846 * @param w The width of the image in pixels.
847 * @param h The height of the image in pixels.
848 * @param alpha The alpha channel flag.
849 * @param compress The compression amount.
850 * @param quality The quality encoding amount.
851 * @param lossy The lossiness flag.
852 * @return The encoded image data.
854 * This function stakes image pixel data and encodes it with compression and
855 * possible loss of quality (as a trade off for size) for storage or
856 * transmission to another system.
858 * The data expected is the same format as returned by eet_data_image_read.
859 * If this is not the case weird things may happen. Width and height must
860 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
861 * the alpha values are not useful and 1 meaning they are). Compress can
862 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
863 * This is only used if the image is not lossily encoded. Quality is used on
864 * lossy compression and should be a value from 0 to 100. The lossy flag
865 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
866 * image quality loss (but then have a much smaller encoding).
868 * On success this function returns a pointer to the encoded data that you
869 * can free with free() when no longer needed.
871 * @see eet_data_image_encode_cipher()
874 * @ingroup Eet_File_Image_Group
876 EAPI void *eet_data_image_encode(const void *data, int *size_ret, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy);
879 * @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Cipher
881 * Most of the @ref Eet_File_Image_Group have alternative versions
882 * that accounts for ciphers to protect their content.
884 * @see @ref Eet_Cipher_Group
886 * @ingroup Eet_File_Image_Group
890 * Read just the header data for an image and dont decode the pixels using a cipher.
891 * @param ef A valid eet file handle opened for reading.
892 * @param name Name of the entry. eg: "/base/file_i_want".
893 * @param cipher_key The key to use as cipher.
894 * @param w A pointer to the unsigned int to hold the width in pixels.
895 * @param h A pointer to the unsigned int to hold the height in pixels.
896 * @param alpha A pointer to the int to hold the alpha flag.
897 * @param compress A pointer to the int to hold the compression amount.
898 * @param quality A pointer to the int to hold the quality amount.
899 * @param lossy A pointer to the int to hold the lossiness flag.
900 * @return 1 on successfull decode, 0 otherwise
902 * This function reads an image from an eet file stored under the named
903 * key in the eet file and return a pointer to the decompressed pixel data.
905 * The other parameters of the image (width, height etc.) are placed into
906 * the values pointed to (they must be supplied). The pixel data is a linear
907 * array of pixels starting from the top-left of the image scanning row by
908 * row from left to right. Each pile is a 32bit value, with the high byte
909 * being the alpha channel, the next being red, then green, and the low byte
910 * being blue. The width and height are measured in pixels and will be
911 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
912 * that the alpha channel is not used. 1 denotes that it is significant.
913 * Compress is filled with the compression value/amount the image was
914 * stored with. The quality value is filled with the quality encoding of
915 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
916 * the image was encoded lossily or not.
918 * On success the function returns 1 indicating the header was read and
919 * decoded properly, or 0 on failure.
921 * @see eet_data_image_header_read()
924 * @ingroup Eet_File_Image_Cipher_Group
926 EAPI int eet_data_image_header_read_cipher(Eet_File *ef, const char *name, const char *cipher_key, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
929 * Read image data from the named key in the eet file using a cipher.
930 * @param ef A valid eet file handle opened for reading.
931 * @param name Name of the entry. eg: "/base/file_i_want".
932 * @param cipher_key The key to use as cipher.
933 * @param w A pointer to the unsigned int to hold the width in pixels.
934 * @param h A pointer to the unsigned int to hold the height in pixels.
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 The image pixel data decoded
941 * This function reads an image from an eet file stored under the named
942 * key in the eet file and return a pointer to the decompressed pixel data.
944 * The other parameters of the image (width, height 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 pile 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 a pointer to the image data decoded. The
958 * calling application is responsible for calling free() on the image data
959 * when it is done with it. On failure NULL is returned and the parameter
960 * values may not contain any sensible data.
962 * @see eet_data_image_read()
965 * @ingroup Eet_File_Image_Cipher_Group
967 EAPI void *eet_data_image_read_cipher(Eet_File *ef, const char *name, const char *cipher_key, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
970 * Read image data from the named key in the eet file using a cipher.
971 * @param ef A valid eet file handle opened for reading.
972 * @param name Name of the entry. eg: "/base/file_i_want".
973 * @param cipher_key The key to use as cipher.
974 * @param src_x The starting x coordinate from where to dump the stream.
975 * @param src_y The starting y coordinate from where to dump the stream.
976 * @param d A pointer to the pixel surface.
977 * @param w The expected width in pixels of the pixel surface to decode.
978 * @param h The expected height in pixels of the pixel surface to decode.
979 * @param row_stride The length of a pixels line in the destination surface.
980 * @param alpha A pointer to the int to hold the alpha flag.
981 * @param compress A pointer to the int to hold the compression amount.
982 * @param quality A pointer to the int to hold the quality amount.
983 * @param lossy A pointer to the int to hold the lossiness flag.
984 * @return 1 on success, 0 otherwise.
986 * This function reads an image from an eet file stored under the named
987 * key in the eet file and return a pointer to the decompressed pixel data.
989 * The other parameters of the image (width, height etc.) are placed into
990 * the values pointed to (they must be supplied). The pixel data is a linear
991 * array of pixels starting from the top-left of the image scanning row by
992 * row from left to right. Each pile is a 32bit value, with the high byte
993 * being the alpha channel, the next being red, then green, and the low byte
994 * being blue. The width and height are measured in pixels and will be
995 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
996 * that the alpha channel is not used. 1 denotes that it is significant.
997 * Compress is filled with the compression value/amount the image was
998 * stored with. The quality value is filled with the quality encoding of
999 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1000 * the image was encoded lossily or not.
1002 * On success the function returns 1, and 0 on failure. On failure the
1003 * parameter values may not contain any sensible data.
1005 * @see eet_data_image_read_to_surface()
1008 * @ingroup Eet_File_Image_Cipher_Group
1010 EAPI int eet_data_image_read_to_surface_cipher(Eet_File *ef, const char *name, const char *cipher_key, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
1013 * Write image data to the named key in an eet file using a cipher.
1014 * @param ef A valid eet file handle opened for writing.
1015 * @param name Name of the entry. eg: "/base/file_i_want".
1016 * @param cipher_key The key to use as cipher.
1017 * @param data A pointer to the image pixel data.
1018 * @param w The width of the image in pixels.
1019 * @param h The height of the image in pixels.
1020 * @param alpha The alpha channel flag.
1021 * @param compress The compression amount.
1022 * @param quality The quality encoding amount.
1023 * @param lossy The lossiness flag.
1024 * @return Success if the data was encoded and written or not.
1026 * This function takes image pixel data and encodes it in an eet file
1027 * stored under the supplied name key, and returns how many bytes were
1028 * actually written to encode the image data.
1030 * The data expected is the same format as returned by eet_data_image_read.
1031 * If this is not the case weird things may happen. Width and height must
1032 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1033 * the alpha values are not useful and 1 meaning they are). Compress can
1034 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1035 * This is only used if the image is not lossily encoded. Quality is used on
1036 * lossy compression and should be a value from 0 to 100. The lossy flag
1037 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1038 * image quality loss (but then have a much smaller encoding).
1040 * On success this function returns the number of bytes that were required
1041 * to encode the image data, or on failure it returns 0.
1043 * @see eet_data_image_write()
1046 * @ingroup Eet_File_Image_Cipher_Group
1048 EAPI int eet_data_image_write_cipher(Eet_File *ef, const char *name, const char *cipher_key, const void *data, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy);
1052 * Decode Image data header only to get information using a cipher.
1053 * @param data The encoded pixel data.
1054 * @param cipher_key The key to use as cipher.
1055 * @param size The size, in bytes, of the encoded pixel data.
1056 * @param w A pointer to the unsigned int to hold the width in pixels.
1057 * @param h A pointer to the unsigned int to hold the height in pixels.
1058 * @param alpha A pointer to the int to hold the alpha flag.
1059 * @param compress A pointer to the int to hold the compression amount.
1060 * @param quality A pointer to the int to hold the quality amount.
1061 * @param lossy A pointer to the int to hold the lossiness flag.
1062 * @return 1 on success, 0 on failure.
1064 * This function takes encoded pixel data and decodes it into raw RGBA
1065 * pixels on success.
1067 * The other parameters of the image (width, height etc.) are placed into
1068 * the values pointed to (they must be supplied). The pixel data is a linear
1069 * array of pixels starting from the top-left of the image scanning row by
1070 * row from left to right. Each pixel is a 32bit value, with the high byte
1071 * being the alpha channel, the next being red, then green, and the low byte
1072 * being blue. The width and height are measured in pixels and will be
1073 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1074 * that the alpha channel is not used. 1 denotes that it is significant.
1075 * Compress is filled with the compression value/amount the image was
1076 * stored with. The quality value is filled with the quality encoding of
1077 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1078 * the image was encoded lossily or not.
1080 * On success the function returns 1 indicating the header was read and
1081 * decoded properly, or 0 on failure.
1083 * @see eet_data_image_header_decode()
1086 * @ingroup Eet_File_Image_Cipher_Group
1088 EAPI int eet_data_image_header_decode_cipher(const void *data, const char *cipher_key, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
1091 * Decode Image data into pixel data using a cipher.
1092 * @param data The encoded pixel data.
1093 * @param cipher_key The key to use as cipher.
1094 * @param size The size, in bytes, of the encoded pixel data.
1095 * @param w A pointer to the unsigned int to hold the width in pixels.
1096 * @param h A pointer to the unsigned int to hold the height in pixels.
1097 * @param alpha A pointer to the int to hold the alpha flag.
1098 * @param compress A pointer to the int to hold the compression amount.
1099 * @param quality A pointer to the int to hold the quality amount.
1100 * @param lossy A pointer to the int to hold the lossiness flag.
1101 * @return The image pixel data decoded
1103 * This function takes encoded pixel data and decodes it into raw RGBA
1104 * pixels on success.
1106 * The other parameters of the image (width, height etc.) are placed into
1107 * the values pointed to (they must be supplied). The pixel data is a linear
1108 * array of pixels starting from the top-left of the image scanning row by
1109 * row from left to right. Each pixel is a 32bit value, with the high byte
1110 * being the alpha channel, the next being red, then green, and the low byte
1111 * being blue. The width and height are measured in pixels and will be
1112 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1113 * that the alpha channel is not used. 1 denotes that it is significant.
1114 * Compress is filled with the compression value/amount the image was
1115 * stored with. The quality value is filled with the quality encoding of
1116 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1117 * the image was encoded lossily or not.
1119 * On success the function returns a pointer to the image data decoded. The
1120 * calling application is responsible for calling free() on the image data
1121 * when it is done with it. On failure NULL is returned and the parameter
1122 * values may not contain any sensible data.
1124 * @see eet_data_image_decode()
1127 * @ingroup Eet_File_Image_Cipher_Group
1129 EAPI void *eet_data_image_decode_cipher(const void *data, const char *cipher_key, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
1132 * Decode Image data into pixel data using a cipher.
1133 * @param data The encoded pixel data.
1134 * @param cipher_key The key to use as cipher.
1135 * @param size The size, in bytes, of the encoded pixel data.
1136 * @param src_x The starting x coordinate from where to dump the stream.
1137 * @param src_y The starting y coordinate from where to dump the stream.
1138 * @param d A pointer to the pixel surface.
1139 * @param w The expected width in pixels of the pixel surface to decode.
1140 * @param h The expected height in pixels of the pixel surface to decode.
1141 * @param row_stride The length of a pixels line in the destination surface.
1142 * @param alpha A pointer to the int to hold the alpha flag.
1143 * @param compress A pointer to the int to hold the compression amount.
1144 * @param quality A pointer to the int to hold the quality amount.
1145 * @param lossy A pointer to the int to hold the lossiness flag.
1146 * @return 1 on success, 0 otherwise.
1148 * This function takes encoded pixel data and decodes it into raw RGBA
1149 * pixels on success.
1151 * The other parameters of the image (alpha, compress etc.) are placed into
1152 * the values pointed to (they must be supplied). The pixel data is a linear
1153 * array of pixels starting from the top-left of the image scanning row by
1154 * row from left to right. Each pixel is a 32bit value, with the high byte
1155 * being the alpha channel, the next being red, then green, and the low byte
1156 * being blue. The width and height are measured in pixels and will be
1157 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1158 * that the alpha channel is not used. 1 denotes that it is significant.
1159 * Compress is filled with the compression value/amount the image was
1160 * stored with. The quality value is filled with the quality encoding of
1161 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1162 * the image was encoded lossily or not.
1164 * On success the function returns 1, and 0 on failure. On failure the
1165 * parameter values may not contain any sensible data.
1167 * @see eet_data_image_decode_to_surface()
1170 * @ingroup Eet_File_Image_Cipher_Group
1172 EAPI int eet_data_image_decode_to_surface_cipher(const void *data, const char *cipher_key, int size, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
1175 * Encode image data for storage or transmission using a cipher.
1176 * @param data A pointer to the image pixel data.
1177 * @param cipher_key The key to use as cipher.
1178 * @param size_ret A pointer to an int to hold the size of the returned data.
1179 * @param w The width of the image in pixels.
1180 * @param h The height of the image in pixels.
1181 * @param alpha The alpha channel flag.
1182 * @param compress The compression amount.
1183 * @param quality The quality encoding amount.
1184 * @param lossy The lossiness flag.
1185 * @return The encoded image data.
1187 * This function stakes image pixel data and encodes it with compression and
1188 * possible loss of quality (as a trade off for size) for storage or
1189 * transmission to another system.
1191 * The data expected is the same format as returned by eet_data_image_read.
1192 * If this is not the case weird things may happen. Width and height must
1193 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1194 * the alpha values are not useful and 1 meaning they are). Compress can
1195 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1196 * This is only used if the image is not lossily encoded. Quality is used on
1197 * lossy compression and should be a value from 0 to 100. The lossy flag
1198 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1199 * image quality loss (but then have a much smaller encoding).
1201 * On success this function returns a pointer to the encoded data that you
1202 * can free with free() when no longer needed.
1204 * @see eet_data_image_encode()
1207 * @ingroup Eet_File_Image_Cipher_Group
1209 EAPI void *eet_data_image_encode_cipher(const void *data, const char *cipher_key, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy, int *size_ret);
1213 * @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms
1215 * Eet allows one to protect entries of an #Eet_File
1216 * individually. This may be used to ensure data was not tampered or
1217 * that third party does not read your data.
1219 * @see @ref Eet_File_Cipher_Group
1220 * @see @ref Eet_File_Image_Cipher_Group
1227 * Opaque handle that defines an identity (also known as key)
1228 * in Eet's cipher system.
1230 typedef struct _Eet_Key Eet_Key;
1238 * Callback used to request if needed the password of a private key.
1240 * @param buffer the buffer where to store the password.
1241 * @param size the maximum password size (size of buffer, including '@\0').
1242 * @param rwflag if the buffer is also readable or just writable.
1243 * @param data currently unused, may contain some context in future.
1244 * @return 1 on success and password was set to @p buffer, 0 on failure.
1247 * @ingroup Eet_Cipher_Group
1249 typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data);
1252 * Create an Eet_Key needed for signing an eet file.
1254 * The certificate should provide the public that match the private key.
1255 * No verification is done to ensure that.
1257 * @param certificate_file The file where to find the certificate.
1258 * @param private_key_file The file that contains the private key.
1259 * @param cb Function to callback if password is required to unlock
1261 * @return A key handle to use, or @c NULL on failure.
1263 * @see eet_identity_close()
1266 * @ingroup Eet_Cipher_Group
1268 EAPI Eet_Key* eet_identity_open(const char *certificate_file, const char *private_key_file, Eet_Key_Password_Callback cb);
1271 * Close and release all ressource used by an Eet_Key. An
1272 * reference counter prevent it from being freed until all file
1273 * using it are also closed.
1275 * @param key the key handle to close and free resources.
1278 * @ingroup Eet_Cipher_Group
1280 EAPI void eet_identity_close(Eet_Key *key);
1283 * Set a key to sign a file
1285 * @param ef the file to set the identity.
1286 * @param key the key handle to set as identity.
1287 * @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or
1288 * #EET_ERROR_NONE on success.
1291 * @ingroup Eet_Cipher_Group
1293 EAPI Eet_Error eet_identity_set(Eet_File *ef, Eet_Key *key);
1296 * Display both private and public key of an Eet_Key.
1298 * @param key the handle to print.
1299 * @param out where to print.
1302 * @ingroup Eet_Cipher_Group
1304 EAPI void eet_identity_print(Eet_Key *key, FILE *out);
1307 * Get the x509 der certificate associated with an Eet_File. Will return NULL
1308 * if the file is not signed.
1310 * @param ef The file handle to query.
1311 * @param der_length The length of returned data, may be @c NULL.
1312 * @return the x509 certificate or @c NULL on error.
1315 * @ingroup Eet_Cipher_Group
1317 EAPI const void *eet_identity_x509(Eet_File *ef, int *der_length);
1320 * Get the raw signature associated with an Eet_File. Will return NULL
1321 * if the file is not signed.
1323 * @param ef The file handle to query.
1324 * @param signature_length The length of returned data, may be @c NULL.
1325 * @return the raw signature or @c NULL on error.
1327 * @ingroup Eet_Cipher_Group
1329 EAPI const void *eet_identity_signature(Eet_File *ef, int *signature_length);
1332 * Get the SHA1 associated with a file. Could be the one used to
1333 * sign the data or if the data where not signed, it will be the
1336 * @param ef The file handle to query.
1337 * @param sha1_length The length of returned data, may be @c NULL.
1338 * @return the associated SHA1 or @c NULL on error.
1341 * @ingroup Eet_Cipher_Group
1343 EAPI const void *eet_identity_sha1(Eet_File *ef, int *sha1_length);
1346 * Display the x509 der certificate to out.
1348 * @param certificate the x509 certificate to print
1349 * @param der_length The length the certificate.
1350 * @param out where to print.
1353 * @ingroup Eet_Cipher_Group
1355 EAPI void eet_identity_certificate_print(const unsigned char *certificate, int der_length, FILE *out);
1359 * @defgroup Eet_Data_Group Eet Data Serialization
1361 * Convenience functions to serialize and parse complex data
1362 * structures to binary blobs.
1364 * While Eet core just handles binary blobs, it is often required
1365 * to save some structured data of different types, such as
1366 * strings, integers, lists, hashes and so on.
1368 * Eet can serialize and then parse data types given some
1369 * construction instructions. These are defined in two levels:
1371 * - #Eet_Data_Descriptor_Class to tell generic memory handling,
1372 * such as the size of the type, how to allocate memory, strings,
1373 * lists, hashes and so on.
1375 * - #Eet_Data_Descriptor to tell inside such type, the members and
1376 * their offsets inside the memory blob, their types and
1377 * names. These members can be simple types or other
1378 * #Eet_Data_Descriptor, allowing hierarchical types to be
1381 * Given that C provides no introspection, this process can be
1382 * quite cumbersome, so we provide lots of macros and convenience
1383 * functions to aid creating the types.
1391 * typedef struct _blah2
1396 * typedef struct _blah3
1401 * typedef struct _blah
1408 * double floating_lots;
1415 * main(int argc, char **argv)
1420 * Eet_Data_Descriptor *edd, *edd2, *edd3;
1421 * Eet_Data_Descriptor_Class eddc, eddc2, eddc3;
1429 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc3, Blah3);
1430 * edd3 = eet_data_descriptor_stream_new(&eddc3);
1431 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd3, Blah3, "string3", string, EET_T_STRING);
1433 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc2, Blah2);
1434 * edd2 = eet_data_descriptor_stream_new(&eddc2);
1435 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd2, Blah2, "string2", string, EET_T_STRING);
1437 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc, Blah);
1438 * edd = eet_data_descriptor_stream_new(&eddc);
1439 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "character", character, EET_T_CHAR);
1440 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "sixteen", sixteen, EET_T_SHORT);
1441 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "integer", integer, EET_T_INT);
1442 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "lots", lots, EET_T_LONG_LONG);
1443 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating", floating, EET_T_FLOAT);
1444 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating_lots", floating_lots, EET_T_DOUBLE);
1445 * EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "string", string, EET_T_STRING);
1446 * EET_DATA_DESCRIPTOR_ADD_SUB(edd, Blah, "blah2", blah2, edd2);
1447 * EET_DATA_DESCRIPTOR_ADD_LIST(edd, Blah, "blah3", blah3, edd3);
1449 * blah3.string = "PANTS";
1451 * blah2.string = "subtype string here!";
1453 * blah.character = '7';
1454 * blah.sixteen = 0x7777;
1455 * blah.integer = 0xc0def00d;
1456 * blah.lots = 0xdeadbeef31337777;
1457 * blah.floating = 3.141592654;
1458 * blah.floating_lots = 0.777777777777777;
1459 * blah.string = "bite me like a turnip";
1460 * blah.blah2 = &blah2;
1461 * blah.blah3 = eina_list_append(NULL, &blah3);
1462 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1463 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1464 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1465 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1466 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1467 * blah.blah3 = eina_list_append(blah.blah3, &blah3);
1469 * data = eet_data_descriptor_encode(edd, &blah, &size);
1470 * printf("-----DECODING\n");
1471 * blah_in = eet_data_descriptor_decode(edd, data, size);
1473 * printf("-----DECODED!\n");
1474 * printf("%c\n", blah_in->character);
1475 * printf("%x\n", (int)blah_in->sixteen);
1476 * printf("%x\n", blah_in->integer);
1477 * printf("%lx\n", blah_in->lots);
1478 * printf("%f\n", (double)blah_in->floating);
1479 * printf("%f\n", (double)blah_in->floating_lots);
1480 * printf("%s\n", blah_in->string);
1481 * printf("%p\n", blah_in->blah2);
1482 * printf(" %s\n", blah_in->blah2->string);
1487 * EINA_LIST_FOREACH(blah_in->blah3, l, blah3_in)
1489 * printf("%p\n", blah3_in);
1490 * printf(" %s\n", blah3_in->string);
1493 * eet_data_descriptor_free(edd);
1494 * eet_data_descriptor_free(edd2);
1495 * eet_data_descriptor_free(edd3);
1505 #define EET_T_UNKNOW 0 /**< Unknown data encoding type */
1506 #define EET_T_CHAR 1 /**< Data type: char */
1507 #define EET_T_SHORT 2 /**< Data type: short */
1508 #define EET_T_INT 3 /**< Data type: int */
1509 #define EET_T_LONG_LONG 4 /**< Data type: long long */
1510 #define EET_T_FLOAT 5 /**< Data type: float */
1511 #define EET_T_DOUBLE 6 /**< Data type: double */
1512 #define EET_T_UCHAR 7 /**< Data type: unsigned char */
1513 #define EET_T_USHORT 8 /**< Data type: unsigned short */
1514 #define EET_T_UINT 9 /**< Data type: unsigned int */
1515 #define EET_T_ULONG_LONG 10 /**< Data type: unsigned long long */
1516 #define EET_T_STRING 11 /**< Data type: char * */
1517 #define EET_T_INLINED_STRING 12 /**< Data type: char * (but compressed inside the resulting eet) */
1518 #define EET_T_NULL 13 /**< Data type: (void *) (only use it if you know why) */
1519 #define EET_T_F32P32 14 /**< Data type: fixed point 32.32 */
1520 #define EET_T_F16P16 15 /**< Data type: fixed point 16.16 */
1521 #define EET_T_F8P24 16 /**< Data type: fixed point 8.24 */
1522 #define EET_T_LAST 18 /**< Last data type */
1524 #define EET_G_UNKNOWN 100 /**< Unknown group data encoding type */
1525 #define EET_G_ARRAY 101 /**< Fixed size array group type */
1526 #define EET_G_VAR_ARRAY 102 /**< Variable size array group type */
1527 #define EET_G_LIST 103 /**< Linked list group type */
1528 #define EET_G_HASH 104 /**< Hash table group type */
1529 #define EET_G_UNION 105 /**< Union group type */
1530 #define EET_G_VARIANT 106 /**< Selectable subtype group */
1531 #define EET_G_LAST 107 /**< Last group type */
1533 #define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */
1536 * @typedef Eet_Data_Descriptor
1538 * Opaque handle that have information on a type members.
1540 * The members are added by means of
1541 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(),
1542 * EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH()
1543 * or eet_data_descriptor_element_add().
1545 * @see eet_data_descriptor_stream_new()
1546 * @see eet_data_descriptor_file_new()
1547 * @see eet_data_descriptor_free()
1549 typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor;
1552 * @def EET_DATA_DESCRIPTOR_CLASS_VERSION
1553 * The version of #Eet_Data_Descriptor_Class at the time of the
1554 * distribution of the sources. One should define this to its
1555 * version member so it is compatible with abi changes, or at least
1556 * will not crash with them.
1558 #define EET_DATA_DESCRIPTOR_CLASS_VERSION 3
1561 * @typedef Eet_Data_Descriptor_Class
1563 * Instructs Eet about memory management for different needs under
1564 * serialization and parse process.
1566 typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
1569 * @struct _Eet_Data_Descriptor_Class
1571 * Instructs Eet about memory management for different needs under
1572 * serialization and parse process.
1574 * If using Eina data types, it is advised to use the helpers
1575 * EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
1576 * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET().
1578 struct _Eet_Data_Descriptor_Class
1580 int version; /**< ABI version as #EET_DATA_DESCRIPTOR_CLASS_VERSION */
1581 const char *name; /**< Name of data type to be serialized */
1582 int size; /**< Size in bytes of data type to be serialized */
1584 void *(*mem_alloc) (size_t size); /**< how to allocate memory (usually malloc()) */
1585 void (*mem_free) (void *mem); /**< how to free memory (usually free()) */
1586 char *(*str_alloc) (const char *str); /**< how to allocate a string */
1587 void (*str_free) (const char *str); /**< how to free a string */
1588 void *(*list_next) (void *l); /**< how to iterate to the next element of a list. Receives and should return the list node. */
1589 void *(*list_append) (void *l, void *d); /**< how to append data @p d to list which head node is @p l */
1590 void *(*list_data) (void *l); /**< retrieves the data from node @p l */
1591 void *(*list_free) (void *l); /**< free all the nodes from the list which head node is @p l */
1592 void (*hash_foreach) (void *h, int (*func) (void *h, const char *k, void *dt, void *fdt), void *fdt); /**< iterates over all elements in the hash @p h in no specific order */
1593 void *(*hash_add) (void *h, const char *k, void *d); /**< add a new data @p d as key @p k in hash @p h */
1594 void (*hash_free) (void *h); /**< free all entries from the hash @p h */
1595 char *(*str_direct_alloc) (const char *str); /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */
1596 void (*str_direct_free) (const char *str); /**< how to free a string returned by str_direct_alloc */
1598 const char *(*type_get) (const void *data, Eina_Bool *unknow); /**< convert any kind of data type to a name that define an Eet_Data_Element. */
1599 Eina_Bool (*type_set) (const char *type, void *data, Eina_Bool unknow); /**< set the type at a particular adress */
1608 * Create a new empty data structure descriptor.
1609 * @param name The string name of this data structure (most be a
1610 * global constant and never change).
1611 * @param size The size of the struct (in bytes).
1612 * @param func_list_next The function to get the next list node.
1613 * @param func_list_append The function to append a member to a list.
1614 * @param func_list_data The function to get the data from a list node.
1615 * @param func_list_free The function to free an entire linked list.
1616 * @param func_hash_foreach The function to iterate through all
1617 * hash table entries.
1618 * @param func_hash_add The function to add a member to a hash table.
1619 * @param func_hash_free The function to free an entire hash table.
1620 * @return A new empty data descriptor.
1622 * This function creates a new data descriptore and returns a handle to the
1623 * new data descriptor. On creation it will be empty, containing no contents
1624 * describing anything other than the shell of the data structure.
1626 * You add structure members to the data descriptor using the macros
1627 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
1628 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
1629 * adding to the description.
1631 * Once you have described all the members of a struct you want loaded, or
1632 * saved eet can load and save those members for you, encode them into
1633 * endian-independant serialised data chunks for transmission across a
1634 * a network or more.
1636 * The function pointers to the list and hash table functions are only
1637 * needed if you use those data types, else you can pass NULL instead.
1640 * @ingroup Eet_Data_Group
1642 * @deprecated use eet_data_descriptor_stream_new() or
1643 * eet_data_descriptor_file_new()
1645 EINA_DEPRECATED EAPI Eet_Data_Descriptor *eet_data_descriptor_new(const char *name, int size, void *(*func_list_next) (void *l), void *(*func_list_append) (void *l, void *d), void *(*func_list_data) (void *l), void *(*func_list_free) (void *l), void (*func_hash_foreach) (void *h, int (*func) (void *h, const char *k, void *dt, void *fdt), void *fdt), void *(*func_hash_add) (void *h, const char *k, void *d), void (*func_hash_free) (void *h));
1649 * moving to this api from the old above. this will break things when the
1650 * move happens - but be warned
1652 EINA_DEPRECATED EAPI Eet_Data_Descriptor *eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc);
1653 EINA_DEPRECATED EAPI Eet_Data_Descriptor *eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc);
1656 * This function creates a new data descriptore and returns a handle to the
1657 * new data descriptor. On creation it will be empty, containing no contents
1658 * describing anything other than the shell of the data structure.
1659 * @param eddc The data descriptor to free.
1661 * You add structure members to the data descriptor using the macros
1662 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
1663 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
1664 * adding to the description.
1666 * Once you have described all the members of a struct you want loaded, or
1667 * saved eet can load and save those members for you, encode them into
1668 * endian-independant serialised data chunks for transmission across a
1669 * a network or more.
1671 * This function specially ignore str_direct_alloc and str_direct_free. It
1672 * is usefull when the eet_data you are reading don't have a dictionnary
1673 * like network stream or ipc. It also mean that all string will be allocated
1674 * and duplicated in memory.
1677 * @ingroup Eet_Data_Group
1679 EAPI Eet_Data_Descriptor *eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc);
1682 * This function creates a new data descriptore and returns a handle to the
1683 * new data descriptor. On creation it will be empty, containing no contents
1684 * describing anything other than the shell of the data structure.
1685 * @param eddc The data descriptor to free.
1687 * You add structure members to the data descriptor using the macros
1688 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
1689 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
1690 * adding to the description.
1692 * Once you have described all the members of a struct you want loaded, or
1693 * saved eet can load and save those members for you, encode them into
1694 * endian-independant serialised data chunks for transmission across a
1695 * a network or more.
1697 * This function use str_direct_alloc and str_direct_free. It is
1698 * usefull when the eet_data you are reading come from a file and
1699 * have a dictionnary. This will reduce memory use, improve the
1700 * possibility for the OS to page this string out. But be carrefull
1701 * all EET_T_STRING are pointer to a mmapped area and it will point
1702 * to nowhere if you close the file. So as long as you use this
1703 * strings, you need to have the Eet_File open.
1706 * @ingroup Eet_Data_Group
1708 EAPI Eet_Data_Descriptor *eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc);
1711 * This function is an helper that set all the parameter of an
1712 * Eet_Data_Descriptor_Class correctly when you use Eina data type
1714 * @param eddc The Eet_Data_Descriptor_Class you want to set.
1715 * @param name The name of the structure described by this class.
1716 * @param size The size of the structure described by this class.
1717 * @return EINA_TRUE if the structure was correctly set (The only
1718 * reason that could make it fail is if you did give wrong
1722 * @ingroup Eet_Data_Group
1724 EAPI Eina_Bool eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, const char *name, int size);
1727 * This macro is an helper that set all the parameter of an
1728 * Eet_Data_Descriptor_Class correctly when you use Eina data type
1730 * @param Clas The Eet_Data_Descriptor_Class you want to set.
1731 * @param Type The type of the structure described by this class.
1732 * @return EINA_TRUE if the structure was correctly set (The only
1733 * reason that could make it fail is if you did give wrong
1737 * @ingroup Eet_Data_Group
1739 #define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(Clas, Type) (eet_eina_stream_data_descriptor_class_set(Clas, #Type , sizeof (Type)))
1742 * This function is an helper that set all the parameter of an
1743 * Eet_Data_Descriptor_Class correctly when you use Eina data type
1745 * @param eddc The Eet_Data_Descriptor_Class you want to set.
1746 * @param name The name of the structure described by this class.
1747 * @param size The size of the structure described by this class.
1748 * @return EINA_TRUE if the structure was correctly set (The only
1749 * reason that could make it fail is if you did give wrong
1753 * @ingroup Eet_Data_Group
1755 EAPI Eina_Bool eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, const char *name, int size);
1758 * This macro is an helper that set all the parameter of an
1759 * Eet_Data_Descriptor_Class correctly when you use Eina data type
1761 * @param Clas The Eet_Data_Descriptor_Class you want to set.
1762 * @param Type The type of the structure described by this class.
1763 * @return EINA_TRUE if the structure was correctly set (The only
1764 * reason that could make it fail is if you did give wrong
1768 * @ingroup Eet_Data_Group
1770 #define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(Clas, Type) (eet_eina_file_data_descriptor_class_set(Clas, #Type , sizeof (Type)))
1773 * This function frees a data descriptor when it is not needed anymore.
1774 * @param edd The data descriptor to free.
1776 * This function takes a data descriptor handle as a parameter and frees all
1777 * data allocated for the data descriptor and the handle itself. After this
1778 * call the descriptor is no longer valid.
1781 * @ingroup Eet_Data_Group
1783 EAPI void eet_data_descriptor_free(Eet_Data_Descriptor *edd);
1786 * This function is an internal used by macros.
1788 * This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(),
1789 * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is
1790 * complex to use by hand and should be left to be used by the macros, and
1791 * thus is not documented.
1793 * @param edd The data descriptor handle to add element (member).
1794 * @param name The name of element to be serialized.
1795 * @param type The type of element to be serialized, like
1796 * #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a
1797 * group, list or hash.
1798 * @param group_type If element type is #EET_T_UNKNOW, then the @p
1799 * group_type will speficy if it is a list (#EET_G_LIST),
1800 * array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then
1801 * the member is a subtype (pointer to another type defined by
1802 * another #Eet_Data_Descriptor).
1803 * @param offset byte offset inside the source memory to be serialized.
1804 * @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY).
1805 * @param counter_name variable that defines the name of number of elements.
1806 * @param subtype If contains a subtype, then its data descriptor.
1809 * @ingroup Eet_Data_Group
1811 EAPI void eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, const char *name, int type, int group_type, int offset, /* int count_offset, */int count, const char *counter_name, Eet_Data_Descriptor *subtype);
1814 * Read a data structure from an eet file and decodes it.
1815 * @param ef The eet file handle to read from.
1816 * @param edd The data descriptor handle to use when decoding.
1817 * @param name The key the data is stored under in the eet file.
1818 * @return A pointer to the decoded data structure.
1820 * This function decodes a data structure stored in an eet file, returning
1821 * a pointer to it if it decoded successfully, or NULL on failure. This
1822 * can save a programmer dozens of hours of work in writing configuration
1823 * file parsing and writing code, as eet does all that work for the program
1824 * and presents a program-friendly data structure, just as the programmer
1825 * likes. Eet can handle members being added or deleted from the data in
1826 * storage and safely zero-fills unfilled members if they were not found
1827 * in the data. It checks sizes and headers whenever it reads data, allowing
1828 * the programmer to not worry about corrupt data.
1830 * Once a data structure has been described by the programmer with the
1831 * fields they wish to save or load, storing or retrieving a data structure
1832 * from an eet file, or from a chunk of memory is as simple as a single
1835 * @see eet_data_read_cipher()
1838 * @ingroup Eet_Data_Group
1840 EAPI void *eet_data_read(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name);
1843 * Write a data structure from memory and store in an eet file.
1844 * @param ef The eet file handle to write to.
1845 * @param edd The data descriptor to use when encoding.
1846 * @param name The key to store the data under in the eet file.
1847 * @param data A pointer to the data structure to ssave and encode.
1848 * @param compress Compression flags for storage.
1849 * @return bytes written on successful write, 0 on failure.
1851 * This function is the reverse of eet_data_read(), saving a data structure
1854 * @see eet_data_write_cipher()
1857 * @ingroup Eet_Data_Group
1859 EAPI int eet_data_write(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const void *data, int compress);
1862 * Dump an eet encoded data structure into ascii text
1863 * @param data_in The pointer to the data to decode into a struct.
1864 * @param size_in The size of the data pointed to in bytes.
1865 * @param dumpfunc The function to call passed a string when new
1866 * data is converted to text
1867 * @param dumpdata The data to pass to the @p dumpfunc callback.
1868 * @return 1 on success, 0 on failure
1870 * This function will take a chunk of data encoded by
1871 * eet_data_descriptor_encode() and convert it into human readable
1872 * ascii text. It does this by calling the @p dumpfunc callback
1873 * for all new text that is generated. This callback should append
1874 * to any existing text buffer and will be passed the pointer @p
1875 * dumpdata as a parameter as well as a string with new text to be
1881 * void output(void *data, const char *string)
1883 * printf("%s", string);
1886 * void dump(const char *file)
1892 * f = fopen(file, "r");
1893 * fseek(f, 0, SEEK_END);
1896 * data = malloc(len);
1897 * fread(data, len, 1, f);
1899 * eet_data_text_dump(data, len, output, NULL);
1903 * @see eet_data_text_dump_cipher()
1906 * @ingroup Eet_Data_Group
1908 EAPI int eet_data_text_dump(const void *data_in, int size_in, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
1911 * Take an ascii encoding from eet_data_text_dump() and re-encode in binary.
1912 * @param text The pointer to the string data to parse and encode.
1913 * @param textlen The size of the string in bytes (not including 0
1915 * @param size_ret This gets filled in with the encoded data blob
1917 * @return The encoded data on success, NULL on failure.
1919 * This function will parse the string pointed to by @p text and return
1920 * an encoded data lump the same way eet_data_descriptor_encode() takes an
1921 * in-memory data struct and encodes into a binary blob. @p text is a normal
1924 * @see eet_data_text_undump_cipher()
1927 * @ingroup Eet_Data_Group
1929 EAPI void *eet_data_text_undump(const char *text, int textlen, int *size_ret);
1932 * Dump an eet encoded data structure from an eet file into ascii text
1933 * @param ef A valid eet file handle.
1934 * @param name Name of the entry. eg: "/base/file_i_want".
1935 * @param dumpfunc The function to call passed a string when new
1936 * data is converted to text
1937 * @param dumpdata The data to pass to the @p dumpfunc callback.
1938 * @return 1 on success, 0 on failure
1940 * This function will take an open and valid eet file from
1941 * eet_open() request the data encoded by
1942 * eet_data_descriptor_encode() corresponding to the key @p name
1943 * and convert it into human readable ascii text. It does this by
1944 * calling the @p dumpfunc callback for all new text that is
1945 * generated. This callback should append to any existing text
1946 * buffer and will be passed the pointer @p dumpdata as a parameter
1947 * as well as a string with new text to be appended.
1949 * @see eet_data_dump_cipher()
1952 * @ingroup Eet_Data_Group
1954 EAPI int eet_data_dump(Eet_File *ef, const char *name, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
1957 * Take an ascii encoding from eet_data_dump() and re-encode in binary.
1958 * @param ef A valid eet file handle.
1959 * @param name Name of the entry. eg: "/base/file_i_want".
1960 * @param text The pointer to the string data to parse and encode.
1961 * @param textlen The size of the string in bytes (not including 0
1963 * @param compress Compression flags (1 == compress, 0 = don't compress).
1964 * @return 1 on success, 0 on failure
1966 * This function will parse the string pointed to by @p text,
1967 * encode it the same way eet_data_descriptor_encode() takes an
1968 * in-memory data struct and encodes into a binary blob.
1970 * The data (optionally compressed) will be in ram, pending a flush to
1971 * disk (it will stay in ram till the eet file handle is closed though).
1973 * @see eet_data_undump_cipher()
1976 * @ingroup Eet_Data_Group
1978 EAPI int eet_data_undump(Eet_File *ef, const char *name, const char *text, int textlen, int compress);
1981 * Decode a data structure from an arbitary location in memory.
1982 * @param edd The data descriptor to use when decoding.
1983 * @param data_in The pointer to the data to decode into a struct.
1984 * @param size_in The size of the data pointed to in bytes.
1985 * @return NULL on failure, or a valid decoded struct pointer on success.
1987 * This function will decode a data structure that has been encoded using
1988 * eet_data_descriptor_encode(), and return a data structure with all its
1989 * elements filled out, if successful, or NULL on failure.
1991 * The data to be decoded is stored at the memory pointed to by @p data_in,
1992 * and is described by the descriptor pointed to by @p edd. The data size is
1993 * passed in as the value to @p size_in, ande must be greater than 0 to
1996 * This function is useful for decoding data structures delivered to the
1997 * application by means other than an eet file, such as an IPC or socket
1998 * connection, raw files, shared memory etc.
2000 * Please see eet_data_read() for more information.
2002 * @see eet_data_descriptor_decode_cipher()
2005 * @ingroup Eet_Data_Group
2007 EAPI void *eet_data_descriptor_decode(Eet_Data_Descriptor *edd, const void *data_in, int size_in);
2010 * Encode a dsata struct to memory and return that encoded data.
2011 * @param edd The data descriptor to use when encoding.
2012 * @param data_in The pointer to the struct to encode into data.
2013 * @param size_ret pointer to the an int to be filled with the decoded size.
2014 * @return NULL on failure, or a valid encoded data chunk on success.
2016 * This function takes a data structutre in memory and encodes it into a
2017 * serialised chunk of data that can be decoded again by
2018 * eet_data_descriptor_decode(). This is useful for being able to transmit
2019 * data structures across sockets, pipes, IPC or shared file mechanisms,
2020 * without having to worry about memory space, machine type, endianess etc.
2022 * The parameter @p edd must point to a valid data descriptor, and
2023 * @p data_in must point to the right data structure to encode. If not, the
2024 * encoding may fail.
2026 * On success a non NULL valid pointer is returned and what @p size_ret
2027 * points to is set to the size of this decoded data, in bytes. When the
2028 * encoded data is no longer needed, call free() on it. On failure NULL is
2029 * returned and what @p size_ret points to is set to 0.
2031 * Please see eet_data_write() for more information.
2033 * @see eet_data_descriptor_encode_cipher()
2036 * @ingroup Eet_Data_Group
2038 EAPI void *eet_data_descriptor_encode(Eet_Data_Descriptor *edd, const void *data_in, int *size_ret);
2041 * Add a basic data element to a data descriptor.
2042 * @param edd The data descriptor to add the type to.
2043 * @param struct_type The type of the struct.
2044 * @param name The string name to use to encode/decode this member
2045 * (must be a constant global and never change).
2046 * @param member The struct member itself to be encoded.
2047 * @param type The type of the member to encode.
2049 * This macro is a convenience macro provided to add a member to
2050 * the data descriptor @p edd. The type of the structure is
2051 * provided as the @p struct_type parameter (for example: struct
2052 * my_struct). The @p name parameter defines a string that will be
2053 * used to uniquely name that member of the struct (it is suggested
2054 * to use the struct member itself). The @p member parameter is
2055 * the actual struct member itself (for eet_dictionary_string_check
2056 * example: values), and @p type is the basic data type of the
2057 * member which must be one of: EET_T_CHAR, EET_T_SHORT, EET_T_INT,
2058 * EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR,
2059 * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING.
2062 * @ingroup Eet_Data_Group
2064 #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
2066 struct_type ___ett; \
2068 eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
2069 (char *)(&(___ett.member)) - (char *)(&(___ett)), \
2070 0, /* 0, */NULL, NULL); \
2074 * Add a sub-element type to a data descriptor
2075 * @param edd The data descriptor to add the type to.
2076 * @param struct_type The type of the struct.
2077 * @param name The string name to use to encode/decode this member
2078 * (must be a constant global and never change).
2079 * @param member The struct member itself to be encoded.
2080 * @param subtype The type of sub-type struct to add.
2082 * This macro lets you easily add a sub-type (a struct that's pointed to
2083 * by this one). All the parameters are the same as for
2084 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception.
2085 * This must be the data descriptor of the struct that is pointed to by
2089 * @ingroup Eet_Data_Group
2091 #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
2093 struct_type ___ett; \
2095 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
2096 (char *)(&(___ett.member)) - (char *)(&(___ett)), \
2097 0, /* 0, */NULL, subtype); \
2101 * Add a linked list type to a data descriptor
2102 * @param edd The data descriptor to add the type to.
2103 * @param struct_type The type of the struct.
2104 * @param name The string name to use to encode/decode this member
2105 * (must be a constant global and never change).
2106 * @param member The struct member itself to be encoded.
2107 * @param subtype The type of linked list member to add.
2109 * This macro lets you easily add a linked list of other data types. All the
2110 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
2111 * @p subtype being the exception. This must be the data descriptor of the
2112 * element that is in each member of the linked list to be stored.
2115 * @ingroup Eet_Data_Group
2117 #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \
2119 struct_type ___ett; \
2121 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
2122 (char *)(&(___ett.member)) - (char *)(&(___ett)), \
2123 0, /* 0, */NULL, subtype); \
2127 * Add a hash type to a data descriptor
2128 * @param edd The data descriptor to add the type to.
2129 * @param struct_type The type of the struct.
2130 * @param name The string name to use to encode/decode this member
2131 * (must be a constant global and never change).
2132 * @param member The struct member itself to be encoded.
2133 * @param subtype The type of hash member to add.
2135 * This macro lets you easily add a hash of other data types. All the
2136 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
2137 * @p subtype being the exception. This must be the data descriptor of the
2138 * element that is in each member of the hash to be stored.
2141 * @ingroup Eet_Data_Group
2143 #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \
2145 struct_type ___ett; \
2147 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \
2148 (char *)(&(___ett.member)) - (char *)(&(___ett)), \
2149 0, /* 0, */NULL, subtype); \
2153 * Add a fixed size array type to a data descriptor
2154 * @param edd The data descriptor to add the type to.
2155 * @param struct_type The type of the struct.
2156 * @param name The string name to use to encode/decode this member
2157 * (must be a constant global and never change).
2158 * @param member The struct member itself to be encoded.
2159 * @param subtype The type of hash member to add.
2161 * This macro lets you easily add a fixed size array of other data
2162 * types. All the parameters are the same as for
2163 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
2164 * exception. This must be the data descriptor of the element that
2165 * is in each member of the hash to be stored.
2168 * @ingroup Eet_Data_Group
2170 #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \
2172 struct_type ___ett; \
2174 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \
2175 (char *)(&(___ett.member)) - (char *)(&(___ett)), \
2176 /* 0, */sizeof(___ett.member)/sizeof(___ett.member[0]), NULL, subtype); \
2180 * Add a variable size array type to a data descriptor
2181 * @param edd The data descriptor to add the type to.
2182 * @param struct_type The type of the struct.
2183 * @param name The string name to use to encode/decode this member
2184 * (must be a constant global and never change).
2185 * @param member The struct member itself to be encoded.
2186 * @param subtype The type of hash member to add.
2188 * This macro lets you easily add a fixed size array of other data
2189 * types. All the parameters are the same as for
2190 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
2191 * exception. This must be the data descriptor of the element that
2192 * is in each member of the hash to be stored.
2195 * @ingroup Eet_Data_Group
2197 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \
2199 struct_type ___ett; \
2201 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VAR_ARRAY, \
2202 (char *)(&(___ett.member)) - (char *)(&(___ett)), \
2203 (char *)(&(___ett.member ## _count)) - (char *)(&(___ett)), /* 0, */NULL, subtype); \
2207 * Add an union type to a data descriptor
2208 * @param edd The data descriptor to add the type to.
2209 * @param struct_type The type of the struct.
2210 * @param name The string name to use to encode/decode this member
2211 * (must be a constant global and never change).
2212 * @param member The struct member itself to be encoded.
2213 * @param type_member The member that give hints on what is in the union.
2214 * @param unified_type Describe all possible type the union could handle.
2216 * This macro lets you easily add an union with a member that specify what is inside.
2217 * The @p unified_type is an Eet_Data_Descriptor, but only the entry that match the name
2218 * returned by type_get will be used for each serialized data. The type_get and type_set
2219 * callback of unified_type should be defined.
2222 * @ingroup Eet_Data_Group
2223 * @see Eet_Data_Descriptor_Class
2225 #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type) \
2227 struct_type ___ett; \
2229 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, \
2230 (char *) (&(___ett.member)) - (char *)(&(___ett)), \
2231 (char *) (&(___ett.type_member)) - (char *)(&(___ett)), \
2232 NULL, unified_type); \
2236 * Add a automatically selectable type to a data descriptor
2237 * @param edd The data descriptor to add the type to.
2238 * @param struct_type The type of the struct.
2239 * @param name The string name to use to encode/decode this member
2240 * (must be a constant global and never change).
2241 * @param member The struct member itself to be encoded.
2242 * @param type_member The member that give hints on what is in the union.
2243 * @param unified_type Describe all possible type the union could handle.
2245 * This macro lets you easily define what the content of @p member points to depending of
2246 * the content of @p type_member. The type_get and type_set callback of unified_type should
2247 * be defined. If the the type is not know at the time of restoring it, eet will still call
2248 * type_set of @p unified_type but the pointer will be set to a serialized binary representation
2249 * of what eet know. This make it possible, to save this pointer again by just returning the string
2250 * given previously and telling it by setting unknow to EINA_TRUE.
2253 * @ingroup Eet_Data_Group
2254 * @see Eet_Data_Descriptor_Class
2256 #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type) \
2258 struct_type ___ett; \
2260 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT, \
2261 (char *) (&(___ett.member)) - (char *)(&(___ett)), \
2262 (char *) (&(___ett.type_member)) - (char *)(&(___ett)), \
2263 NULL, unified_type); \
2267 * Add a mapping to a data descriptor that will be used by union, variant or inherited type
2268 * @param unified_type The data descriptor to add the mapping to.
2269 * @param name The string name to get/set type.
2270 * @param subtype The matching data descriptor.
2273 * @ingroup Eet_Data_Group
2274 * @see Eet_Data_Descriptor_Class
2276 #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \
2277 eet_data_descriptor_element_add(unified_type, name, EET_T_UNKNOW, EET_G_UNKNOWN, 0, 0, NULL, subtype);
2280 * @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers
2282 * Most of the @ref Eet_Data_Group have alternative versions that
2283 * accounts for ciphers to protect their content.
2285 * @see @ref Eet_Cipher_Group
2287 * @ingroup Eet_Data_Group
2291 * Read a data structure from an eet file and decodes it using a cipher.
2292 * @param ef The eet file handle to read from.
2293 * @param edd The data descriptor handle to use when decoding.
2294 * @param name The key the data is stored under in the eet file.
2295 * @param cipher_key The key to use as cipher.
2296 * @return A pointer to the decoded data structure.
2298 * This function decodes a data structure stored in an eet file, returning
2299 * a pointer to it if it decoded successfully, or NULL on failure. This
2300 * can save a programmer dozens of hours of work in writing configuration
2301 * file parsing and writing code, as eet does all that work for the program
2302 * and presents a program-friendly data structure, just as the programmer
2303 * likes. Eet can handle members being added or deleted from the data in
2304 * storage and safely zero-fills unfilled members if they were not found
2305 * in the data. It checks sizes and headers whenever it reads data, allowing
2306 * the programmer to not worry about corrupt data.
2308 * Once a data structure has been described by the programmer with the
2309 * fields they wish to save or load, storing or retrieving a data structure
2310 * from an eet file, or from a chunk of memory is as simple as a single
2313 * @see eet_data_read()
2316 * @ingroup Eet_Data_Cipher_Group
2318 EAPI void *eet_data_read_cipher(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const char *cipher_key);
2321 * Write a data structure from memory and store in an eet file
2323 * @param ef The eet file handle to write to.
2324 * @param edd The data descriptor to use when encoding.
2325 * @param name The key to store the data under in the eet file.
2326 * @param cipher_key The key to use as cipher.
2327 * @param data A pointer to the data structure to ssave and encode.
2328 * @param compress Compression flags for storage.
2329 * @return bytes written on successful write, 0 on failure.
2331 * This function is the reverse of eet_data_read(), saving a data structure
2334 * @see eet_data_write_cipher()
2337 * @ingroup Eet_Data_Cipher_Group
2339 EAPI int eet_data_write_cipher(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const char *cipher_key, const void *data, int compress);
2342 * Dump an eet encoded data structure into ascii text using a cipher.
2343 * @param data_in The pointer to the data to decode into a struct.
2344 * @param cipher_key The key to use as cipher.
2345 * @param size_in The size of the data pointed to in bytes.
2346 * @param dumpfunc The function to call passed a string when new
2347 * data is converted to text
2348 * @param dumpdata The data to pass to the @p dumpfunc callback.
2349 * @return 1 on success, 0 on failure
2351 * This function will take a chunk of data encoded by
2352 * eet_data_descriptor_encode() and convert it into human readable
2353 * ascii text. It does this by calling the @p dumpfunc callback
2354 * for all new text that is generated. This callback should append
2355 * to any existing text buffer and will be passed the pointer @p
2356 * dumpdata as a parameter as well as a string with new text to be
2362 * void output(void *data, const char *string)
2364 * printf("%s", string);
2367 * void dump(const char *file)
2373 * f = fopen(file, "r");
2374 * fseek(f, 0, SEEK_END);
2377 * data = malloc(len);
2378 * fread(data, len, 1, f);
2380 * eet_data_text_dump_cipher(data, cipher_key, len, output, NULL);
2384 * @see eet_data_text_dump()
2387 * @ingroup Eet_Data_Cipher_Group
2389 EAPI int eet_data_text_dump_cipher(const void *data_in, const char *cipher_key, int size_in, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
2392 * Take an ascii encoding from eet_data_text_dump() and re-encode
2393 * in binary using a cipher.
2394 * @param text The pointer to the string data to parse and encode.
2395 * @param cipher_key The key to use as cipher.
2396 * @param textlen The size of the string in bytes (not including 0
2398 * @param size_ret This gets filled in with the encoded data blob
2400 * @return The encoded data on success, NULL on failure.
2402 * This function will parse the string pointed to by @p text and return
2403 * an encoded data lump the same way eet_data_descriptor_encode() takes an
2404 * in-memory data struct and encodes into a binary blob. @p text is a normal
2407 * @see eet_data_text_undump()
2410 * @ingroup Eet_Data_Cipher_Group
2412 EAPI void *eet_data_text_undump_cipher(const char *text, const char *cipher_key, int textlen, int *size_ret);
2415 * Dump an eet encoded data structure from an eet file into ascii
2416 * text using a cipher.
2417 * @param ef A valid eet file handle.
2418 * @param name Name of the entry. eg: "/base/file_i_want".
2419 * @param cipher_key The key to use as cipher.
2420 * @param dumpfunc The function to call passed a string when new
2421 * data is converted to text
2422 * @param dumpdata The data to pass to the @p dumpfunc callback.
2423 * @return 1 on success, 0 on failure
2425 * This function will take an open and valid eet file from
2426 * eet_open() request the data encoded by
2427 * eet_data_descriptor_encode() corresponding to the key @p name
2428 * and convert it into human readable ascii text. It does this by
2429 * calling the @p dumpfunc callback for all new text that is
2430 * generated. This callback should append to any existing text
2431 * buffer and will be passed the pointer @p dumpdata as a parameter
2432 * as well as a string with new text to be appended.
2434 * @see eet_data_dump()
2437 * @ingroup Eet_Data_Cipher_Group
2439 EAPI int eet_data_dump_cipher(Eet_File *ef, const char *name, const char *cipher_key, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
2442 * Take an ascii encoding from eet_data_dump() and re-encode in
2443 * binary using a cipher.
2444 * @param ef A valid eet file handle.
2445 * @param name Name of the entry. eg: "/base/file_i_want".
2446 * @param cipher_key The key to use as cipher.
2447 * @param text The pointer to the string data to parse and encode.
2448 * @param textlen The size of the string in bytes (not including 0
2450 * @param compress Compression flags (1 == compress, 0 = don't compress).
2451 * @return 1 on success, 0 on failure
2453 * This function will parse the string pointed to by @p text,
2454 * encode it the same way eet_data_descriptor_encode() takes an
2455 * in-memory data struct and encodes into a binary blob.
2457 * The data (optionally compressed) will be in ram, pending a flush to
2458 * disk (it will stay in ram till the eet file handle is closed though).
2460 * @see eet_data_undump()
2463 * @ingroup Eet_Data_Cipher_Group
2465 EAPI int eet_data_undump_cipher(Eet_File *ef, const char *name, const char *cipher_key, const char *text, int textlen, int compress);
2468 * Decode a data structure from an arbitary location in memory
2470 * @param edd The data descriptor to use when decoding.
2471 * @param data_in The pointer to the data to decode into a struct.
2472 * @param cipher_key The key to use as cipher.
2473 * @param size_in The size of the data pointed to in bytes.
2474 * @return NULL on failure, or a valid decoded struct pointer on success.
2476 * This function will decode a data structure that has been encoded using
2477 * eet_data_descriptor_encode(), and return a data structure with all its
2478 * elements filled out, if successful, or NULL on failure.
2480 * The data to be decoded is stored at the memory pointed to by @p data_in,
2481 * and is described by the descriptor pointed to by @p edd. The data size is
2482 * passed in as the value to @p size_in, ande must be greater than 0 to
2485 * This function is useful for decoding data structures delivered to the
2486 * application by means other than an eet file, such as an IPC or socket
2487 * connection, raw files, shared memory etc.
2489 * Please see eet_data_read() for more information.
2491 * @see eet_data_descriptor_decode()
2494 * @ingroup Eet_Data_Cipher_Group
2496 EAPI void *eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd, const void *data_in, const char *cipher_key, int size_in);
2499 * Encode a data struct to memory and return that encoded data
2501 * @param edd The data descriptor to use when encoding.
2502 * @param data_in The pointer to the struct to encode into data.
2503 * @param cipher_key The key to use as cipher.
2504 * @param size_ret pointer to the an int to be filled with the decoded size.
2505 * @return NULL on failure, or a valid encoded data chunk on success.
2507 * This function takes a data structutre in memory and encodes it into a
2508 * serialised chunk of data that can be decoded again by
2509 * eet_data_descriptor_decode(). This is useful for being able to transmit
2510 * data structures across sockets, pipes, IPC or shared file mechanisms,
2511 * without having to worry about memory space, machine type, endianess etc.
2513 * The parameter @p edd must point to a valid data descriptor, and
2514 * @p data_in must point to the right data structure to encode. If not, the
2515 * encoding may fail.
2517 * On success a non NULL valid pointer is returned and what @p size_ret
2518 * points to is set to the size of this decoded data, in bytes. When the
2519 * encoded data is no longer needed, call free() on it. On failure NULL is
2520 * returned and what @p size_ret points to is set to 0.
2522 * Please see eet_data_write() for more information.
2524 * @see eet_data_descriptor_encode()
2527 * @ingroup Eet_Data_Cipher_Group
2529 EAPI void *eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd, const void *data_in, const char *cipher_key, int *size_ret);
2532 * @defgroup Eet_Node_Group Low-level Serialization Structures.
2534 * Functions that create, destroy and manipulate serialization nodes
2535 * used by @ref Eet_Data_Group.
2542 * Opaque handle to manage serialization node.
2544 typedef struct _Eet_Node Eet_Node;
2547 * @typedef Eet_Node_Data
2548 * Contains an union that can fit any kind of node.
2550 typedef struct _Eet_Node_Data Eet_Node_Data;
2553 * @struct _Eet_Node_Data
2554 * Contains an union that can fit any kind of node.
2556 struct _Eet_Node_Data
2568 unsigned long long ul;
2579 * @ingroup Eet_Node_Group
2581 EAPI Eet_Node *eet_node_char_new(const char *name, char c);
2585 * @ingroup Eet_Node_Group
2587 EAPI Eet_Node *eet_node_short_new(const char *name, short s);
2591 * @ingroup Eet_Node_Group
2593 EAPI Eet_Node *eet_node_int_new(const char *name, int i);
2597 * @ingroup Eet_Node_Group
2599 EAPI Eet_Node *eet_node_long_long_new(const char *name, long long l);
2603 * @ingroup Eet_Node_Group
2605 EAPI Eet_Node *eet_node_float_new(const char *name, float f);
2609 * @ingroup Eet_Node_Group
2611 EAPI Eet_Node *eet_node_double_new(const char *name, double d);
2615 * @ingroup Eet_Node_Group
2617 EAPI Eet_Node *eet_node_unsigned_char_new(const char *name, unsigned char uc);
2621 * @ingroup Eet_Node_Group
2623 EAPI Eet_Node *eet_node_unsigned_short_new(const char *name, unsigned short us);
2627 * @ingroup Eet_Node_Group
2629 EAPI Eet_Node *eet_node_unsigned_int_new(const char *name, unsigned int ui);
2633 * @ingroup Eet_Node_Group
2635 EAPI Eet_Node *eet_node_unsigned_long_long_new(const char *name, unsigned long long l);
2639 * @ingroup Eet_Node_Group
2641 EAPI Eet_Node *eet_node_string_new(const char *name, const char *str);
2645 * @ingroup Eet_Node_Group
2647 EAPI Eet_Node *eet_node_inlined_string_new(const char *name, const char *str);
2651 * @ingroup Eet_Node_Group
2653 EAPI Eet_Node *eet_node_null_new(const char *name);
2657 * @ingroup Eet_Node_Group
2659 EAPI Eet_Node *eet_node_list_new(const char *name, Eina_List *nodes);
2663 * @ingroup Eet_Node_Group
2665 EAPI Eet_Node *eet_node_array_new(const char *name, int count, Eina_List *nodes);
2669 * @ingroup Eet_Node_Group
2671 EAPI Eet_Node *eet_node_var_array_new(const char *name, Eina_List *nodes);
2675 * @ingroup Eet_Node_Group
2677 EAPI Eet_Node *eet_node_hash_new(const char *name, const char *key, Eet_Node *node);
2681 * @ingroup Eet_Node_Group
2683 EAPI Eet_Node *eet_node_struct_new(const char *name, Eina_List *nodes);
2687 * @ingroup Eet_Node_Group
2689 EAPI Eet_Node *eet_node_struct_child_new(const char *parent, Eet_Node *child);
2694 * @ingroup Eet_Node_Group
2696 EAPI void eet_node_list_append(Eet_Node *parent, const char *name, Eet_Node *child);
2700 * @ingroup Eet_Node_Group
2702 EAPI void eet_node_struct_append(Eet_Node *parent, const char *name, Eet_Node *child);
2706 * @ingroup Eet_Node_Group
2708 EAPI void eet_node_hash_add(Eet_Node *parent, const char *name, const char *key, Eet_Node *child);
2713 * @ingroup Eet_Node_Group
2715 EAPI void eet_node_dump(Eet_Node *n, int dumplevel, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
2719 * @ingroup Eet_Node_Group
2721 EAPI void eet_node_del(Eet_Node *n);
2725 * @ingroup Eet_Node_Group
2727 EAPI void *eet_data_node_encode_cipher(Eet_Node *node, const char *cipher_key, int *size_ret);
2731 * @ingroup Eet_Node_Group
2733 EAPI Eet_Node *eet_data_node_decode_cipher(const void *data_in, const char *cipher_key, int size_in);
2737 * @ingroup Eet_Node_Group
2739 EAPI Eet_Node *eet_data_node_read_cipher(Eet_File *ef, const char *name, const char *cipher_key);
2743 * @ingroup Eet_Node_Group
2745 EAPI int eet_data_node_write_cipher(Eet_File *ef, const char *name, const char *cipher_key, Eet_Node *node, int compress);
2747 /* EXPERIMENTAL: THIS API MAY CHANGE IN THE FUTURE, USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING. */
2750 * @typedef Eet_Node_Walk
2751 * Describes how to walk trees of #Eet_Node.
2753 typedef struct _Eet_Node_Walk Eet_Node_Walk;
2756 * @struct _Eet_Node_Walk
2757 * Describes how to walk trees of #Eet_Node.
2759 struct _Eet_Node_Walk
2761 void *(*struct_alloc)(const char *type, void *user_data);
2762 void (*struct_add)(void *parent, const char *name, void *child, void *user_data);
2763 void *(*array)(Eina_Bool variable, const char *name, int count, void *user_data);
2764 void (*insert)(void *array, int index, void *child, void *user_data);
2765 void *(*list)(const char *name, void *user_data);
2766 void (*append)(void *list, void *child, void *user_data);
2767 void *(*hash)(void *parent, const char *name, const char *key, void *value, void *user_data);
2768 void *(*simple)(int type, Eet_Node_Data *data, void *user_data);
2771 EAPI void *eet_node_walk(void *parent, const char *name, Eet_Node *root, Eet_Node_Walk *cb, void *user_data);
2776 * @defgroup Eet_Connection_Group Helper function to use eet over a network link
2778 * Function that reconstruct and prepare packet of @ref Eet_Data_Group to be send.
2783 * @typedef Eet_Connection
2784 * Opaque handle to track paquet for a specific connection.
2786 * @ingroup Eet_Connection_Group
2788 typedef struct _Eet_Connection Eet_Connection;
2791 * @typedef Eet_Read_Cb
2792 * Called back when an @ref Eet_Data_Group has been received completly and could be used.
2794 * @ingroup Eet_Connection_Group
2796 typedef Eina_Bool Eet_Read_Cb(const void *eet_data, size_t size, void *user_data);
2799 * @typedef Eet_Write_Cb
2800 * Called back when a packet containing @ref Eet_Data_Group data is ready to be send.
2802 * @ingroup Eet_Connection_Group
2804 typedef Eina_Bool Eet_Write_Cb(const void *data, size_t size, void *user_data);
2807 * Instanciate a new connection to track.
2808 * @oaram eet_read_cb Function to call when one Eet_Data packet has been fully assemble.
2809 * @param eet_write_cb Function to call when one Eet_Data packet is ready to be send over the wire.
2810 * @param user_data Pointer provided to both functions to be used as a context handler.
2811 * @return NULL on failure, or a valid Eet_Connection handler.
2813 * For every connection to track you will need a separate Eet_Connection provider.
2816 * @ingroup Eet_Connection_Group
2818 Eet_Connection *eet_connection_new(Eet_Read_Cb *eet_read_cb, Eet_Write_Cb *eet_write_cb, const void *user_data);
2821 * Process a raw packet received over the link
2822 * @oaram conn Connection handler to track.
2823 * @param data Raw data packet.
2824 * @param size The size of that packet.
2825 * @return 0 on complete success, any other value indicate where in the stream it got wrong (It could be before that packet).
2827 * Every time you receive a packet related to your connection, you should pass
2828 * it to that function so that it could process and assemble packet has you
2829 * receive it. It will automatically call Eet_Read_Cb when one is fully received.
2832 * @ingroup Eet_Connection_Group
2834 int eet_connection_received(Eet_Connection *conn, const void *data, size_t size);
2837 * Convert a complex structure and prepare it to be send.
2838 * @oaram conn Connection handler to track.
2839 * @param edd The data descriptor to use when encoding.
2840 * @param data_in The pointer to the struct to encode into data.
2841 * @param cipher_key The key to use as cipher.
2842 * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
2844 * This function serialize data_in with edd, assemble the packet and call
2845 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
2846 * and will vanish just after the return of the callback.
2848 * @see eet_data_descriptor_encode_cipher
2851 * @ingroup Eet_Connection_Group
2853 Eina_Bool eet_connection_send(Eet_Connection *conn, Eet_Data_Descriptor *edd, const void *data_in, const char *cipher_key);
2856 * Convert a Eet_Node tree and prepare it to be send.
2857 * @oaram conn Connection handler to track.
2858 * @param node The data tree to use when encoding.
2859 * @param cipher_key The key to use as cipher.
2860 * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't.
2862 * This function serialize node, assemble the packet and call
2863 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated
2864 * and will vanish just after the return of the callback.
2866 * @see eet_data_node_encode_cipher
2869 * @ingroup Eet_Connection_Group
2871 Eina_Bool eet_connection_node_send(Eet_Connection *conn, Eet_Node *node, const char *cipher_key);
2874 * Close a connection and lost its track.
2875 * @oaram conn Connection handler to close.
2876 * @param on_going Signal if a partial packet wasn't completed.
2877 * @return the user_data passed to both callback.
2880 * @ingroup Eet_Connection_Group
2882 void *eet_connection_close(Eet_Connection *conn, Eina_Bool *on_going);
2884 /***************************************************************************/