summaryrefslogtreecommitdiff
path: root/src/lib/eet
diff options
context:
space:
mode:
authorVincent Torri <vincent.torri@gmail.com>2012-09-17 16:35:38 +0000
committerVincent Torri <vincent.torri@gmail.com>2012-09-17 16:35:38 +0000
commit8abaff3bdf53ecc7e605b82b12e385b8c0a02327 (patch)
tree4c828ae7083f724fd0214cf3624b20a7cf9448d2 /src/lib/eet
parent12732ab7ebcacad66352d3d48306e9945a4a584f (diff)
merge: add eet
SVN revision: 76768
Diffstat (limited to 'src/lib/eet')
-rw-r--r--src/lib/eet/Eet.h4271
-rw-r--r--src/lib/eet/Eet_private.h329
-rw-r--r--src/lib/eet/Makefile.am43
-rw-r--r--src/lib/eet/eet_alloc.c93
-rw-r--r--src/lib/eet/eet_cipher.c1391
-rw-r--r--src/lib/eet/eet_connection.c228
-rw-r--r--src/lib/eet/eet_data.c5014
-rw-r--r--src/lib/eet/eet_dictionary.c514
-rw-r--r--src/lib/eet/eet_image.c1881
-rw-r--r--src/lib/eet/eet_lib.c2707
-rw-r--r--src/lib/eet/eet_node.c797
-rw-r--r--src/lib/eet/eet_utils.c36
-rw-r--r--src/lib/eet/lz4/README7
-rw-r--r--src/lib/eet/lz4/lz4.c819
-rw-r--r--src/lib/eet/lz4/lz4.h120
-rw-r--r--src/lib/eet/lz4/lz4hc.c663
-rw-r--r--src/lib/eet/lz4/lz4hc.h60
17 files changed, 18973 insertions, 0 deletions
diff --git a/src/lib/eet/Eet.h b/src/lib/eet/Eet.h
new file mode 100644
index 0000000000..05f80e959f
--- /dev/null
+++ b/src/lib/eet/Eet.h
@@ -0,0 +1,4271 @@
1/**
2 @brief Eet Data Handling Library Public API Calls
3
4 These routines are used for Eet Library interaction
5
6 @mainpage Eet Library Documentation
7
8 @version 1.7.0
9 @date 2000-2012
10
11 Please see the @ref authors page for contact details.
12
13 @section toc Table of Contents
14
15 @li @ref intro
16 @li @ref example
17 @li @ref compiling
18 @li @ref install
19 @li @ref next_steps
20 @li @ref intro_example
21
22 @section intro What is Eet?
23
24 It is a tiny library designed to write an arbitrary set of chunks of data
25 to a file and optionally compress each chunk (very much like a zip file)
26 and allow fast random-access reading of the file later on. It does not
27 do zip as a zip itself has more complexity than is needed, and it was much
28 simpler to implement this once here.
29
30 Eet is extremely fast, small and simple. Eet files can be very small and
31 highly compressed, making them very optimal for just sending across the
32 internet without having to archive, compress or decompress and install them.
33 They allow for lightning-fast random-access reads once created, making them
34 perfect for storing data that is written once (or rarely) and read many
35 times, but the program does not want to have to read it all in at once.
36
37 It also can encode and decode data structures in memory, as well as image
38 data for saving to Eet files or sending across the network to other
39 machines, or just writing to arbitrary files on the system. All data is
40 encoded in a platform independent way and can be written and read by any
41 architecture.
42
43 @section example A simple example on using Eet
44
45 Here is a simple example on how to use Eet to save a series of strings to a
46 file and load them again. The advantage of using Eet over just
47 fprintf() and
48 fscanf() is that not only can these entries be strings, they need no special
49 parsing to handle delimiter characters or escaping, they can be binary data,
50 image data, data structures containing integers, strings, other data
51 structures, linked lists and much more, without the programmer having to
52 worry about parsing, and best of all, Eet is very fast.
53
54 This is just a very simple example that doesn't show all of the capabilities
55 of Eet, but it serves to illustrate its simplicity.
56
57 @include eet-basic.c
58
59 @section compiling How to compile using Eet ?
60
61 Eet is a library your application links to. The procedure for this is very
62 simple. You simply have to compile your application with the appropriate
63 compiler flags that the @p pkg-config script outputs. For example:
64
65 Compiling C or C++ files into object files:
66
67 @verbatim
68 gcc -c -o main.o main.c `pkg-config --cflags eet`
69 @endverbatim
70
71 Linking object files into a binary executable:
72
73 @verbatim
74 gcc -o my_application main.o `pkg-config --libs eet`
75 @endverbatim
76
77 You simply have to make sure that pkg-config is in your shell's PATH (see
78 the manual page for your appropriate shell) and eet.pc in /usr/lib/pkgconfig
79 or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
80 to link and use Eet once you have written your code to use it.
81
82 Since the program is linked to Eet, it is now able to use any advertised
83 API calls to serialize your data.
84
85 You should make sure you add any extra compile and link flags to your
86 compile commands that your application may need as well. The above example
87 is only guaranteed to make Eet add it's own requirements.
88
89
90 @section install How is it installed?
91
92 Simple:
93
94 @verbatim
95 ./configure
96 make
97 su -
98 ...
99 make install
100 @endverbatim
101
102 @section next_steps Next Steps
103
104 After you understood what Eet is and installed it in your system you
105 should proceed understanding the programming interface. We'd recommend
106 you to take a while to learn Eina
107 (http://docs.enlightenment.org/auto/eina/) as it is very convenient
108 and optimized, and Eet provides integration with it.
109
110 Recommended reading:
111
112 @li @ref Eet_File_Group to know the basics to open and save files.
113 @li @ref Eet_Data_Group to know the convenient way to serialize and
114 parse your data structures automatically. Just create your
115 descriptors and let Eet do the work for you.
116
117 @section intro_example Introductory Examples
118
119 @ref Examples
120
121 @todo Document data format for images and data structures.
122
123 */
124
125/**
126 @page authors Authors
127 @author Carsten Haitzler <raster@@rasterman.com>
128 @author David Goodlad <dgoodlad@@gmail.com>
129 @author Cedric Bail <cedric.bail@@free.fr>
130 @author Arnaud de Turckheim <quarium@@gmail.com>
131 @author Luis Felipe Strano Moraes <lfelipe@@profusion.mobi>
132 @author Chidambar Zinnoury <illogict@@online.fr>
133 @author Vincent Torri <vtorri@@univ-evry.fr>
134 @author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
135 @author Raphael Kubo da Costa <kubo@@profusion.mobi>
136 @author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
137 @author Albin "Lutin" Tonnerre <albin.tonnerre@@gmail.com>
138 @author Adam Simpkins <adam@@adamsimpkins.net>
139 @author Mike Blumenkrantz <michael.blumenkrantz@gmail.com>
140
141 Please contact <enlightenment-devel@lists.sourceforge.net> to get in
142 contact with the developers and maintainers.
143 */
144
145#ifndef _EET_H
146#define _EET_H
147
148#include <stdlib.h>
149#include <stdio.h>
150#include <Eina.h>
151
152#ifdef EAPI
153# undef EAPI
154#endif /* ifdef EAPI */
155
156#ifdef _WIN32
157# ifdef EFL_EET_BUILD
158# ifdef DLL_EXPORT
159# define EAPI __declspec(dllexport)
160# else /* ifdef DLL_EXPORT */
161# define EAPI
162# endif /* ! DLL_EXPORT */
163# else /* ifdef EFL_EET_BUILD */
164# define EAPI __declspec(dllimport)
165# endif /* ! EFL_EET_BUILD */
166#else /* ifdef _WIN32 */
167# ifdef __GNUC__
168# if __GNUC__ >= 4
169# define EAPI __attribute__ ((visibility("default")))
170# else /* if __GNUC__ >= 4 */
171# define EAPI
172# endif /* if __GNUC__ >= 4 */
173# else /* ifdef __GNUC__ */
174# define EAPI
175# endif /* ifdef __GNUC__ */
176#endif /* ! _WIN32 */
177
178#ifdef __cplusplus
179extern "C" {
180#endif /* ifdef __cplusplus */
181
182/**
183 * @file Eet.h
184 * @brief The file that provides the eet functions.
185 *
186 * This header provides the Eet management functions.
187 *
188 */
189
190#define EET_VERSION_MAJOR 1
191#define EET_VERSION_MINOR 8
192/**
193 * @typedef Eet_Version
194 *
195 * This is the Eet version information structure that can be used at
196 * runtime to detect which version of eet is being used and adapt
197 * appropriately as follows for example:
198 *
199 * @code
200 * #if defined(EET_VERSION_MAJOR) && (EET_VERSION_MAJOR >= 1) && defined(EET_VERSION_MINOR) && (EET_VERSION_MINOR > 2)
201 * printf("Eet version: %i.%i.%i\n",
202 * eet_version->major,
203 * eet_version->minor,
204 * eet_version->micro);
205 * if (eet_version->revision > 0)
206 * {
207 * printf(" Built from SVN revision # %i\n", eet_version->revision);
208 * }
209 * #endif
210 * @endcode
211 *
212 * Note the \#if check can be dropped if your program refuses to compile or
213 * work with an Eet version less than 1.3.0.
214 */
215typedef struct _Eet_Version
216{
217 int major; /** < major (binary or source incompatible changes) */
218 int minor; /** < minor (new features, bugfixes, major improvements version) */
219 int micro; /** < micro (bugfix, internal improvements, no new features version) */
220 int revision; /** < svn revision (0 if a proper release or the svn revision number Eet is built from) */
221} Eet_Version;
222
223EAPI extern Eet_Version *eet_version;
224
225/**
226 * @defgroup Eet_Group Top level functions
227 * Functions that affect Eet as a whole.
228 *
229 * @{
230 */
231
232/**
233 * @enum _Eet_Error
234 * All the error identifiers known by Eet.
235 */
236typedef enum _Eet_Error
237{
238 EET_ERROR_NONE, /**< No error, it's all fine! */
239 EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */
240 EET_ERROR_EMPTY, /**< There was nothing to do */
241 EET_ERROR_NOT_WRITABLE, /**< Could not write to file or file is #EET_FILE_MODE_READ */
242 EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */
243 EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */
244 EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it is too big */
245 EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write due a generic Input/Output error */
246 EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of space */
247 EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */
248 EET_ERROR_MMAP_FAILED, /**< Could not mmap file */
249 EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */
250 EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */
251 EET_ERROR_INVALID_SIGNATURE, /**< Signature is invalid */
252 EET_ERROR_NOT_SIGNED, /**< File or contents are not signed */
253 EET_ERROR_NOT_IMPLEMENTED, /**< Function is not implemented */
254 EET_ERROR_PRNG_NOT_SEEDED, /**< Could not introduce random seed */
255 EET_ERROR_ENCRYPT_FAILED, /**< Could not encrypt contents */
256 EET_ERROR_DECRYPT_FAILED /**< Could not decrypt contents */
257} Eet_Error; /**< Eet error identifiers */
258
259/**
260 * @}
261 */
262
263/**
264 * @defgroup Eet_Compression Eet Compression Levels
265 * Compression modes/levels supported by Eet.
266 *
267 * @{
268 */
269
270/**
271 * @enum _Eet_Compression
272 * All the compression modes known by Eet.
273 */
274
275typedef enum _Eet_Compression
276{
277 EET_COMPRESSION_NONE = 0, /**< No compression at all @since 1.7 */
278 EET_COMPRESSION_DEFAULT = 1, /**< Default compression (Zlib) @since 1.7 */
279 EET_COMPRESSION_LOW = 2, /**< Fast but minimal compression (Zlib) @since 1.7 */
280 EET_COMPRESSION_MED = 6, /**< Medium compression level (Zlib) @since 1.7 */
281 EET_COMPRESSION_HI = 9, /**< Slow but high compression level (Zlib) @since 1.7 */
282 EET_COMPRESSION_VERYFAST = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */
283 EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST) (LZ4) @since 1.7 */
284
285 EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Don't use it @since 1.7 */
286 EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Don't use it @since 1.7 */
287 EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Don't use it @since 1.7 */
288 EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Don't use it @since 1.7 */
289 EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Don't use it @since 1.7 */
290} Eet_Compression; /**< Eet compression modes @since 1.7 */
291
292/**
293 * @}
294 */
295
296/**
297 * Initialize the EET library.
298 *
299 * The first time this function is called, it will perform all the internal
300 * initialization required for the library to function properly and increment
301 * the initialization counter. Any subsequent call only increment this counter
302 * and return its new value, so it's safe to call this function more than once.
303 *
304 * @return The new init count. Will be 0 if initialization failed.
305 *
306 * @since 1.0.0
307 * @ingroup Eet_Group
308 */
309EAPI int
310eet_init(void);
311
312/**
313 * Shut down the EET library.
314 *
315 * If eet_init() was called more than once for the running application,
316 * eet_shutdown() will decrement the initialization counter and return its
317 * new value, without doing anything else. When the counter reaches 0, all
318 * of the internal elements will be shutdown and any memory used freed.
319 *
320 * @return The new init count.
321 *
322 * @since 1.0.0
323 * @ingroup Eet_Group
324 */
325EAPI int
326eet_shutdown(void);
327
328/**
329 * Clear eet cache
330 *
331 * For a faster access to previously accessed data, Eet keeps an internal
332 * cache of files. These files will be freed automatically only when
333 * they are unused and the cache gets full, in order based on the last time
334 * they were used.
335 * On systems with little memory this may present an unnecessary constraint,
336 * so eet_clearcache() is available for users to reclaim the memory used by
337 * files that are no longer needed. Those that were open using
338 * ::EET_FILE_MODE_WRITE or ::EET_FILE_MODE_READ_WRITE and have modifications,
339 * will be written down to disk before flushing them from memory.
340 *
341 * @since 1.0.0
342 * @ingroup Eet_Group
343 */
344EAPI void
345eet_clearcache(void);
346
347/**
348 * @defgroup Eet_File_Group Eet File Main Functions
349 *
350 * Functions to create, destroy and do basic manipulation of
351 * #Eet_File handles.
352 *
353 * This sections explains how to use the most basic Eet functions, which
354 * are used to work with eet files, read data from them, store it back in or
355 * take a look at what entries it contains, without making use of the
356 * serialization capabilities explained in @ref Eet_Data_Group.
357 *
358 * The following example will serve as an introduction to most, if not all,
359 * of these functions.
360 *
361 * If you are only using Eet, this is the only header you need to include.
362 * @dontinclude eet-file.c
363 * @skipline Eet.h
364 *
365 * Now let's create ourselves an eet file to play with. The following function
366 * shows step by step how to open a file and write some data in it.
367 * First, we define our file handler and some other things we'll put in it.
368 * @line static int
369 * @skip Eet_File
370 * @until ";
371 * @skip eet_open
372 *
373 * We open a new file in write mode, and if it fails, we just return, since
374 * there's not much more we can do about it..
375 * @until return
376 *
377 * Now, we need to write some data in our file. For now, strings will suffice,
378 * so let's just dump a bunch of them in there.
379 * @until }
380 *
381 * As you can see, we copied a string into our static buffer, which is a bit
382 * bigger than the full length of the string, and then told Eet to write it
383 * into the file, compressed, returning the size of the data written into the
384 * file.
385 * This is all to show that Eet treats data as just data. It doesn't matter
386 * what that data represents (for now), it's all just bytes for it. As running
387 * the following code will show, we took a string of around 30 bytes and put it
388 * in a buffer of 1024 bytes, but the returned size won't be any of those.
389 * @until printf
390 *
391 * Next, we copy into our buffer our set of strings, including their null
392 * terminators and write them into the file. No error checking for the sake
393 * of brevity. And a call to eet_sync() to make sure all out data is
394 * properly written down to disk, even though we haven't yet closed the file.
395 * @until eet_sync
396 *
397 * One more write, this time our large array of binary data and... well, I
398 * couldn't come up with a valid use of the last set of strings we stored,
399 * so let's take it out from the file with eet_delete().
400 * @until eet_delete
401 *
402 * Finally, we close the file, saving any changes back to disk and return.
403 * Notice how, if there's any error closing the file or saving its contents,
404 * the return value from the function will be a false one, which later on
405 * will make the program exit with an error code.
406 * @until return
407 *
408 * Moving onto our main function, we will open the same file and read it back.
409 * Trivial, but it'll show how we can do so in more than one way. We'll skip
410 * the variable declarations, as they aren't very different from what we've
411 * seen already.
412 *
413 * We start from the beginning by initializing Eet so things in general work.
414 * Forgetting to do so will result in weird results or crashes when calling
415 * any eet function, so if you experience something like that, the first thing
416 * to look at is whether eet_init() is missing.
417 * Then we call our @p create_eet_file function, described above, to make
418 * sure we have something to work with. If the function fails it will return
419 * 0 and we just exit, since nothing from here onwards will work anyway.
420 * @skip eet_init
421 * @until return
422 *
423 * Let's take a look now at what entries our file has. For this, we use
424 * eet_list(), which will return a list of strings, each being the name of
425 * one entry. Since we skipped before, it may be worth noting that @p list
426 * is declared as a @p char **.
427 * The @p num parameter will, of course, have the number of entries contained
428 * in our file.
429 * If everything's fine, we'll get our list and print it to the screen, and
430 * once done with it, we free the list. That's just the list, not its contents,
431 * as they are internal strings used by Eet and trying to free them will surely
432 * break things.
433 * @until }
434 *
435 * Reading back plain data is simple. Just a call to eet_read() with the file
436 * to read from, and the name of the entry we are interested in. We get back
437 * our data and the passed @p size parameter will contain the size of it. If
438 * the data was stored compressed, it will decompressed first.
439 * @until }
440 *
441 * Another simple read for the set of strings from before, except those were
442 * deleted, so we should get a NULL return and continue normally.
443 * @until }
444 *
445 * Finally, we'll get our binary data in the same way we got the strings. Once
446 * again, it makes no difference for Eet what the data is, it's up to us to
447 * know how to handle it.
448 * @until {
449 *
450 * Now some cheating, we know that this data is an Eet file because, well...
451 * we just know it. So we are going to open it and take a look at its insides.
452 * For this, eet_open() won't work, as it needs to have a file on disk to read
453 * from and all we have is some data in RAM.
454 *
455 * So how do we do? One way would be to create a normal file and write down
456 * our data, then open it with eet_open(). Another, faster and more efficient
457 * if all we want to do is read the file, is to use eet_memopen_read().
458 * @until memopen
459 *
460 * As you can see, the size we got from our previous read was put to good use
461 * this time. Unlike the first one where all we had were strings, the size
462 * of the data read only serves to demonstrate that we are reading back the
463 * entire size of our original @p buf variable.
464 *
465 * A little peeking to see how many entries the file has and to make an
466 * example of eet_num_entries() to get that number when we don't care about
467 * their names.
468 * @until printf
469 *
470 * More cheating follows. Just like we knew this was an Eet file, we also know
471 * what key to read from, and ontop of that we know that the data in it is not
472 * compressed.
473 * Knowing all this allows us to take some shortcuts.
474 * @until read_direct
475 *
476 * That's a direct print of our data, whatever that data is. We don't want
477 * to worry about having to free it later, so we just used eet_direct_read()
478 * to tell Eet to gives a pointer to the internal data in the file, without
479 * duplicating it. Since we said that data was not compressed, we shouldn't
480 * worry about printing garbage to the screen (and yes, we also know the data
481 * is yet another string).
482 * We also don't care about the size of the data as it was stored in the file,
483 * so we passed NULL as the size parameter.
484 * One very important note about this, however, is that we don't care about
485 * the size parameter because the data in the file contains the null
486 * terminator for the string. So when using Eet to store strings this way,
487 * it's very important to consider whether you will keep that final null
488 * byte, or to always get the size read and do the necessary checks and copies.
489 * It's up to the user and the particular use cases to decide how this will
490 * be done.
491 *
492 * With everything done, close this second file and free the data used to open
493 * it. And this is important, we can't free that data until we are done with
494 * the file, as Eet is using it. When opening with eet_memopen_read(), the data
495 * passed to it must be available for as long as the the file is open.
496 * @until }
497 *
498 * Finally, we close the first file, shutdown all internal resources used by
499 * Eet and leave our main function, thus terminating our program.
500 * @until return
501 *
502 * You can look at the full code of the example @ref eet-file.c "here".
503 * @{
504 */
505
506/**
507 * @enum _Eet_File_Mode
508 * Modes that a file can be opened.
509 */
510typedef enum _Eet_File_Mode
511{
512 EET_FILE_MODE_INVALID = -1,
513 EET_FILE_MODE_READ, /**< File is read-only. */
514 EET_FILE_MODE_WRITE, /**< File is write-only. */
515 EET_FILE_MODE_READ_WRITE /**< File is for both read and write */
516} Eet_File_Mode; /**< Modes that a file can be opened. */
517
518/**
519 * @typedef Eet_File
520 * Opaque handle that defines an Eet file (or memory).
521 *
522 * This handle will be returned by the functions eet_open() and
523 * eet_memopen_read() and is used by every other function that affects the
524 * file in any way. When you are done with it, call eet_close() to close it
525 * and, if the file was open for writing, write down to disk any changes made
526 * to it.
527 *
528 * @see eet_open()
529 * @see eet_memopen_read()
530 * @see eet_close()
531 */
532typedef struct _Eet_File Eet_File;
533
534/**
535 * @typedef Eet_Dictionary
536 * Opaque handle that defines a file-backed (mmaped) dictionary of strings.
537 */
538typedef struct _Eet_Dictionary Eet_Dictionary;
539
540/**
541 * @}
542 */
543
544/**
545 * Open an eet file on disk, and returns a handle to it.
546 * @param file The file path to the eet file. eg: @c "/tmp/file.eet".
547 * @param mode The mode for opening. Either #EET_FILE_MODE_READ,
548 * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE.
549 * @return An opened eet file handle.
550 * @ingroup Eet_File_Group
551 *
552 * This function will open an exiting eet file for reading, and build
553 * the directory table in memory and return a handle to the file, if it
554 * exists and can be read, and no memory errors occur on the way, otherwise
555 * NULL will be returned.
556 *
557 * It will also open an eet file for writing. This will, if successful,
558 * delete the original file and replace it with a new empty file, till
559 * the eet file handle is closed or flushed. If it cannot be opened for
560 * writing or a memory error occurs, NULL is returned.
561 *
562 * You can also open the file for read/write. If you then write a key that
563 * does not exist it will be created, if the key exists it will be replaced
564 * by the new data.
565 *
566 * If the same file is opened multiple times, then the same file handle will
567 * be returned as eet maintains an internal list of all currently open
568 * files. Note that it considers files opened for read only and those opened
569 * for read/write and write only as 2 separate sets. Those that do not write
570 * to the file and those that do. Eet will allow 2 handles to the same file
571 * if they are in the 2 separate lists/groups. That means opening a file for
572 * read only looks in the read only set, and returns a handle to that file
573 * handle and increments its reference count. If you open a file for read/write
574 * or write only it looks in the write set and returns a handle after
575 * incrementing the reference count. You need to close an eet file handle
576 * as many times as it has been opened to maintain correct reference counts.
577 * Files whose modified timestamp or size do not match those of the existing
578 * referenced file handles will not be returned and a new handle will be
579 * returned instead.
580 *
581 * @since 1.0.0
582 */
583EAPI Eet_File *
584eet_open(const char *file,
585 Eet_File_Mode mode);
586
587/**
588 * Open an eet file directly from a memory location. The data is not copied,
589 * so you must keep it around as long as the eet file is open. There is
590 * currently no cache for this kind of Eet_File, so it's reopened every time
591 * you use eet_memopen_read.
592 * @param data Address of file in memory.
593 * @param size Size of memory to be read.
594 * @return A handle to the file.
595 *
596 * Files opened this way will always be in read-only mode.
597 *
598 * @since 1.1.0
599 * @ingroup Eet_File_Group
600 */
601EAPI Eet_File *
602eet_memopen_read(const void *data,
603 size_t size);
604
605/**
606 * Get the mode an Eet_File was opened with.
607 * @param ef A valid eet file handle.
608 * @return The mode ef was opened with.
609 *
610 * @since 1.0.0
611 * @ingroup Eet_File_Group
612 */
613EAPI Eet_File_Mode
614eet_mode_get(Eet_File *ef);
615
616/**
617 * Close an eet file handle and flush pending writes.
618 * @param ef A valid eet file handle.
619 * @return An eet error identifier.
620 *
621 * This function will flush any pending writes to disk if the eet file
622 * was opened for write, and free all data associated with the file handle
623 * and file, and close the file. If it was opened for read (or read/write),
624 * the file handle may still be held open internally for caching purposes.
625 * To flush speculatively held eet file handles use eet_clearcache().
626 *
627 * If the eet file handle is not valid nothing will be done.
628 *
629 * @since 1.0.0
630 * @ingroup Eet_File_Group
631 *
632 * @see eet_clearcache()
633 */
634EAPI Eet_Error
635eet_close(Eet_File *ef);
636
637/**
638 * Sync content of an eet file handle, flushing pending writes.
639 * @param ef A valid eet file handle.
640 * @return An eet error identifier.
641 *
642 * This function will flush any pending writes to disk. The eet file must
643 * be opened for write.
644 *
645 * If the eet file handle is not valid nothing will be done.
646 *
647 * @since 1.2.4
648 * @ingroup Eet_File_Group
649 */
650EAPI Eet_Error
651eet_sync(Eet_File *ef);
652
653/**
654 * Return a handle to the shared string dictionary of the Eet file
655 * @param ef A valid eet file handle.
656 * @return A handle to the dictionary of the file
657 *
658 * This function returns a handle to the dictionary of an Eet file whose
659 * handle is @p ef, if a dictionary exists. NULL is returned otherwise or
660 * if the file handle is known to be invalid.
661 *
662 * @see eet_dictionary_string_check() to know if given string came
663 * from the dictionary or it was dynamically allocated using
664 * the #Eet_Data_Descriptor_Class instructions.
665 *
666 * @since 1.0.0
667 * @ingroup Eet_File_Group
668 */
669EAPI Eet_Dictionary *
670eet_dictionary_get(Eet_File *ef);
671
672/**
673 * Check if a given string comes from a given dictionary
674 * @param ed A valid dictionary handle
675 * @param string A valid 0 byte terminated C string
676 * @return 1 if it is in the dictionary, 0 otherwise
677 *
678 * This checks the given dictionary to see if the given string is actually
679 * inside that dictionary (i.e. comes from it) and returns 1 if it does.
680 * If the dictionary handle is invalid, the string is NULL or the string is
681 * not in the dictionary, 0 is returned.
682 *
683 * @since 1.0.0
684 * @ingroup Eet_File_Group
685 */
686EAPI int
687eet_dictionary_string_check(Eet_Dictionary *ed,
688 const char *string);
689
690/**
691 * Return the number of strings inside a dictionary
692 * @param ed A valid dictionary handle
693 * @return the number of strings inside a dictionary
694 *
695 * @since 1.6.0
696 * @ingroup Eet_File_Group
697 */
698EAPI int
699eet_dictionary_count(const Eet_Dictionary *ed);
700
701/**
702 * Read a specified entry from an eet file and return data
703 * @param ef A valid eet file handle opened for reading.
704 * @param name Name of the entry. eg: "/base/file_i_want".
705 * @param size_ret Number of bytes read from entry and returned.
706 * @return The data stored in that entry in the eet file.
707 *
708 * This function finds an entry in the eet file that is stored under the
709 * name specified, and returns that data, decompressed, if successful.
710 * NULL is returned if the lookup fails or if memory errors are
711 * encountered. It is the job of the calling program to call free() on
712 * the returned data. The number of bytes in the returned data chunk are
713 * placed in size_ret.
714 *
715 * If the eet file handle is not valid NULL is returned and size_ret is
716 * filled with 0.
717 *
718 * @see eet_read_cipher()
719 *
720 * @since 1.0.0
721 * @ingroup Eet_File_Group
722 */
723EAPI void *
724eet_read(Eet_File *ef,
725 const char *name,
726 int *size_ret);
727
728/**
729 * Read a specified entry from an eet file and return data
730 * @param ef A valid eet file handle opened for reading.
731 * @param name Name of the entry. eg: "/base/file_i_want".
732 * @param size_ret Number of bytes read from entry and returned.
733 * @return The data stored in that entry in the eet file.
734 *
735 * This function finds an entry in the eet file that is stored under the
736 * name specified, and returns that data if not compressed and successful.
737 * NULL is returned if the lookup fails or if memory errors are
738 * encountered or if the data is compressed. The calling program must never
739 * call free() on the returned data. The number of bytes in the returned
740 * data chunk are placed in size_ret.
741 *
742 * If the eet file handle is not valid NULL is returned and size_ret is
743 * filled with 0.
744 *
745 * @since 1.0.0
746 * @ingroup Eet_File_Group
747 */
748EAPI const void *
749eet_read_direct(Eet_File *ef,
750 const char *name,
751 int *size_ret);
752
753/**
754 * Write a specified entry to an eet file handle
755 * @param ef A valid eet file handle opened for writing.
756 * @param name Name of the entry. eg: "/base/file_i_want".
757 * @param data Pointer to the data to be stored.
758 * @param size Length in bytes in the data to be stored.
759 * @param compress Compression flags (1 == compress, 0 = don't compress).
760 * @return bytes written on successful write, 0 on failure.
761 *
762 * This function will write the specified chunk of data to the eet file
763 * and return greater than 0 on success. 0 will be returned on failure.
764 *
765 * The eet file handle must be a valid file handle for an eet file opened
766 * for writing. If it is not, 0 will be returned and no action will be
767 * performed.
768 *
769 * Name, and data must not be NULL, and size must be > 0. If these
770 * conditions are not met, 0 will be returned.
771 *
772 * The data will be copied (and optionally compressed) in ram, pending
773 * a flush to disk (it will stay in ram till the eet file handle is
774 * closed though).
775 *
776 * @see eet_write_cipher()
777 *
778 * @since 1.0.0
779 * @ingroup Eet_File_Group
780 */
781EAPI int
782eet_write(Eet_File *ef,
783 const char *name,
784 const void *data,
785 int size,
786 int compress);
787
788/**
789 * Delete a specified entry from an Eet file being written or re-written
790 * @param ef A valid eet file handle opened for writing.
791 * @param name Name of the entry. eg: "/base/file_i_want".
792 * @return Success or failure of the delete.
793 *
794 * This function will delete the specified chunk of data from the eet file
795 * and return greater than 0 on success. 0 will be returned on failure.
796 *
797 * The eet file handle must be a valid file handle for an eet file opened
798 * for writing. If it is not, 0 will be returned and no action will be
799 * performed.
800 *
801 * Name, must not be NULL, otherwise 0 will be returned.
802 *
803 * @since 1.0.0
804 * @ingroup Eet_File_Group
805 */
806EAPI int
807eet_delete(Eet_File *ef,
808 const char *name);
809
810/**
811 * Alias a specific section to another one. Destination may exist or not,
812 * no checks are done.
813 * @param ef A valid eet file handle opened for writing.
814 * @param name Name of the new entry. eg: "/base/file_i_want".
815 * @param destination Actual source of the aliased entry eg: "/base/the_real_stuff_i_want".
816 * @param compress Compression flags (1 == compress, 0 = don't compress).
817 * @return EINA_TRUE on success, EINA_FALSE on failure.
818 *
819 * Name and Destination must not be NULL, otherwise EINA_FALSE will be returned.
820 * The equivalent of this would be calling 'ln -s destination name'
821 *
822 * @since 1.3.3
823 * @ingroup Eet_File_Group
824 */
825EAPI Eina_Bool
826eet_alias(Eet_File *ef,
827 const char *name,
828 const char *destination,
829 int compress);
830
831/**
832 * Retrieve the filename of an Eet_File
833 * @param ef A valid eet file handle opened for writing.
834 * @return The stringshared file string opened with eet_open(), or NULL on error
835 *
836 * @note This function will return NULL for files opened with eet_memopen_read()
837 *
838 * @since 1.6
839 * @ingroup Eet_File_Group
840 */
841EAPI const char *
842eet_file_get(Eet_File *ef);
843
844/**
845 * Retrieve the destination name of an alias
846 * @param ef A valid eet file handle opened for writing
847 * @param name Name of the entry. eg: "/base/file_i_want"
848 * @return Destination of the alias. eg: "/base/the_real_stuff_i_want", NULL on failure
849 *
850 * Name must not be NULL, otherwise NULL will be returned.
851 *
852 * @since 1.5
853 * @ingroup Eet_File_Group
854 */
855EAPI const char *
856eet_alias_get(Eet_File *ef,
857 const char *name);
858
859/**
860 * List all entries in eet file matching shell glob.
861 * @param ef A valid eet file handle.
862 * @param glob A shell glob to match against.
863 * @param count_ret Number of entries found to match.
864 * @return Pointer to an array of strings.
865 *
866 * This function will list all entries in the eet file matching the
867 * supplied shell glob and return an allocated list of their names, if
868 * there are any, and if no memory errors occur.
869 *
870 * The eet file handle must be valid and glob must not be NULL, or NULL
871 * will be returned and count_ret will be filled with 0.
872 *
873 * The calling program must call free() on the array returned, but NOT
874 * on the string pointers in the array. They are taken as read-only
875 * internals from the eet file handle. They are only valid as long as
876 * the file handle is not closed. When it is closed those pointers in the
877 * array are now not valid and should not be used.
878 *
879 * On success the array returned will have a list of string pointers
880 * that are the names of the entries that matched, and count_ret will have
881 * the number of entries in this array placed in it.
882 *
883 * Hint: an easy way to list all entries in an eet file is to use a glob
884 * value of "*".
885 *
886 * @since 1.0.0
887 * @ingroup Eet_File_Group
888 */
889EAPI char **
890eet_list(Eet_File *ef,
891 const char *glob,
892 int *count_ret);
893
894/**
895 * Return the number of entries in the specified eet file.
896 * @param ef A valid eet file handle.
897 * @return Number of entries in ef or -1 if the number of entries
898 * cannot be read due to open mode restrictions.
899 *
900 * @since 1.0.0
901 * @ingroup Eet_File_Group
902 */
903EAPI int
904eet_num_entries(Eet_File *ef);
905
906/**
907 * @defgroup Eet_File_Cipher_Group Eet File Ciphered Main Functions
908 *
909 * Most of the @ref Eet_File_Group have alternative versions that
910 * accounts for ciphers to protect their content.
911 *
912 * @see @ref Eet_Cipher_Group
913 *
914 * @ingroup Eet_File_Group
915 */
916
917/**
918 * Read a specified entry from an eet file and return data using a cipher.
919 * @param ef A valid eet file handle opened for reading.
920 * @param name Name of the entry. eg: "/base/file_i_want".
921 * @param size_ret Number of bytes read from entry and returned.
922 * @param cipher_key The key to use as cipher.
923 * @return The data stored in that entry in the eet file.
924 *
925 * This function finds an entry in the eet file that is stored under the
926 * name specified, and returns that data, decompressed, if successful.
927 * NULL is returned if the lookup fails or if memory errors are
928 * encountered. It is the job of the calling program to call free() on
929 * the returned data. The number of bytes in the returned data chunk are
930 * placed in size_ret.
931 *
932 * If the eet file handle is not valid NULL is returned and size_ret is
933 * filled with 0.
934 *
935 * @see eet_read()
936 *
937 * @since 1.0.0
938 * @ingroup Eet_File_Cipher_Group
939 */
940EAPI void *
941eet_read_cipher(Eet_File *ef,
942 const char *name,
943 int *size_ret,
944 const char *cipher_key);
945
946/**
947 * Write a specified entry to an eet file handle using a cipher.
948 * @param ef A valid eet file handle opened for writing.
949 * @param name Name of the entry. eg: "/base/file_i_want".
950 * @param data Pointer to the data to be stored.
951 * @param size Length in bytes in the data to be stored.
952 * @param compress Compression flags (1 == compress, 0 = don't compress).
953 * @param cipher_key The key to use as cipher.
954 * @return bytes written on successful write, 0 on failure.
955 *
956 * This function will write the specified chunk of data to the eet file
957 * and return greater than 0 on success. 0 will be returned on failure.
958 *
959 * The eet file handle must be a valid file handle for an eet file opened
960 * for writing. If it is not, 0 will be returned and no action will be
961 * performed.
962 *
963 * Name, and data must not be NULL, and size must be > 0. If these
964 * conditions are not met, 0 will be returned.
965 *
966 * The data will be copied (and optionally compressed) in ram, pending
967 * a flush to disk (it will stay in ram till the eet file handle is
968 * closed though).
969 *
970 * @see eet_write()
971 *
972 * @since 1.0.0
973 * @ingroup Eet_File_Cipher_Group
974 */
975EAPI int
976eet_write_cipher(Eet_File *ef,
977 const char *name,
978 const void *data,
979 int size,
980 int compress,
981 const char *cipher_key);
982
983/**
984 * @defgroup Eet_File_Image_Group Image Store and Load
985 *
986 * Eet efficiently stores and loads images, including alpha
987 * channels and lossy compressions.
988 *
989 * Eet can handle both lossy compression with different levels of quality and
990 * non-lossy compression with different compression levels. It's also possible,
991 * given an image data, to only read its header to get the image information
992 * without decoding the entire content for it.
993 *
994 * The encode family of functions will take an image raw buffer and its
995 * parameters and compress it in memory, returning the new buffer.
996 * Likewise, the decode functions will read from the given location in memory
997 * and return the uncompressed image.
998 *
999 * The read and write functions will, respectively, encode and decode to or
1000 * from an Eet file, under the specified key.
1001 *
1002 * These functions are fairly low level and the same functionality can be
1003 * achieved using Evas and Edje, making it much easier to work with images
1004 * as well as not needing to worry about things like scaling them.
1005 */
1006
1007/**
1008 * Read just the header data for an image and dont decode the pixels.
1009 * @param ef A valid eet file handle opened for reading.
1010 * @param name Name of the entry. eg: "/base/file_i_want".
1011 * @param w A pointer to the unsigned int to hold the width in pixels.
1012 * @param h A pointer to the unsigned int to hold the height in pixels.
1013 * @param alpha A pointer to the int to hold the alpha flag.
1014 * @param compress A pointer to the int to hold the compression amount.
1015 * @param quality A pointer to the int to hold the quality amount.
1016 * @param lossy A pointer to the int to hold the lossiness flag.
1017 * @return 1 on successful decode, 0 otherwise
1018 *
1019 * Reads and decodes the image header data stored under the given key and
1020 * Eet file.
1021 *
1022 * The information decoded is placed in each of the parameters, which must be
1023 * provided. The width and height, measured in pixels, will be stored under
1024 * the variables pointed by @p w and @p h, respectively. If the read or
1025 * decode of the header fails, this values will be 0. The @p alpha parameter
1026 * will be 1 or 0, denoting if the alpha channel of the image is used or not.
1027 * If the image was losslessly compressed, the @p compress parameter will hold
1028 * the compression amount used, ranging from 0 to 9 and @p lossy will be 0.
1029 * In the case of lossy compression, @p lossy will be 1, and the compression
1030 * quality will be placed under @p quality, with a value ranging from 0 to 100.
1031 *
1032 * @see eet_data_image_header_decode()
1033 * @see eet_data_image_header_read_cipher()
1034 *
1035 * @since 1.0.0
1036 * @ingroup Eet_File_Image_Group
1037 */
1038EAPI int
1039eet_data_image_header_read(Eet_File *ef,
1040 const char *name,
1041 unsigned int *w,
1042 unsigned int *h,
1043 int *alpha,
1044 int *compress,
1045 int *quality,
1046 int *lossy);
1047
1048/**
1049 * Read image data from the named key in the eet file.
1050 * @param ef A valid eet file handle opened for reading.
1051 * @param name Name of the entry. eg: "/base/file_i_want".
1052 * @param w A pointer to the unsigned int to hold the width in pixels.
1053 * @param h A pointer to the unsigned int to hold the height in pixels.
1054 * @param alpha A pointer to the int to hold the alpha flag.
1055 * @param compress A pointer to the int to hold the compression amount.
1056 * @param quality A pointer to the int to hold the quality amount.
1057 * @param lossy A pointer to the int to hold the lossiness flag.
1058 * @return The image pixel data decoded
1059 *
1060 * Reads and decodes the image stored in the given Eet file under the named
1061 * key.
1062 *
1063 * The returned pixel data is a linear array of pixels starting from the
1064 * top-left of the image, scanning row by row from left to right. Each pile
1065 * is a 32bit value, with the high byte being the alpha channel, the next being
1066 * red, then green, and the low byte being blue.
1067 *
1068 * The rest of the parameters are the same as in eet_data_image_header_read().
1069 *
1070 * On success the function returns a pointer to the image data decoded. The
1071 * calling application is responsible for calling free() on the image data
1072 * when it is done with it. On failure NULL is returned and the parameter
1073 * values may not contain any sensible data.
1074 *
1075 * @see eet_data_image_header_read()
1076 * @see eet_data_image_decode()
1077 * @see eet_data_image_read_cipher()
1078 * @see eet_data_image_read_to_surface()
1079 *
1080 * @since 1.0.0
1081 * @ingroup Eet_File_Image_Group
1082 */
1083EAPI void *
1084eet_data_image_read(Eet_File *ef,
1085 const char *name,
1086 unsigned int *w,
1087 unsigned int *h,
1088 int *alpha,
1089 int *compress,
1090 int *quality,
1091 int *lossy);
1092
1093/**
1094 * Read image data from the named key in the eet file and store it in the given buffer.
1095 * @param ef A valid eet file handle opened for reading.
1096 * @param name Name of the entry. eg: "/base/file_i_want".
1097 * @param src_x The starting x coordinate from where to dump the stream.
1098 * @param src_y The starting y coordinate from where to dump the stream.
1099 * @param d A pointer to the pixel surface.
1100 * @param w The expected width in pixels of the pixel surface to decode.
1101 * @param h The expected height in pixels of the pixel surface to decode.
1102 * @param row_stride The length of a pixels line in the destination surface.
1103 * @param alpha A pointer to the int to hold the alpha flag.
1104 * @param compress A pointer to the int to hold the compression amount.
1105 * @param quality A pointer to the int to hold the quality amount.
1106 * @param lossy A pointer to the int to hold the lossiness flag.
1107 * @return 1 on success, 0 otherwise.
1108 *
1109 * Reads and decodes the image stored in the given Eet file, placing the
1110 * resulting pixel data in the buffer pointed by the user.
1111 *
1112 * Like eet_data_image_read(), it takes the image data stored under the
1113 * @p name key in the @p ef file, but instead of returning a new buffer with
1114 * the pixel data, it places the result in the buffer pointed by @p d, which
1115 * must be provided by the user and of sufficient size to hold the requested
1116 * portion of the image.
1117 *
1118 * The @p src_x and @p src_y parameters indicate the top-left corner of the
1119 * section of the image to decode. These have to be higher or equal than 0 and
1120 * less than the respective total width and height of the image. The width
1121 * and height of the section of the image to decode are given in @p w and @p h
1122 * and also can't be higher than the total width and height of the image.
1123 *
1124 * The @p row_stride parameter indicates the length in bytes of each line in
1125 * the destination buffer and it has to be at least @p w * 4.
1126 *
1127 * All the other parameters are the same as in eet_data_image_read().
1128 *
1129 * On success the function returns 1, and 0 on failure. On failure the
1130 * parameter values may not contain any sensible data.
1131 *
1132 * @see eet_data_image_read()
1133 * @see eet_data_image_decode()
1134 * @see eet_data_image_decode_to_surface()
1135 * @see eet_data_image_read_to_surface_cipher()
1136 *
1137 * @since 1.0.2
1138 * @ingroup Eet_File_Image_Group
1139 */
1140EAPI int
1141eet_data_image_read_to_surface(Eet_File *ef,
1142 const char *name,
1143 unsigned int src_x,
1144 unsigned int src_y,
1145 unsigned int *d,
1146 unsigned int w,
1147 unsigned int h,
1148 unsigned int row_stride,
1149 int *alpha,
1150 int *compress,
1151 int *quality,
1152 int *lossy);
1153
1154/**
1155 * Write image data to the named key in an eet file.
1156 * @param ef A valid eet file handle opened for writing.
1157 * @param name Name of the entry. eg: "/base/file_i_want".
1158 * @param data A pointer to the image pixel data.
1159 * @param w The width of the image in pixels.
1160 * @param h The height of the image in pixels.
1161 * @param alpha The alpha channel flag.
1162 * @param compress The compression amount.
1163 * @param quality The quality encoding amount.
1164 * @param lossy The lossiness flag.
1165 * @return Success if the data was encoded and written or not.
1166 *
1167 * This function takes image pixel data and encodes it in an eet file
1168 * stored under the supplied name key, and returns how many bytes were
1169 * actually written to encode the image data.
1170 *
1171 * The data expected is the same format as returned by eet_data_image_read.
1172 * If this is not the case weird things may happen. Width and height must
1173 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1174 * the alpha values are not useful and 1 meaning they are). Compress can
1175 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1176 * This is only used if the image is not lossily encoded. Quality is used on
1177 * lossy compression and should be a value from 0 to 100. The lossy flag
1178 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1179 * image quality loss (but then have a much smaller encoding).
1180 *
1181 * On success this function returns the number of bytes that were required
1182 * to encode the image data, or on failure it returns 0.
1183 *
1184 * @see eet_data_image_read()
1185 * @see eet_data_image_encode()
1186 * @see eet_data_image_write_cipher()
1187 *
1188 * @since 1.0.0
1189 * @ingroup Eet_File_Image_Group
1190 */
1191EAPI int
1192eet_data_image_write(Eet_File *ef,
1193 const char *name,
1194 const void *data,
1195 unsigned int w,
1196 unsigned int h,
1197 int alpha,
1198 int compress,
1199 int quality,
1200 int lossy);
1201
1202/**
1203 * Decode Image data header only to get information.
1204 * @param data The encoded pixel data.
1205 * @param size The size, in bytes, of the encoded pixel data.
1206 * @param w A pointer to the unsigned int to hold the width in pixels.
1207 * @param h A pointer to the unsigned int to hold the height in pixels.
1208 * @param alpha A pointer to the int to hold the alpha flag.
1209 * @param compress A pointer to the int to hold the compression amount.
1210 * @param quality A pointer to the int to hold the quality amount.
1211 * @param lossy A pointer to the int to hold the lossiness flag.
1212 * @return 1 on success, 0 on failure.
1213 *
1214 * This function works exactly like eet_data_image_header_read(), but instead
1215 * of reading from an Eet file, it takes the buffer of size @p size pointed
1216 * by @p data, which must be a valid Eet encoded image.
1217 *
1218 * On success the function returns 1 indicating the header was read and
1219 * decoded properly, or 0 on failure.
1220 *
1221 * @see eet_data_image_header_read()
1222 * @see eet_data_image_header_decode_cipher()
1223 *
1224 * @since 1.0.0
1225 * @ingroup Eet_File_Image_Group
1226 */
1227EAPI int
1228eet_data_image_header_decode(const void *data,
1229 int size,
1230 unsigned int *w,
1231 unsigned int *h,
1232 int *alpha,
1233 int *compress,
1234 int *quality,
1235 int *lossy);
1236
1237/**
1238 * Decode Image data into pixel data.
1239 * @param data The encoded pixel data.
1240 * @param size The size, in bytes, of the encoded pixel data.
1241 * @param w A pointer to the unsigned int to hold the width in pixels.
1242 * @param h A pointer to the unsigned int to hold the height in pixels.
1243 * @param alpha A pointer to the int to hold the alpha flag.
1244 * @param compress A pointer to the int to hold the compression amount.
1245 * @param quality A pointer to the int to hold the quality amount.
1246 * @param lossy A pointer to the int to hold the lossiness flag.
1247 * @return The image pixel data decoded
1248 *
1249 * This function takes encoded pixel data and decodes it into raw RGBA
1250 * pixels on success.
1251 *
1252 * It works exactly like eet_data_image_read(), but it takes the encoded
1253 * data in the @p data buffer of size @p size, instead of reading from a file.
1254 * All the others parameters are also the same.
1255 *
1256 * On success the function returns a pointer to the image data decoded. The
1257 * calling application is responsible for calling free() on the image data
1258 * when it is done with it. On failure NULL is returned and the parameter
1259 * values may not contain any sensible data.
1260 *
1261 * @see eet_data_image_read()
1262 * @see eet_data_image_decode_cipher()
1263 *
1264 * @since 1.0.0
1265 * @ingroup Eet_File_Image_Group
1266 */
1267EAPI void *
1268eet_data_image_decode(const void *data,
1269 int size,
1270 unsigned int *w,
1271 unsigned int *h,
1272 int *alpha,
1273 int *compress,
1274 int *quality,
1275 int *lossy);
1276
1277/**
1278 * Decode Image data into pixel data and stores in the given buffer.
1279 * @param data The encoded pixel data.
1280 * @param size The size, in bytes, of the encoded pixel data.
1281 * @param src_x The starting x coordinate from where to dump the stream.
1282 * @param src_y The starting y coordinate from where to dump the stream.
1283 * @param d A pointer to the pixel surface.
1284 * @param w The expected width in pixels of the pixel surface to decode.
1285 * @param h The expected height in pixels of the pixel surface to decode.
1286 * @param row_stride The length of a pixels line in the destination surface.
1287 * @param alpha A pointer to the int to hold the alpha flag.
1288 * @param compress A pointer to the int to hold the compression amount.
1289 * @param quality A pointer to the int to hold the quality amount.
1290 * @param lossy A pointer to the int to hold the lossiness flag.
1291 * @return 1 on success, 0 otherwise.
1292 *
1293 * Like eet_data_image_read_to_surface(), but reading the given @p data buffer
1294 * instead of a file.
1295 *
1296 * On success the function returns 1, and 0 on failure. On failure the
1297 * parameter values may not contain any sensible data.
1298 *
1299 * @see eet_data_image_read_to_surface()
1300 * @see eet_data_image_decode_to_surface_cipher()
1301 *
1302 * @since 1.0.2
1303 * @ingroup Eet_File_Image_Group
1304 */
1305EAPI int
1306eet_data_image_decode_to_surface(const void *data,
1307 int size,
1308 unsigned int src_x,
1309 unsigned int src_y,
1310 unsigned int *d,
1311 unsigned int w,
1312 unsigned int h,
1313 unsigned int row_stride,
1314 int *alpha,
1315 int *compress,
1316 int *quality,
1317 int *lossy);
1318
1319/**
1320 * Encode image data for storage or transmission.
1321 * @param data A pointer to the image pixel data.
1322 * @param size_ret A pointer to an int to hold the size of the returned data.
1323 * @param w The width of the image in pixels.
1324 * @param h The height of the image in pixels.
1325 * @param alpha The alpha channel flag.
1326 * @param compress The compression amount.
1327 * @param quality The quality encoding amount.
1328 * @param lossy The lossiness flag.
1329 * @return The encoded image data.
1330 *
1331 * This function stakes image pixel data and encodes it with compression and
1332 * possible loss of quality (as a trade off for size) for storage or
1333 * transmission to another system.
1334 *
1335 * It works like eet_data_image_write(), but instead of writing the encoded
1336 * image into an Eet file, it allocates a new buffer of the size required and
1337 * returns the encoded data in it.
1338 *
1339 * On success this function returns a pointer to the encoded data that you
1340 * can free with free() when no longer needed.
1341 *
1342 * @see eet_data_image_write()
1343 * @see eet_data_image_read()
1344 * @see eet_data_image_encode_cipher()
1345 *
1346 * @since 1.0.0
1347 * @ingroup Eet_File_Image_Group
1348 */
1349EAPI void *
1350eet_data_image_encode(const void *data,
1351 int *size_ret,
1352 unsigned int w,
1353 unsigned int h,
1354 int alpha,
1355 int compress,
1356 int quality,
1357 int lossy);
1358
1359/**
1360 * @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Cipher
1361 *
1362 * Most of the @ref Eet_File_Image_Group have alternative versions
1363 * that accounts for ciphers to protect their content.
1364 *
1365 * @see @ref Eet_Cipher_Group
1366 *
1367 * @ingroup Eet_File_Image_Group
1368 */
1369
1370/**
1371 * Read just the header data for an image and dont decode the pixels using a cipher.
1372 * @param ef A valid eet file handle opened for reading.
1373 * @param name Name of the entry. eg: "/base/file_i_want".
1374 * @param cipher_key The key to use as cipher.
1375 * @param w A pointer to the unsigned int to hold the width in pixels.
1376 * @param h A pointer to the unsigned int to hold the height in pixels.
1377 * @param alpha A pointer to the int to hold the alpha flag.
1378 * @param compress A pointer to the int to hold the compression amount.
1379 * @param quality A pointer to the int to hold the quality amount.
1380 * @param lossy A pointer to the int to hold the lossiness flag.
1381 * @return 1 on successful decode, 0 otherwise
1382 *
1383 * This function reads an image from an eet file stored under the named
1384 * key in the eet file and return a pointer to the decompressed pixel data.
1385 *
1386 * The other parameters of the image (width, height etc.) are placed into
1387 * the values pointed to (they must be supplied). The pixel data is a linear
1388 * array of pixels starting from the top-left of the image scanning row by
1389 * row from left to right. Each pixel is a 32bit value, with the high byte
1390 * being the alpha channel, the next being red, then green, and the low byte
1391 * being blue. The width and height are measured in pixels and will be
1392 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1393 * that the alpha channel is not used. 1 denotes that it is significant.
1394 * Compress is filled with the compression value/amount the image was
1395 * stored with. The quality value is filled with the quality encoding of
1396 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1397 * the image was encoded lossily or not.
1398 *
1399 * On success the function returns 1 indicating the header was read and
1400 * decoded properly, or 0 on failure.
1401 *
1402 * @see eet_data_image_header_read()
1403 *
1404 * @since 1.0.0
1405 * @ingroup Eet_File_Image_Cipher_Group
1406 */
1407EAPI int
1408eet_data_image_header_read_cipher(Eet_File *ef,
1409 const char *name,
1410 const char *cipher_key,
1411 unsigned int *w,
1412 unsigned int *h,
1413 int *alpha,
1414 int *compress,
1415 int *quality,
1416 int *lossy);
1417
1418/**
1419 * Read image data from the named key in the eet file using a cipher.
1420 * @param ef A valid eet file handle opened for reading.
1421 * @param name Name of the entry. eg: "/base/file_i_want".
1422 * @param cipher_key The key to use as cipher.
1423 * @param w A pointer to the unsigned int to hold the width in pixels.
1424 * @param h A pointer to the unsigned int to hold the height in pixels.
1425 * @param alpha A pointer to the int to hold the alpha flag.
1426 * @param compress A pointer to the int to hold the compression amount.
1427 * @param quality A pointer to the int to hold the quality amount.
1428 * @param lossy A pointer to the int to hold the lossiness flag.
1429 * @return The image pixel data decoded
1430 *
1431 * This function reads an image from an eet file stored under the named
1432 * key in the eet file and return a pointer to the decompressed pixel data.
1433 *
1434 * The other parameters of the image (width, height etc.) are placed into
1435 * the values pointed to (they must be supplied). The pixel data is a linear
1436 * array of pixels starting from the top-left of the image scanning row by
1437 * row from left to right. Each pixel is a 32bit value, with the high byte
1438 * being the alpha channel, the next being red, then green, and the low byte
1439 * being blue. The width and height are measured in pixels and will be
1440 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1441 * that the alpha channel is not used. 1 denotes that it is significant.
1442 * Compress is filled with the compression value/amount the image was
1443 * stored with. The quality value is filled with the quality encoding of
1444 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1445 * the image was encoded lossily or not.
1446 *
1447 * On success the function returns a pointer to the image data decoded. The
1448 * calling application is responsible for calling free() on the image data
1449 * when it is done with it. On failure NULL is returned and the parameter
1450 * values may not contain any sensible data.
1451 *
1452 * @see eet_data_image_read()
1453 *
1454 * @since 1.0.0
1455 * @ingroup Eet_File_Image_Cipher_Group
1456 */
1457EAPI void *
1458eet_data_image_read_cipher(Eet_File *ef,
1459 const char *name,
1460 const char *cipher_key,
1461 unsigned int *w,
1462 unsigned int *h,
1463 int *alpha,
1464 int *compress,
1465 int *quality,
1466 int *lossy);
1467
1468/**
1469 * Read image data from the named key in the eet file using a cipher.
1470 * @param ef A valid eet file handle opened for reading.
1471 * @param name Name of the entry. eg: "/base/file_i_want".
1472 * @param cipher_key The key to use as cipher.
1473 * @param src_x The starting x coordinate from where to dump the stream.
1474 * @param src_y The starting y coordinate from where to dump the stream.
1475 * @param d A pointer to the pixel surface.
1476 * @param w The expected width in pixels of the pixel surface to decode.
1477 * @param h The expected height in pixels of the pixel surface to decode.
1478 * @param row_stride The length of a pixels line in the destination surface.
1479 * @param alpha A pointer to the int to hold the alpha flag.
1480 * @param compress A pointer to the int to hold the compression amount.
1481 * @param quality A pointer to the int to hold the quality amount.
1482 * @param lossy A pointer to the int to hold the lossiness flag.
1483 * @return 1 on success, 0 otherwise.
1484 *
1485 * This function reads an image from an eet file stored under the named
1486 * key in the eet file and return a pointer to the decompressed pixel data.
1487 *
1488 * The other parameters of the image (width, height etc.) are placed into
1489 * the values pointed to (they must be supplied). The pixel data is a linear
1490 * array of pixels starting from the top-left of the image scanning row by
1491 * row from left to right. Each pixel is a 32bit value, with the high byte
1492 * being the alpha channel, the next being red, then green, and the low byte
1493 * being blue. The width and height are measured in pixels and will be
1494 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1495 * that the alpha channel is not used. 1 denotes that it is significant.
1496 * Compress is filled with the compression value/amount the image was
1497 * stored with. The quality value is filled with the quality encoding of
1498 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1499 * the image was encoded lossily or not.
1500 *
1501 * On success the function returns 1, and 0 on failure. On failure the
1502 * parameter values may not contain any sensible data.
1503 *
1504 * @see eet_data_image_read_to_surface()
1505 *
1506 * @since 1.0.2
1507 * @ingroup Eet_File_Image_Cipher_Group
1508 */
1509EAPI int
1510eet_data_image_read_to_surface_cipher(Eet_File *ef,
1511 const char *name,
1512 const char *cipher_key,
1513 unsigned int src_x,
1514 unsigned int src_y,
1515 unsigned int *d,
1516 unsigned int w,
1517 unsigned int h,
1518 unsigned int row_stride,
1519 int *alpha,
1520 int *compress,
1521 int *quality,
1522 int *lossy);
1523
1524/**
1525 * Write image data to the named key in an eet file using a cipher.
1526 * @param ef A valid eet file handle opened for writing.
1527 * @param name Name of the entry. eg: "/base/file_i_want".
1528 * @param cipher_key The key to use as cipher.
1529 * @param data A pointer to the image pixel data.
1530 * @param w The width of the image in pixels.
1531 * @param h The height of the image in pixels.
1532 * @param alpha The alpha channel flag.
1533 * @param compress The compression amount.
1534 * @param quality The quality encoding amount.
1535 * @param lossy The lossiness flag.
1536 * @return Success if the data was encoded and written or not.
1537 *
1538 * This function takes image pixel data and encodes it in an eet file
1539 * stored under the supplied name key, and returns how many bytes were
1540 * actually written to encode the image data.
1541 *
1542 * The data expected is the same format as returned by eet_data_image_read.
1543 * If this is not the case weird things may happen. Width and height must
1544 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1545 * the alpha values are not useful and 1 meaning they are). Compress can
1546 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1547 * This is only used if the image is not lossily encoded. Quality is used on
1548 * lossy compression and should be a value from 0 to 100. The lossy flag
1549 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1550 * image quality loss (but then have a much smaller encoding).
1551 *
1552 * On success this function returns the number of bytes that were required
1553 * to encode the image data, or on failure it returns 0.
1554 *
1555 * @see eet_data_image_write()
1556 *
1557 * @since 1.0.0
1558 * @ingroup Eet_File_Image_Cipher_Group
1559 */
1560EAPI int
1561eet_data_image_write_cipher(Eet_File *ef,
1562 const char *name,
1563 const char *cipher_key,
1564 const void *data,
1565 unsigned int w,
1566 unsigned int h,
1567 int alpha,
1568 int compress,
1569 int quality,
1570 int lossy);
1571
1572/**
1573 * Decode Image data header only to get information using a cipher.
1574 * @param data The encoded pixel data.
1575 * @param cipher_key The key to use as cipher.
1576 * @param size The size, in bytes, of the encoded pixel data.
1577 * @param w A pointer to the unsigned int to hold the width in pixels.
1578 * @param h A pointer to the unsigned int to hold the height in pixels.
1579 * @param alpha A pointer to the int to hold the alpha flag.
1580 * @param compress A pointer to the int to hold the compression amount.
1581 * @param quality A pointer to the int to hold the quality amount.
1582 * @param lossy A pointer to the int to hold the lossiness flag.
1583 * @return 1 on success, 0 on failure.
1584 *
1585 * This function takes encoded pixel data and decodes it into raw RGBA
1586 * pixels on success.
1587 *
1588 * The other parameters of the image (width, height etc.) are placed into
1589 * the values pointed to (they must be supplied). The pixel data is a linear
1590 * array of pixels starting from the top-left of the image scanning row by
1591 * row from left to right. Each pixel is a 32bit value, with the high byte
1592 * being the alpha channel, the next being red, then green, and the low byte
1593 * being blue. The width and height are measured in pixels and will be
1594 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1595 * that the alpha channel is not used. 1 denotes that it is significant.
1596 * Compress is filled with the compression value/amount the image was
1597 * stored with. The quality value is filled with the quality encoding of
1598 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1599 * the image was encoded lossily or not.
1600 *
1601 * On success the function returns 1 indicating the header was read and
1602 * decoded properly, or 0 on failure.
1603 *
1604 * @see eet_data_image_header_decode()
1605 *
1606 * @since 1.0.0
1607 * @ingroup Eet_File_Image_Cipher_Group
1608 */
1609EAPI int
1610eet_data_image_header_decode_cipher(const void *data,
1611 const char *cipher_key,
1612 int size,
1613 unsigned int *w,
1614 unsigned int *h,
1615 int *alpha,
1616 int *compress,
1617 int *quality,
1618 int *lossy);
1619
1620/**
1621 * Decode Image data into pixel data using a cipher.
1622 * @param data The encoded pixel data.
1623 * @param cipher_key The key to use as cipher.
1624 * @param size The size, in bytes, of the encoded pixel data.
1625 * @param w A pointer to the unsigned int to hold the width in pixels.
1626 * @param h A pointer to the unsigned int to hold the height in pixels.
1627 * @param alpha A pointer to the int to hold the alpha flag.
1628 * @param compress A pointer to the int to hold the compression amount.
1629 * @param quality A pointer to the int to hold the quality amount.
1630 * @param lossy A pointer to the int to hold the lossiness flag.
1631 * @return The image pixel data decoded
1632 *
1633 * This function takes encoded pixel data and decodes it into raw RGBA
1634 * pixels on success.
1635 *
1636 * The other parameters of the image (width, height etc.) are placed into
1637 * the values pointed to (they must be supplied). The pixel data is a linear
1638 * array of pixels starting from the top-left of the image scanning row by
1639 * row from left to right. Each pixel is a 32bit value, with the high byte
1640 * being the alpha channel, the next being red, then green, and the low byte
1641 * being blue. The width and height are measured in pixels and will be
1642 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1643 * that the alpha channel is not used. 1 denotes that it is significant.
1644 * Compress is filled with the compression value/amount the image was
1645 * stored with. The quality value is filled with the quality encoding of
1646 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1647 * the image was encoded lossily or not.
1648 *
1649 * On success the function returns a pointer to the image data decoded. The
1650 * calling application is responsible for calling free() on the image data
1651 * when it is done with it. On failure NULL is returned and the parameter
1652 * values may not contain any sensible data.
1653 *
1654 * @see eet_data_image_decode()
1655 *
1656 * @since 1.0.0
1657 * @ingroup Eet_File_Image_Cipher_Group
1658 */
1659EAPI void *
1660eet_data_image_decode_cipher(const void *data,
1661 const char *cipher_key,
1662 int size,
1663 unsigned int *w,
1664 unsigned int *h,
1665 int *alpha,
1666 int *compress,
1667 int *quality,
1668 int *lossy);
1669
1670/**
1671 * Decode Image data into pixel data using a cipher.
1672 * @param data The encoded pixel data.
1673 * @param cipher_key The key to use as cipher.
1674 * @param size The size, in bytes, of the encoded pixel data.
1675 * @param src_x The starting x coordinate from where to dump the stream.
1676 * @param src_y The starting y coordinate from where to dump the stream.
1677 * @param d A pointer to the pixel surface.
1678 * @param w The expected width in pixels of the pixel surface to decode.
1679 * @param h The expected height in pixels of the pixel surface to decode.
1680 * @param row_stride The length of a pixels line in the destination surface.
1681 * @param alpha A pointer to the int to hold the alpha flag.
1682 * @param compress A pointer to the int to hold the compression amount.
1683 * @param quality A pointer to the int to hold the quality amount.
1684 * @param lossy A pointer to the int to hold the lossiness flag.
1685 * @return 1 on success, 0 otherwise.
1686 *
1687 * This function takes encoded pixel data and decodes it into raw RGBA
1688 * pixels on success.
1689 *
1690 * The other parameters of the image (alpha, compress etc.) are placed into
1691 * the values pointed to (they must be supplied). The pixel data is a linear
1692 * array of pixels starting from the top-left of the image scanning row by
1693 * row from left to right. Each pixel is a 32bit value, with the high byte
1694 * being the alpha channel, the next being red, then green, and the low byte
1695 * being blue. The width and height are measured in pixels and will be
1696 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
1697 * that the alpha channel is not used. 1 denotes that it is significant.
1698 * Compress is filled with the compression value/amount the image was
1699 * stored with. The quality value is filled with the quality encoding of
1700 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
1701 * the image was encoded lossily or not.
1702 *
1703 * On success the function returns 1, and 0 on failure. On failure the
1704 * parameter values may not contain any sensible data.
1705 *
1706 * @see eet_data_image_decode_to_surface()
1707 *
1708 * @since 1.0.2
1709 * @ingroup Eet_File_Image_Cipher_Group
1710 */
1711EAPI int
1712eet_data_image_decode_to_surface_cipher(const void *data,
1713 const char *cipher_key,
1714 int size,
1715 unsigned int src_x,
1716 unsigned int src_y,
1717 unsigned int *d,
1718 unsigned int w,
1719 unsigned int h,
1720 unsigned int row_stride,
1721 int *alpha,
1722 int *compress,
1723 int *quality,
1724 int *lossy);
1725
1726/**
1727 * Encode image data for storage or transmission using a cipher.
1728 * @param data A pointer to the image pixel data.
1729 * @param cipher_key The key to use as cipher.
1730 * @param size_ret A pointer to an int to hold the size of the returned data.
1731 * @param w The width of the image in pixels.
1732 * @param h The height of the image in pixels.
1733 * @param alpha The alpha channel flag.
1734 * @param compress The compression amount.
1735 * @param quality The quality encoding amount.
1736 * @param lossy The lossiness flag.
1737 * @return The encoded image data.
1738 *
1739 * This function stakes image pixel data and encodes it with compression and
1740 * possible loss of quality (as a trade off for size) for storage or
1741 * transmission to another system.
1742 *
1743 * The data expected is the same format as returned by eet_data_image_read.
1744 * If this is not the case weird things may happen. Width and height must
1745 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
1746 * the alpha values are not useful and 1 meaning they are). Compress can
1747 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
1748 * This is only used if the image is not lossily encoded. Quality is used on
1749 * lossy compression and should be a value from 0 to 100. The lossy flag
1750 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
1751 * image quality loss (but then have a much smaller encoding).
1752 *
1753 * On success this function returns a pointer to the encoded data that you
1754 * can free with free() when no longer needed.
1755 *
1756 * @see eet_data_image_encode()
1757 *
1758 * @since 1.0.0
1759 * @ingroup Eet_File_Image_Cipher_Group
1760 */
1761EAPI void *
1762eet_data_image_encode_cipher(const void *data,
1763 const char *cipher_key,
1764 unsigned int w,
1765 unsigned int h,
1766 int alpha,
1767 int compress,
1768 int quality,
1769 int lossy,
1770 int *size_ret);
1771
1772/**
1773 * @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms
1774 *
1775 * Eet allows one to protect entries of an #Eet_File
1776 * individually. This may be used to ensure data was not tampered or
1777 * that third party does not read your data.
1778 *
1779 * @see @ref Eet_File_Cipher_Group
1780 * @see @ref Eet_File_Image_Cipher_Group
1781 *
1782 * @{
1783 */
1784
1785/**
1786 * @typedef Eet_Key
1787 * Opaque handle that defines an identity (also known as key)
1788 * in Eet's cipher system.
1789 */
1790typedef struct _Eet_Key Eet_Key;
1791
1792/**
1793 * @}
1794 */
1795
1796/**
1797 * Callback used to request if needed the password of a private key.
1798 *
1799 * @param buffer the buffer where to store the password.
1800 * @param size the maximum password size (size of buffer, including '@\0').
1801 * @param rwflag if the buffer is also readable or just writable.
1802 * @param data currently unused, may contain some context in future.
1803 * @return 1 on success and password was set to @p buffer, 0 on failure.
1804 *
1805 * @since 1.2.0
1806 * @ingroup Eet_Cipher_Group
1807 */
1808typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data);
1809
1810/**
1811 * Create an Eet_Key needed for signing an eet file.
1812 *
1813 * The certificate should provide the public that match the private key.
1814 * No verification is done to ensure that.
1815 *
1816 * @param certificate_file The file where to find the certificate.
1817 * @param private_key_file The file that contains the private key.
1818 * @param cb Function to callback if password is required to unlock
1819 * private key.
1820 * @return A key handle to use, or @c NULL on failure.
1821 *
1822 * @see eet_identity_close()
1823 *
1824 * @since 1.2.0
1825 * @ingroup Eet_Cipher_Group
1826 */
1827EAPI Eet_Key *
1828eet_identity_open(const char *certificate_file,
1829 const char *private_key_file,
1830 Eet_Key_Password_Callback cb);
1831
1832/**
1833 * Close and release all resource used by an Eet_Key. An
1834 * reference counter prevent it from being freed until all file
1835 * using it are also closed.
1836 *
1837 * @param key the key handle to close and free resources.
1838 *
1839 * @since 1.2.0
1840 * @ingroup Eet_Cipher_Group
1841 */
1842EAPI void
1843eet_identity_close(Eet_Key *key);
1844
1845/**
1846 * Set a key to sign a file
1847 *
1848 * @param ef the file to set the identity.
1849 * @param key the key handle to set as identity.
1850 * @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or
1851 * #EET_ERROR_NONE on success.
1852 *
1853 * @since 1.2.0
1854 * @ingroup Eet_Cipher_Group
1855 */
1856EAPI Eet_Error
1857eet_identity_set(Eet_File *ef,
1858 Eet_Key *key);
1859
1860/**
1861 * Display both private and public key of an Eet_Key.
1862 *
1863 * @param key the handle to print.
1864 * @param out where to print.
1865 *
1866 * @since 1.2.0
1867 * @ingroup Eet_Cipher_Group
1868 */
1869EAPI void
1870eet_identity_print(Eet_Key *key,
1871 FILE *out);
1872
1873/**
1874 * Get the x509 der certificate associated with an Eet_File. Will return NULL
1875 * if the file is not signed.
1876 *
1877 * @param ef The file handle to query.
1878 * @param der_length The length of returned data, may be @c NULL.
1879 * @return the x509 certificate or @c NULL on error.
1880 *
1881 * @since 1.2.0
1882 * @ingroup Eet_Cipher_Group
1883 */
1884EAPI const void *
1885eet_identity_x509(Eet_File *ef,
1886 int *der_length);
1887
1888/**
1889 * Get the raw signature associated with an Eet_File. Will return NULL
1890 * if the file is not signed.
1891 *
1892 * @param ef The file handle to query.
1893 * @param signature_length The length of returned data, may be @c NULL.
1894 * @return the raw signature or @c NULL on error.
1895 *
1896 * @ingroup Eet_Cipher_Group
1897 */
1898EAPI const void *
1899eet_identity_signature(Eet_File *ef,
1900 int *signature_length);
1901
1902/**
1903 * Get the SHA1 associated with a file. Could be the one used to
1904 * sign the data or if the data where not signed, it will be the
1905 * SHA1 of the file.
1906 *
1907 * @param ef The file handle to query.
1908 * @param sha1_length The length of returned data, may be @c NULL.
1909 * @return the associated SHA1 or @c NULL on error.
1910 *
1911 * @since 1.2.0
1912 * @ingroup Eet_Cipher_Group
1913 */
1914EAPI const void *
1915eet_identity_sha1(Eet_File *ef,
1916 int *sha1_length);
1917
1918/**
1919 * Display the x509 der certificate to out.
1920 *
1921 * @param certificate the x509 certificate to print
1922 * @param der_length The length the certificate.
1923 * @param out where to print.
1924 *
1925 * @since 1.2.0
1926 * @ingroup Eet_Cipher_Group
1927 */
1928EAPI void
1929eet_identity_certificate_print(const unsigned char *certificate,
1930 int der_length,
1931 FILE *out);
1932
1933/**
1934 * @defgroup Eet_Data_Group Eet Data Serialization
1935 *
1936 * Convenience functions to serialize and parse complex data
1937 * structures to binary blobs.
1938 *
1939 * While Eet core just handles binary blobs, it is often required
1940 * to save some structured data of different types, such as
1941 * strings, integers, lists, hashes and so on.
1942 *
1943 * Eet can serialize and then parse data types given some
1944 * construction instructions. These are defined in two levels:
1945 *
1946 * - #Eet_Data_Descriptor_Class to tell generic memory handling,
1947 * such as the size of the type, how to allocate memory, strings,
1948 * lists, hashes and so on.
1949 *
1950 * - #Eet_Data_Descriptor to tell inside such type, the members and
1951 * their offsets inside the memory blob, their types and
1952 * names. These members can be simple types or other
1953 * #Eet_Data_Descriptor, allowing hierarchical types to be
1954 * defined.
1955 *
1956 * Given that C provides no introspection, this process can be
1957 * quite cumbersome, so we provide lots of macros and convenience
1958 * functions to aid creating the types.
1959 *
1960 * We make now a quick overview of some of the most commonly used elements
1961 * of this part of the library. A simple example of a configuration system
1962 * will work as a somewhat real life example that is still simple enough to
1963 * follow.
1964 * Only the relevant sections will be shown here, but you can get the full
1965 * code @ref eet-data-simple.c "here".
1966 *
1967 * Ignoring the included headers, we'll begin by defining our configuration
1968 * struct.
1969 * @dontinclude eet-data-simple.c
1970 * @skip typedef
1971 * @until }
1972 *
1973 * When using Eet, you don't think in matters of what data the program needs
1974 * to run and which you would like to store. It's all the same and if it makes
1975 * more sense to keep them together, it's perfectly fine to do so. At the time
1976 * of telling Eet how your data is comprised you can leave out the things
1977 * that are runtime only and let Eet take care of the rest for you.
1978 *
1979 * The key used to store the config follows, as well as the variable used to
1980 * store our data descriptor.
1981 * This last one is very important. It's the one thing that Eet will use to
1982 * identify your data, both at the time of writing it to the file and when
1983 * loading from it.
1984 * @skipline MY_CONF
1985 * @skipline Eet_Data_Descriptor
1986 *
1987 * Now we'll see how to create this descriptor, so Eet knows how to handle
1988 * our data later on.
1989 * Begin our function by declaring an Eet_Data_Descriptor_Class, which is
1990 * used to create the actual descriptor. This class contains the name of
1991 * our data type, its size and several functions that dictate how Eet should
1992 * handle memory to allocate the necessary bits to bring our data to life.
1993 * You, as a user, will very hardly set this class' contents directly. The
1994 * most common scenario is to use one of the provided macros that set it using
1995 * the Eina data types, so that's what we'll be doing across all our examples.
1996 * @skip static void
1997 * @until eet_data_descriptor_stream_new
1998 *
1999 * Now that we have our descriptor, we need to make it describe something.
2000 * We do so by telling it which members of our struct we want it to know about
2001 * and their types.
2002 * The eet_data_descriptor_element_add() function takes care of this, but it's
2003 * too cumbersome for normal use, so several macros are provided that make
2004 * it easier to handle. Even with them, however, code can get very repetitive
2005 * and it's not uncommon to define custom macros using them to save on typing.
2006 * @skip #define
2007 * @until }
2008 *
2009 * Now our descriptor knows about the parts of our structure that we are
2010 * interesting in saving. You can see that not all of them are there, yet Eet
2011 * will find those that need saving and do the right thing. When loading our
2012 * data, any non-described fields in the structure will be zeroed, so there's
2013 * no need to worry about garbage memory in them.
2014 * Refer to the documentation of #EET_DATA_DESCRIPTOR_ADD_BASIC to understand
2015 * what our macro does.
2016 *
2017 * We are done with our descriptor init function and it's proper to have the
2018 * relevant shutdown. Proper coding guidelines indiciate that all memory
2019 * allocated should be freed when the program ends, and since you will most
2020 * likely keep your descriptor around for the life or your application, it's
2021 * only right to free it at the end.
2022 * @skip static void
2023 * @until }
2024 *
2025 * Not listed here, but included in the full example are functions to create
2026 * a blank configuration and free it. The first one will only be used when
2027 * no file exists to load from, or nothing is found in it, but the latter is
2028 * used regardless of where our data comes from. Unless you are reading direct
2029 * data from the Eet file, you will be in charge of freeing anything loaded
2030 * from it.
2031 *
2032 * Now it's time to look at how we can load our config from some file.
2033 * Begin by opening the Eet file normally.
2034 * @skip static My_Conf_Type
2035 * @until }
2036 *
2037 * And now we need to read the data from the file and decode it using our
2038 * descriptor. Fortunately, that's all done in one single step.
2039 * @until goto
2040 *
2041 * And that's it for all Eet cares about. But since we are dealing with a
2042 * common case, as is save and load of user configurations, the next fragment
2043 * of code shows why we have a version field in our struct, and how you can
2044 * use it to load older configuration files and update them as needed.
2045 * @until }
2046 *
2047 * Finally, close the file and return the newly loaded config data.
2048 * @until }
2049 *
2050 * Saving data is just as easy. The full version of the following function
2051 * includes code to save to a temporary file first, so you can be sure not
2052 * to lose all your data in the case of a failure mid-writing. You can look
2053 * at it @ref eet-data-simple.c "here".
2054 * @skip static Eina_Bool
2055 * @until {
2056 * @skipline Eina_Bool ret
2057 * @skip eet_open
2058 * @until eet_close
2059 * @skip return
2060 * @until }
2061 *
2062 * To close, our main function, which doesn't do much. Just take some arguments
2063 * from the command line with the name of the file to load and another one
2064 * where to save again. If input file doesn't exist, a new config structure
2065 * will be created and saved to our output file.
2066 * @skip int main
2067 * @until return ret
2068 * @until }
2069 *
2070 * The following is a list of more advanced and detailed examples.
2071 * @li @ref eet_data_nested_example
2072 * @li @ref eet_data_file_descriptor
2073 * @li @ref Example_Eet_Data_File_Descriptor_02
2074 * @li @ref Example_Eet_Data_Cipher_Decipher
2075 */
2076
2077/**
2078 * @page eet_data_nested_example Nested structures and Eet Data Descriptors
2079 *
2080 * We've seen already a simple example of how to use Eet Data Descriptors
2081 * to handle our structures, but it didn't show how this works when you
2082 * have structures inside other structures.
2083 *
2084 * Now, there's a very simple case of this, for when you have inline structs
2085 * to keep your big structure more organized, you don't need anything else
2086 * besides what @ref eet-data-simple.c "this simple example does".
2087 * Just use something like @p some_struct.sub_struct.member when adding the
2088 * member to the descriptor and it will work.
2089 *
2090 * For example:
2091 * @code
2092 * typedef struct
2093 * {
2094 * int a_number;
2095 * char *a_string;
2096 * struct {
2097 * int other_num;
2098 * int one_more;
2099 * } sub;
2100 * } some_struct;
2101 *
2102 * void some_function()
2103 * {
2104 * ...
2105 * my_desc = eet_data_descriptor_stream_new(&eddc);
2106 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_number",
2107 * a_number, EET_T_INT);
2108 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_string",
2109 * a_string, EET_T_STRING);
2110 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.other_num",
2111 * sub.other_num, EET_T_INT);
2112 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.one_more",
2113 * sub.one_more", EET_T_INT);
2114 * ...
2115 * }
2116 * @endcode
2117 *
2118 * But this is not what we are here for today. When we talk about nested
2119 * structures, what we really want are things like lists and hashes to be
2120 * taken into consideration automatically, and all their contents saved and
2121 * loaded just like ordinary integers and strings are.
2122 *
2123 * And of course, Eet can do that, and considering the work it saves you as a
2124 * programmer, we could say it's even easier to do than handling just integers.
2125 *
2126 * Let's begin with our example then, which is not all too different from the
2127 * simple one introduced earlier.
2128 *
2129 * We won't ignore the headers this time to show how easy it is to use Eina
2130 * data types with Eet, but we'll still skip most of the code that is not
2131 * pertinent to what we want to show now, but as usual, you can get it full
2132 * by following @ref eet-data-nested.c "this link".
2133 *
2134 * @dontinclude eet-data-nested.c
2135 * @skipline Eina.h
2136 * @skipline Eet.h
2137 * @skip typedef struct
2138 * @until } My_Conf_Subtype
2139 *
2140 * Extremely similar to our previous example. Just a new struct in there, and
2141 * a pointer to a list in the one we already had. Handling a list of subtypes
2142 * is easy on our program, but now we'll see what Eet needs to work with them
2143 * (Hint: it's easy too).
2144 * @skip _my_conf_descriptor
2145 * @until _my_conf_sub_descriptor
2146 *
2147 * Since we have two structures now, it's only natural that we'll need two
2148 * descriptors. One for each, which will be defined exactly as before.
2149 * @skip static void
2150 * @until eddc
2151 * @skip EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET
2152 * @until _my_conf_sub_descriptor
2153 *
2154 * We create our descriptors, each for one type, and as before, we are going to
2155 * use a simple macro to set their contents, to save on typing.
2156 * @skip #define
2157 * @until EET_T_UCHAR
2158 *
2159 * So far, nothing new. We have our descriptors and we know already how to
2160 * save them separately. But what we want is to link them together, and even
2161 * more so, we want our main type to hold a list of more than one of the new
2162 * sub type. So how do we do that?
2163 *
2164 * Simple enough, we tell Eet that our main descriptor will hold a list, of
2165 * which each node will point to some type described by our new descriptor.
2166 * @skip EET_DATA_DESCRIPTOR_ADD_LIST
2167 * @until _my_conf_sub_descriptor
2168 *
2169 * And that's all. We are closing the function now so as to not leave dangling
2170 * curly braces, but there's nothing more to show in this example. Only other
2171 * additions are the necessary code to free our new data, but you can see it
2172 * in the full code listing.
2173 * @until }
2174 */
2175
2176/**
2177 * @page eet_data_file_descriptor Advanced use of Eet Data Descriptors
2178 *
2179 * A real life example is usually the best way to see how things are used,
2180 * but they also involve a lot more code than what needs to be shown, so
2181 * instead of going that way, we'll be borrowing some pieces from one in
2182 * the following example. It's been slightly modified from the original
2183 * source to show more of the varied ways in which Eet can handle our data.
2184 *
2185 * @ref eet-data-file_descriptor_01.c "This example" shows a cache of user
2186 * accounts and messages received, and it's a bit more interactive than
2187 * previous examples.
2188 *
2189 * Let's begin by looking at the structures we'll be using. First we have
2190 * one to define the messages the user receives and one for the one he posts.
2191 * Straight forward and nothing new here.
2192 * @dontinclude eet-data-file_descriptor_01.c
2193 * @skip typedef
2194 * @until My_Post
2195 *
2196 * One more to declare the account itself. This one will contain a list of
2197 * all messages received, and the posts we make ourselves will be kept in an
2198 * array. No special reason other than to show how to use arrays with Eet.
2199 * @until My_Account
2200 *
2201 * Finally, the main structure to hold our cache of accounts. We'll be looking
2202 * for these accounts by their names, so let's keep them in a hash, using
2203 * that name as the key.
2204 * @until My_Cache
2205 *
2206 * As explained before, we need one descriptor for each struct we want Eet
2207 * to handle, but this time we also want to keep around our Eet file and its
2208 * string dictionary. You will see why in a moment.
2209 * @skip Eet_Data_Descriptor
2210 * @until _my_post_descriptor
2211 * @skip Eet_File
2212 * @until Eet_Dictionary
2213 *
2214 * The differences begin now. They aren't much, but we'll be creating our
2215 * descriptors differently. Things can be added to our cache, but we won't
2216 * be modifying the current contents, so we can consider the data read from
2217 * it to be read-only, and thus allow Eet to save time and memory by not
2218 * duplicating thins unnecessary.
2219 * @skip static void
2220 * @until _my_post_descriptor
2221 *
2222 * As the comment in the code explains, we are asking Eet to give us strings
2223 * directly from the mapped file, which avoids having to load it in memory
2224 * and data duplication.
2225 * Of course, there are things to take into account when doing things this
2226 * way, and they will be mentioned as we encounter those special cases.
2227 *
2228 * Next comes the actual description of our data, just like we did in the
2229 * previous examples.
2230 * @skip #define
2231 * @until #undef
2232 * @until #define
2233 * @until #undef
2234 *
2235 * And the account struct's description doesn't add much new, but it's worth
2236 * commenting on it.
2237 * @skip #define
2238 * @until _my_post_descriptor
2239 *
2240 * How to add a list we've seen before, but now we are also adding an array.
2241 * There's nothing really special about it, but it's important to note that
2242 * the EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY is used to add arrays of variable
2243 * length to a descriptor. That is, arrays just like the one we defined.
2244 * Since there's no way in C to know how long they are, we need to keep
2245 * track of the count ourselves and Eet needs to know how to do so as well.
2246 * That's what the @p posts_count member of our struct is for. When adding
2247 * our array member, this macro will look for another variable in the struct
2248 * named just like the array, but with @p _count attached to the end.
2249 * When saving our data, Eet will know how many elements the array contains
2250 * by looking into this count variable. When loading back from a file, this
2251 * variable will be set to the right number of elements.
2252 *
2253 * Another option for arrays is to use EET_DATA_DESCRIPTOR_ADD_ARRAY, which
2254 * takes care of fixed sized arrays.
2255 * For example, let's suppose that we want to keep track of only the last
2256 * ten posts the user sent, and we declare our account struct as follows
2257 * @code
2258 * typedef struct
2259 * {
2260 * unsigned int id;
2261 * const char *name;
2262 * Eina_List *messages;
2263 * My_Post posts[10];
2264 * } My_Account;
2265 * @endcode
2266 * Then we would add the array to our descriptor with
2267 * @code
2268 * EET_DATA_DESCRIPTOR_ADD_ARRAY(_my_account_descriptor, My_Account, "posts",
2269 * posts, _my_post_descriptor);
2270 * @endcode
2271 *
2272 * Notice how this time we don't have a @p posts_count variable in our struct.
2273 * We could have it for the program to keep track of how many posts the
2274 * array actually contains, but Eet no longer needs it. Being defined that
2275 * way the array is already taking up all the memory needed for the ten
2276 * elements, and it is possible in C to determine how much it is in code.
2277 * When saving our data, Eet will just dump the entire memory blob into the
2278 * file, regardless of how much of it is really used. So it's important to
2279 * take into consideration this kind of things when defining your data types.
2280 * Each has its uses, its advantages and disadvantages and it's up to you
2281 * to decide which to use.
2282 *
2283 * Now, going back to our example, we have to finish adding our data to the
2284 * descriptors. We are only missing the main one for the cache, which
2285 * contains our hash of accounts.
2286 * Unless you are using your own hash functions when setting the descriptor
2287 * class, always use hashes with string type keys.
2288 * @skip #define
2289 * @until }
2290 *
2291 * If you remember, we told Eet not to duplicate memory when possible at the
2292 * time of loading back our data. But this doesn't mean everything will be
2293 * loaded straight from disk and we don't have to worry about freeing it.
2294 * Data in the Eet file is compressed and encoded, so it still needs to be
2295 * decoded and memory will be allocated to convert it back into something we
2296 * can use. We also need to take care of anything we add in the current
2297 * instance of the program.
2298 * To summarize, any string we get from Eet is likely to be a pointer to the
2299 * internal dictionary, and trying to free it will, in the best case, crash
2300 * our application right away.
2301 *
2302 * So how do we know if we have to free a string? We check if it's part of
2303 * the dictionary, and if it's not there we can be sure it's safe to get
2304 * rid of it.
2305 * @skip static void
2306 * @skip }
2307 * @skip static void
2308 * @until }
2309 *
2310 * See how this is used when adding a new message to our cache.
2311 * @skip static My_Message
2312 * @until return msg
2313 * @until free(msg)
2314 * @until }
2315 *
2316 * Skipping all the utility functions used by our program (remember you can
2317 * look at the full example @ref eet-data-file_descriptor_01.c "here") we get to
2318 * our cache loading code. Nothing out of the ordinary at first, just the
2319 * same old open file, read data using our main descriptor to decode it
2320 * into something we can use and check version of loaded data and if it doesn't
2321 * match, do something accordingly.
2322 * @skip static My_Cache
2323 * @until }
2324 * @until }
2325 * @until }
2326 *
2327 * Then comes the interesting part. Remember how we kept two more global
2328 * variables with our descriptors? One of them we already used to check if
2329 * it was right to free a string or not, but we didn't know where it came from.
2330 * Loading our data straight from the mmapped file means that we can't close
2331 * it until we are done using it, so we need to keep its handler around until
2332 * then. It also means that any changes done to the file can, and will,
2333 * invalidate all our pointers to the file backed data, so if we add something
2334 * and save the file, we need to reload our cache.
2335 *
2336 * Thus our load function checks if we had an open file, if there is it gets
2337 * closed and our variable is updated to the new handler. Then we get the
2338 * string dictionary we use to check if a string is part of it or not.
2339 * Updating any references to the cache data is up you as a programmer to
2340 * handle properly, there's nothing Eet can do in this situation.
2341 * @until }
2342 *
2343 * The save function doesn't have anything new, and all that's left after it
2344 * is the main program, which doesn't really have anything of interest within
2345 * the scope of what we are learning.
2346 */
2347
2348/**
2349 * @addtogroup Eet_Data_Group
2350 * @{
2351 */
2352#define EET_T_UNKNOW 0 /**< Unknown data encoding type */
2353#define EET_T_CHAR 1 /**< Data type: char */
2354#define EET_T_SHORT 2 /**< Data type: short */
2355#define EET_T_INT 3 /**< Data type: int */
2356#define EET_T_LONG_LONG 4 /**< Data type: long long */
2357#define EET_T_FLOAT 5 /**< Data type: float */
2358#define EET_T_DOUBLE 6 /**< Data type: double */
2359#define EET_T_UCHAR 7 /**< Data type: unsigned char */
2360#define EET_T_USHORT 8 /**< Data type: unsigned short */
2361#define EET_T_UINT 9 /**< Data type: unsigned int */
2362#define EET_T_ULONG_LONG 10 /**< Data type: unsigned long long */
2363#define EET_T_STRING 11 /**< Data type: char * */
2364#define EET_T_INLINED_STRING 12 /**< Data type: char * (but compressed inside the resulting eet) */
2365#define EET_T_NULL 13 /**< Data type: (void *) (only use it if you know why) */
2366#define EET_T_F32P32 14 /**< Data type: fixed point 32.32 */
2367#define EET_T_F16P16 15 /**< Data type: fixed point 16.16 */
2368#define EET_T_F8P24 16 /**< Data type: fixed point 8.24 */
2369#define EET_T_LAST 18 /**< Last data type */
2370
2371#define EET_G_UNKNOWN 100 /**< Unknown group data encoding type */
2372#define EET_G_ARRAY 101 /**< Fixed size array group type */
2373#define EET_G_VAR_ARRAY 102 /**< Variable size array group type */
2374#define EET_G_LIST 103 /**< Linked list group type */
2375#define EET_G_HASH 104 /**< Hash table group type */
2376#define EET_G_UNION 105 /**< Union group type */
2377#define EET_G_VARIANT 106 /**< Selectable subtype group */
2378#define EET_G_LAST 107 /**< Last group type */
2379
2380#define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */
2381
2382/**
2383 * @typedef Eet_Data_Descriptor
2384 *
2385 * Opaque handle that have information on a type members.
2386 *
2387 * Descriptors are created using an #Eet_Data_Descriptor_Class, and they
2388 * describe the contents of the structure that will be serialized by Eet.
2389 * Not all members need be described by it, just those that should be handled
2390 * by Eet. This way it's possible to have one structure with both data to be
2391 * saved to a file, like application configuration, and runtime information
2392 * that would be meaningless to store, but is appropriate to keep together
2393 * during the program execution.
2394 * The members are added by means of
2395 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(),
2396 * EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH()
2397 * or eet_data_descriptor_element_add().
2398 *
2399 * @see eet_data_descriptor_stream_new()
2400 * @see eet_data_descriptor_file_new()
2401 * @see eet_data_descriptor_free()
2402 */
2403typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor;
2404
2405/**
2406 * @def EET_DATA_DESCRIPTOR_CLASS_VERSION
2407 * The version of #Eet_Data_Descriptor_Class at the time of the
2408 * distribution of the sources. One should define this to its
2409 * version member so it is compatible with abi changes, or at least
2410 * will not crash with them.
2411 */
2412#define EET_DATA_DESCRIPTOR_CLASS_VERSION 4
2413
2414/**
2415 * @typedef Eet_Data_Descriptor_Class
2416 *
2417 * Instructs Eet about memory management for different needs under
2418 * serialization and parse process.
2419 */
2420typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
2421
2422typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt);
2423
2424typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size);
2425typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem);
2426typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str);
2427typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str);
2428typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l);
2429typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d);
2430typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l);
2431typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l);
2432typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt);
2433typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d);
2434typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h);
2435typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str);
2436typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str);
2437typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow);
2438typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow);
2439typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size);
2440typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem);
2441/**
2442 * @struct _Eet_Data_Descriptor_Class
2443 *
2444 * Instructs Eet about memory management for different needs under
2445 * serialization and parse process.
2446 *
2447 * The list and hash methods match the Eina API, so for a more detailed
2448 * reference on them, look at the Eina_List and Eina_Hash documentation,
2449 * respectively.
2450 * For the most part these will be used with the standard Eina functions,
2451 * so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
2452 * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything
2453 * accordingly.
2454 */
2455struct _Eet_Data_Descriptor_Class
2456{
2457 int version; /**< ABI version. Should always be set to #EET_DATA_DESCRIPTOR_CLASS_VERSION */
2458 const char *name; /**< Name of the user data type to be serialized */
2459 int size; /**< Size in bytes of the user data type to be serialized */
2460 struct
2461 {
2462 Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to allocate memory (usually malloc()) */
2463 Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free memory (usually free()) */
2464 Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to allocate a string */
2465 Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a string */
2466 Eet_Descriptor_List_Next_Callback list_next; /**< how to iterate to the next element of a list. Receives and should return the list node. */
2467 Eet_Descriptor_List_Append_Callback list_append; /**< how to append data @p d to list which head node is @p l */
2468 Eet_Descriptor_List_Data_Callback list_data; /**< retrieves the data from node @p l */
2469 Eet_Descriptor_List_Free_Callback list_free; /**< free all the nodes from the list which head node is @p l */
2470 Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates over all elements in the hash @p h in no specific order */
2471 Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new data @p d with key @p k in hash @p h */
2472 Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all entries from the hash @p h */
2473 Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */
2474 Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to free a string returned by str_direct_alloc */
2475 Eet_Descriptor_Type_Get_Callback type_get; /**< get the type, as used in the union or variant mapping, that should be used to store the given data into the eet file. */
2476 Eet_Descriptor_Type_Set_Callback type_set; /**< called when loading a mapped type with the given @p type used to describe the type in the descriptor */
2477 Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to allocate memory for array (usually malloc()) */
2478 Eet_Descriptor_Array_Free_Callback array_free; /**< how to free memory for array (usually free()) */
2479 } func;
2480};
2481
2482/**
2483 * @}
2484 */
2485
2486/**
2487 * Create a new empty data structure descriptor.
2488 * @param name The string name of this data structure (most be a
2489 * global constant and never change).
2490 * @param size The size of the struct (in bytes).
2491 * @param func_list_next The function to get the next list node.
2492 * @param func_list_append The function to append a member to a list.
2493 * @param func_list_data The function to get the data from a list node.
2494 * @param func_list_free The function to free an entire linked list.
2495 * @param func_hash_foreach The function to iterate through all
2496 * hash table entries.
2497 * @param func_hash_add The function to add a member to a hash table.
2498 * @param func_hash_free The function to free an entire hash table.
2499 * @return A new empty data descriptor.
2500 *
2501 * This function creates a new data descriptor and returns a handle to the
2502 * new data descriptor. On creation it will be empty, containing no contents
2503 * describing anything other than the shell of the data structure.
2504 *
2505 * You add structure members to the data descriptor using the macros
2506 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
2507 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
2508 * adding to the description.
2509 *
2510 * Once you have described all the members of a struct you want loaded, or
2511 * saved eet can load and save those members for you, encode them into
2512 * endian-independent serialised data chunks for transmission across a
2513 * a network or more.
2514 *
2515 * The function pointers to the list and hash table functions are only
2516 * needed if you use those data types, else you can pass NULL instead.
2517 *
2518 * @since 1.0.0
2519 * @ingroup Eet_Data_Group
2520 *
2521 * @deprecated use eet_data_descriptor_stream_new() or
2522 * eet_data_descriptor_file_new()
2523 */
2524EINA_DEPRECATED EAPI Eet_Data_Descriptor *
2525eet_data_descriptor_new(const char *name,
2526 int size,
2527 Eet_Descriptor_List_Next_Callback func_list_next,
2528 Eet_Descriptor_List_Append_Callback func_list_append,
2529 Eet_Descriptor_List_Data_Callback func_list_data,
2530 Eet_Descriptor_List_Free_Callback func_list_free,
2531 Eet_Descriptor_Hash_Foreach_Callback func_hash_foreach,
2532 Eet_Descriptor_Hash_Add_Callback func_hash_add,
2533 Eet_Descriptor_Hash_Free_Callback func_hash_free);
2534/*
2535 * FIXME:
2536 *
2537 * moving to this api from the old above. this will break things when the
2538 * move happens - but be warned
2539 */
2540EINA_DEPRECATED EAPI Eet_Data_Descriptor *
2541 eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc);
2542EINA_DEPRECATED EAPI Eet_Data_Descriptor *
2543 eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc);
2544
2545/**
2546 * This function creates a new data descriptor and returns a handle to the
2547 * new data descriptor. On creation it will be empty, containing no contents
2548 * describing anything other than the shell of the data structure.
2549 * @param eddc The class from where to create the data descriptor.
2550 * @return A handle to the new data descriptor.
2551 *
2552 * You add structure members to the data descriptor using the macros
2553 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
2554 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
2555 * adding to the description.
2556 *
2557 * Once you have described all the members of a struct you want loaded or
2558 * saved, eet can load and save those members for you, encode them into
2559 * endian-independent serialised data chunks for transmission across a
2560 * network or more.
2561 *
2562 * This function specially ignores str_direct_alloc and str_direct_free. It
2563 * is useful when the eet_data you are reading doesn't have a dictionary,
2564 * like network stream or IPC. It also mean that all string will be allocated
2565 * and duplicated in memory.
2566 *
2567 * @since 1.2.3
2568 * @ingroup Eet_Data_Group
2569 */
2570EAPI Eet_Data_Descriptor *
2571eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc);
2572
2573/**
2574 * This function creates a new data descriptor and returns a handle to the
2575 * new data descriptor. On creation it will be empty, containing no contents
2576 * describing anything other than the shell of the data structure.
2577 * @param eddc The class from where to create the data descriptor.
2578 * @return A handle to the new data descriptor.
2579 *
2580 * You add structure members to the data descriptor using the macros
2581 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
2582 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
2583 * adding to the description.
2584 *
2585 * Once you have described all the members of a struct you want loaded or
2586 * saved, eet can load and save those members for you, encode them into
2587 * endian-independent serialised data chunks for transmission across a
2588 * a network or more.
2589 *
2590 * This function uses str_direct_alloc and str_direct_free. It is
2591 * useful when the eet_data you are reading come from a file and
2592 * have a dictionary. This will reduce memory use and improve the
2593 * possibility for the OS to page this string out.
2594 * However, the load speed and memory saving comes with some drawbacks to keep
2595 * in mind. If you never modify the contents of the structures loaded from
2596 * the file, all you need to remember is that closing the eet file will make
2597 * the strings go away. On the other hand, should you need to free a string,
2598 * before doing so you have to verify that it's not part of the eet dictionary.
2599 * You can do this in the following way, assuming @p ef is a valid Eet_File
2600 * and @p str is a string loaded from said file.
2601 *
2602 * @code
2603 * void eet_string_free(Eet_File *ef, const char *str)
2604 * {
2605 * Eet_Dictionary *dict = eet_dictionary_get(ef);
2606 * if (dict && eet_dictionary_string_check(dict, str))
2607 * {
2608 * // The file contains a dictionary and the given string is a part of
2609 * // of it, so we can't free it, just return.
2610 * return;
2611 * }
2612 * // We assume eina_stringshare was used on the descriptor
2613 * eina_stringshare_del(str);
2614 * }
2615 * @endcode
2616 *
2617 * @since 1.2.3
2618 * @ingroup Eet_Data_Group
2619 */
2620EAPI Eet_Data_Descriptor *
2621eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc);
2622
2623/**
2624 * This function is an helper that set all the parameters of an
2625 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2626 * with a stream.
2627 * @param eddc The Eet_Data_Descriptor_Class you want to set.
2628 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
2629 * @param name The name of the structure described by this class.
2630 * @param size The size of the structure described by this class.
2631 * @return EINA_TRUE if the structure was correctly set (The only
2632 * reason that could make it fail is if you did give wrong
2633 * parameter).
2634 *
2635 * @note Unless there's a very specific reason to use this function directly,
2636 * the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
2637 *
2638 * @since 1.2.3
2639 * @ingroup Eet_Data_Group
2640 */
2641EAPI Eina_Bool
2642eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
2643 unsigned int eddc_size,
2644 const char *name,
2645 int size);
2646
2647/**
2648 * This macro is an helper that set all the parameter of an
2649 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2650 * with stream.
2651 * @param clas The Eet_Data_Descriptor_Class you want to set.
2652 * @param type The type of the structure described by this class.
2653 * @return EINA_TRUE if the structure was correctly set (The only
2654 * reason that could make it fail is if you did give wrong
2655 * parameter).
2656 *
2657 * @see eet_data_descriptor_stream_new
2658 * @since 1.2.3
2659 * @ingroup Eet_Data_Group
2660 */
2661#define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
2662 (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
2663
2664/**
2665 * This function is an helper that set all the parameter of an
2666 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2667 * with a file.
2668 * @param eddc The Eet_Data_Descriptor_Class you want to set.
2669 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time.
2670 * @param name The name of the structure described by this class.
2671 * @param size The size of the structure described by this class.
2672 * @return EINA_TRUE if the structure was correctly set (The only
2673 * reason that could make it fail is if you did give wrong
2674 * parameter).
2675 *
2676 * @note Unless there's a very specific reason to use this function directly,
2677 * the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
2678 *
2679 * @since 1.2.3
2680 * @ingroup Eet_Data_Group
2681 */
2682EAPI Eina_Bool
2683eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
2684 unsigned int eddc_size,
2685 const char *name,
2686 int size);
2687
2688/**
2689 * This macro is an helper that set all the parameter of an
2690 * Eet_Data_Descriptor_Class correctly when you use Eina data type
2691 * with file.
2692 * @param clas The Eet_Data_Descriptor_Class you want to set.
2693 * @param type The type of the structure described by this class.
2694 * @return EINA_TRUE if the structure was correctly set (The only
2695 * reason that could make it fail is if you did give wrong
2696 * parameter).
2697 *
2698 * @see eet_data_descriptor_file_new
2699 * @since 1.2.3
2700 * @ingroup Eet_Data_Group
2701 */
2702#define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
2703 (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
2704
2705/**
2706 * This function frees a data descriptor when it is not needed anymore.
2707 * @param edd The data descriptor to free.
2708 *
2709 * This function takes a data descriptor handle as a parameter and frees all
2710 * data allocated for the data descriptor and the handle itself. After this
2711 * call the descriptor is no longer valid.
2712 *
2713 * @since 1.0.0
2714 * @ingroup Eet_Data_Group
2715 */
2716EAPI void
2717eet_data_descriptor_free(Eet_Data_Descriptor *edd);
2718
2719/**
2720 * This function is an internal used by macros.
2721 *
2722 * This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(),
2723 * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is
2724 * complex to use by hand and should be left to be used by the macros, and
2725 * thus is not documented.
2726 *
2727 * @param edd The data descriptor handle to add element (member).
2728 * @param name The name of element to be serialized.
2729 * @param type The type of element to be serialized, like
2730 * #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a
2731 * group, list or hash.
2732 * @param group_type If element type is #EET_T_UNKNOW, then the @p
2733 * group_type will specify if it is a list (#EET_G_LIST),
2734 * array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then
2735 * the member is a subtype (pointer to another type defined by
2736 * another #Eet_Data_Descriptor).
2737 * @param offset byte offset inside the source memory to be serialized.
2738 * @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY).
2739 * @param counter_name variable that defines the name of number of elements.
2740 * @param subtype If contains a subtype, then its data descriptor.
2741 *
2742 * @since 1.0.0
2743 * @ingroup Eet_Data_Group
2744 */
2745EAPI void
2746eet_data_descriptor_element_add(Eet_Data_Descriptor *edd,
2747 const char *name,
2748 int type,
2749 int group_type,
2750 int offset,
2751 /* int count_offset, */
2752 int count,
2753 const char *counter_name,
2754 Eet_Data_Descriptor *subtype);
2755
2756/**
2757 * Read a data structure from an eet file and decodes it.
2758 * @param ef The eet file handle to read from.
2759 * @param edd The data descriptor handle to use when decoding.
2760 * @param name The key the data is stored under in the eet file.
2761 * @return A pointer to the decoded data structure.
2762 *
2763 * This function decodes a data structure stored in an eet file, returning
2764 * a pointer to it if it decoded successfully, or NULL on failure. This
2765 * can save a programmer dozens of hours of work in writing configuration
2766 * file parsing and writing code, as eet does all that work for the program
2767 * and presents a program-friendly data structure, just as the programmer
2768 * likes. Eet can handle members being added or deleted from the data in
2769 * storage and safely zero-fills unfilled members if they were not found
2770 * in the data. It checks sizes and headers whenever it reads data, allowing
2771 * the programmer to not worry about corrupt data.
2772 *
2773 * Once a data structure has been described by the programmer with the
2774 * fields they wish to save or load, storing or retrieving a data structure
2775 * from an eet file, or from a chunk of memory is as simple as a single
2776 * function call.
2777 *
2778 * @see eet_data_read_cipher()
2779 *
2780 * @since 1.0.0
2781 * @ingroup Eet_Data_Group
2782 */
2783EAPI void *
2784eet_data_read(Eet_File *ef,
2785 Eet_Data_Descriptor *edd,
2786 const char *name);
2787
2788/**
2789 * Write a data structure from memory and store in an eet file.
2790 * @param ef The eet file handle to write to.
2791 * @param edd The data descriptor to use when encoding.
2792 * @param name The key to store the data under in the eet file.
2793 * @param data A pointer to the data structure to save and encode.
2794 * @param compress Compression flags for storage.
2795 * @return bytes written on successful write, 0 on failure.
2796 *
2797 * This function is the reverse of eet_data_read(), saving a data structure
2798 * to an eet file. The file must have been opening in write mode and the data
2799 * will be kept in memory until the file is either closed or eet_sync() is
2800 * called to flush any unwritten changes.
2801 *
2802 * @see eet_data_write_cipher()
2803 *
2804 * @since 1.0.0
2805 * @ingroup Eet_Data_Group
2806 */
2807EAPI int
2808eet_data_write(Eet_File *ef,
2809 Eet_Data_Descriptor *edd,
2810 const char *name,
2811 const void *data,
2812 int compress);
2813
2814typedef void (*Eet_Dump_Callback)(void *data, const char *str);
2815
2816/**
2817 * Dump an eet encoded data structure into ascii text
2818 * @param data_in The pointer to the data to decode into a struct.
2819 * @param size_in The size of the data pointed to in bytes.
2820 * @param dumpfunc The function to call passed a string when new
2821 * data is converted to text
2822 * @param dumpdata The data to pass to the @p dumpfunc callback.
2823 * @return 1 on success, 0 on failure
2824 *
2825 * This function will take a chunk of data encoded by
2826 * eet_data_descriptor_encode() and convert it into human readable
2827 * ascii text. It does this by calling the @p dumpfunc callback
2828 * for all new text that is generated. This callback should append
2829 * to any existing text buffer and will be passed the pointer @p
2830 * dumpdata as a parameter as well as a string with new text to be
2831 * appended.
2832 *
2833 * Example:
2834 *
2835 * @code
2836 * void output(void *data, const char *string)
2837 * {
2838 * printf("%s", string);
2839 * }
2840 *
2841 * void dump(const char *file)
2842 * {
2843 * FILE *f;
2844 * int len;
2845 * void *data;
2846 *
2847 * f = fopen(file, "r");
2848 * fseek(f, 0, SEEK_END);
2849 * len = ftell(f);
2850 * rewind(f);
2851 * data = malloc(len);
2852 * fread(data, len, 1, f);
2853 * fclose(f);
2854 * eet_data_text_dump(data, len, output, NULL);
2855 * }
2856 * @endcode
2857 *
2858 * @see eet_data_text_dump_cipher()
2859 *
2860 * @since 1.0.0
2861 * @ingroup Eet_Data_Group
2862 */
2863EAPI int
2864eet_data_text_dump(const void *data_in,
2865 int size_in,
2866 Eet_Dump_Callback dumpfunc,
2867 void *dumpdata);
2868
2869/**
2870 * Take an ascii encoding from eet_data_text_dump() and re-encode in binary.
2871 * @param text The pointer to the string data to parse and encode.
2872 * @param textlen The size of the string in bytes (not including 0
2873 * byte terminator).
2874 * @param size_ret This gets filled in with the encoded data blob
2875 * size in bytes.
2876 * @return The encoded data on success, NULL on failure.
2877 *
2878 * This function will parse the string pointed to by @p text and return
2879 * an encoded data lump the same way eet_data_descriptor_encode() takes an
2880 * in-memory data struct and encodes into a binary blob. @p text is a normal
2881 * C string.
2882 *
2883 * @see eet_data_text_undump_cipher()
2884 *
2885 * @since 1.0.0
2886 * @ingroup Eet_Data_Group
2887 */
2888EAPI void *
2889eet_data_text_undump(const char *text,
2890 int textlen,
2891 int *size_ret);
2892
2893/**
2894 * Dump an eet encoded data structure from an eet file into ascii text
2895 * @param ef A valid eet file handle.
2896 * @param name Name of the entry. eg: "/base/file_i_want".
2897 * @param dumpfunc The function to call passed a string when new
2898 * data is converted to text
2899 * @param dumpdata The data to pass to the @p dumpfunc callback.
2900 * @return 1 on success, 0 on failure
2901 *
2902 * This function will take an open and valid eet file from
2903 * eet_open() request the data encoded by
2904 * eet_data_descriptor_encode() corresponding to the key @p name
2905 * and convert it into human readable ascii text. It does this by
2906 * calling the @p dumpfunc callback for all new text that is
2907 * generated. This callback should append to any existing text
2908 * buffer and will be passed the pointer @p dumpdata as a parameter
2909 * as well as a string with new text to be appended.
2910 *
2911 * @see eet_data_dump_cipher()
2912 *
2913 * @since 1.0.0
2914 * @ingroup Eet_Data_Group
2915 */
2916EAPI int
2917eet_data_dump(Eet_File *ef,
2918 const char *name,
2919 Eet_Dump_Callback dumpfunc,
2920 void *dumpdata);
2921
2922/**
2923 * Take an ascii encoding from eet_data_dump() and re-encode in binary.
2924 * @param ef A valid eet file handle.
2925 * @param name Name of the entry. eg: "/base/file_i_want".
2926 * @param text The pointer to the string data to parse and encode.
2927 * @param textlen The size of the string in bytes (not including 0
2928 * byte terminator).
2929 * @param compress Compression flags (1 == compress, 0 = don't compress).
2930 * @return 1 on success, 0 on failure
2931 *
2932 * This function will parse the string pointed to by @p text,
2933 * encode it the same way eet_data_descriptor_encode() takes an
2934 * in-memory data struct and encodes into a binary blob.
2935 *
2936 * The data (optionally compressed) will be in ram, pending a flush to
2937 * disk (it will stay in ram till the eet file handle is closed though).
2938 *
2939 * @see eet_data_undump_cipher()
2940 *
2941 * @since 1.0.0
2942 * @ingroup Eet_Data_Group
2943 */
2944EAPI int
2945eet_data_undump(Eet_File *ef,
2946 const char *name,
2947 const char *text,
2948 int textlen,
2949 int compress);
2950
2951/**
2952 * Decode a data structure from an arbitrary location in memory.
2953 * @param edd The data descriptor to use when decoding.
2954 * @param data_in The pointer to the data to decode into a struct.
2955 * @param size_in The size of the data pointed to in bytes.
2956 * @return NULL on failure, or a valid decoded struct pointer on success.
2957 *
2958 * This function will decode a data structure that has been encoded using
2959 * eet_data_descriptor_encode(), and return a data structure with all its
2960 * elements filled out, if successful, or NULL on failure.
2961 *
2962 * The data to be decoded is stored at the memory pointed to by @p data_in,
2963 * and is described by the descriptor pointed to by @p edd. The data size is
2964 * passed in as the value to @p size_in, ande must be greater than 0 to
2965 * succeed.
2966 *
2967 * This function is useful for decoding data structures delivered to the
2968 * application by means other than an eet file, such as an IPC or socket
2969 * connection, raw files, shared memory etc.
2970 *
2971 * Please see eet_data_read() for more information.
2972 *
2973 * @see eet_data_descriptor_decode_cipher()
2974 *
2975 * @since 1.0.0
2976 * @ingroup Eet_Data_Group
2977 */
2978EAPI void *
2979eet_data_descriptor_decode(Eet_Data_Descriptor *edd,
2980 const void *data_in,
2981 int size_in);
2982
2983/**
2984 * Encode a dsata struct to memory and return that encoded data.
2985 * @param edd The data descriptor to use when encoding.
2986 * @param data_in The pointer to the struct to encode into data.
2987 * @param size_ret pointer to the an int to be filled with the decoded size.
2988 * @return NULL on failure, or a valid encoded data chunk on success.
2989 *
2990 * This function takes a data structutre in memory and encodes it into a
2991 * serialised chunk of data that can be decoded again by
2992 * eet_data_descriptor_decode(). This is useful for being able to transmit
2993 * data structures across sockets, pipes, IPC or shared file mechanisms,
2994 * without having to worry about memory space, machine type, endianness etc.
2995 *
2996 * The parameter @p edd must point to a valid data descriptor, and
2997 * @p data_in must point to the right data structure to encode. If not, the
2998 * encoding may fail.
2999 *
3000 * On success a non NULL valid pointer is returned and what @p size_ret
3001 * points to is set to the size of this decoded data, in bytes. When the
3002 * encoded data is no longer needed, call free() on it. On failure NULL is
3003 * returned and what @p size_ret points to is set to 0.
3004 *
3005 * Please see eet_data_write() for more information.
3006 *
3007 * @see eet_data_descriptor_encode_cipher()
3008 *
3009 * @since 1.0.0
3010 * @ingroup Eet_Data_Group
3011 */
3012EAPI void *
3013eet_data_descriptor_encode(Eet_Data_Descriptor *edd,
3014 const void *data_in,
3015 int *size_ret);
3016
3017/**
3018 * Add a basic data element to a data descriptor.
3019 * @param edd The data descriptor to add the type to.
3020 * @param struct_type The type of the struct.
3021 * @param name The string name to use to encode/decode this member
3022 * (must be a constant global and never change).
3023 * @param member The struct member itself to be encoded.
3024 * @param type The type of the member to encode.
3025 *
3026 * This macro is a convenience macro provided to add a member to
3027 * the data descriptor @p edd. The type of the structure is
3028 * provided as the @p struct_type parameter (for example: struct
3029 * my_struct). The @p name parameter defines a string that will be
3030 * used to uniquely name that member of the struct (it is suggested
3031 * to use the struct member itself). The @p member parameter is
3032 * the actual struct member itself (for example: values), and @p type is the
3033 * basic data type of the member which must be one of: EET_T_CHAR, EET_T_SHORT,
3034 * EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR,
3035 * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING.
3036 *
3037 * @since 1.0.0
3038 * @ingroup Eet_Data_Group
3039 */
3040#define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
3041 do { \
3042 struct_type ___ett; \
3043 eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
3044 (char *)(& (___ett.member)) - \
3045 (char *)(& (___ett)), \
3046 0, /* 0, */ NULL, NULL); \
3047 } while(0)
3048
3049/**
3050 * Add a sub-element type to a data descriptor
3051 * @param edd The data descriptor to add the type to.
3052 * @param struct_type The type of the struct.
3053 * @param name The string name to use to encode/decode this member
3054 * (must be a constant global and never change).
3055 * @param member The struct member itself to be encoded.
3056 * @param subtype The type of sub-type struct to add.
3057 *
3058 * This macro lets you easily add a sub-type (a struct that's pointed to
3059 * by this one). All the parameters are the same as for
3060 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception.
3061 * This must be the data descriptor of the struct that is pointed to by
3062 * this element.
3063 *
3064 * @since 1.0.0
3065 * @ingroup Eet_Data_Group
3066 */
3067#define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
3068 do { \
3069 struct_type ___ett; \
3070 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
3071 (char *)(& (___ett.member)) - \
3072 (char *)(& (___ett)), \
3073 0, /* 0, */ NULL, subtype); \
3074 } while (0)
3075
3076/**
3077 * Add a linked list type to a data descriptor
3078 * @param edd The data descriptor to add the type to.
3079 * @param struct_type The type of the struct.
3080 * @param name The string name to use to encode/decode this member
3081 * (must be a constant global and never change).
3082 * @param member The struct member itself to be encoded.
3083 * @param subtype The type of linked list member to add.
3084 *
3085 * This macro lets you easily add a linked list of other data types. All the
3086 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
3087 * @p subtype being the exception. This must be the data descriptor of the
3088 * element that is in each member of the linked list to be stored.
3089 *
3090 * @since 1.0.0
3091 * @ingroup Eet_Data_Group
3092 */
3093#define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \
3094 do { \
3095 struct_type ___ett; \
3096 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
3097 (char *)(& (___ett.member)) - \
3098 (char *)(& (___ett)), \
3099 0, /* 0, */ NULL, subtype); \
3100 } while (0)
3101
3102/**
3103 * Add a linked list of string to a data descriptor
3104 * @param edd The data descriptor to add the type to.
3105 * @param struct_type The type of the struct.
3106 * @param name The string name to use to encode/decode this member
3107 * (must be a constant global and never change).
3108 * @param member The struct member itself to be encoded.
3109 *
3110 * This macro lets you easily add a linked list of char *. All the
3111 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
3112 *
3113 * @since 1.5.0
3114 * @ingroup Eet_Data_Group
3115 */
3116#define EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member) \
3117 do { \
3118 struct_type ___ett; \
3119 eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_LIST, \
3120 (char *)(& (___ett.member)) - \
3121 (char *)(& (___ett)), \
3122 0, /* 0, */ NULL, NULL); \
3123 } while (0)
3124
3125/**
3126 * Add a hash type to a data descriptor
3127 * @param edd The data descriptor to add the type to.
3128 * @param struct_type The type of the struct.
3129 * @param name The string name to use to encode/decode this member
3130 * (must be a constant global and never change).
3131 * @param member The struct member itself to be encoded.
3132 * @param subtype The type of hash member to add.
3133 *
3134 * This macro lets you easily add a hash of other data types. All the
3135 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
3136 * @p subtype being the exception. This must be the data descriptor of the
3137 * element that is in each member of the hash to be stored.
3138 * The hash keys must be strings.
3139 *
3140 * @since 1.0.0
3141 * @ingroup Eet_Data_Group
3142 */
3143#define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \
3144 do { \
3145 struct_type ___ett; \
3146 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \
3147 (char *)(& (___ett.member)) - \
3148 (char *)(& (___ett)), \
3149 0, /* 0, */ NULL, subtype); \
3150 } while (0)
3151
3152/**
3153 * Add a hash of string to a data descriptor
3154 * @param edd The data descriptor to add the type to.
3155 * @param struct_type The type of the struct.
3156 * @param name The string name to use to encode/decode this member
3157 * (must be a constant global and never change).
3158 * @param member The struct member itself to be encoded.
3159 *
3160 * This macro lets you easily add a hash of string elements. All the
3161 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH().
3162 *
3163 * @since 1.3.4
3164 * @ingroup Eet_Data_Group
3165 */
3166#define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \
3167 do { \
3168 struct_type ___ett; \
3169 eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH, \
3170 (char *)(& (___ett.member)) - \
3171 (char *)(& (___ett)), \
3172 0, /* 0, */ NULL, NULL); \
3173 } while (0)
3174
3175/**
3176 * Add an array of basic data elements to a data descriptor.
3177 * @param edd The data descriptor to add the type to.
3178 * @param struct_type The type of the struct.
3179 * @param name The string name to use to encode/decode this member
3180 * (must be a constant global and never change).
3181 * @param member The struct member itself to be encoded.
3182 * @param type The type of the member to encode.
3183 *
3184 * This macro lets you easily add a fixed size array of basic data
3185 * types. All the parameters are the same as for
3186 * EET_DATA_DESCRIPTOR_ADD_BASIC().
3187 * The array must be defined with a fixed size in the declaration of the
3188 * struct containing it.
3189 *
3190 * @since 1.5.0
3191 * @ingroup Eet_Data_Group
3192 */
3193#define EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member, type) \
3194 do { \
3195 struct_type ___ett; \
3196 eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY, \
3197 (char *)(& (___ett.member)) - \
3198 (char *)(& (___ett)), \
3199 sizeof(___ett.member) / \
3200 sizeof(___ett.member[0]), \
3201 NULL, NULL); \
3202 } while(0)
3203
3204/**
3205 * Add a variable array of basic data elements to a data descriptor.
3206 * @param edd The data descriptor to add the type to.
3207 * @param struct_type The type of the struct.
3208 * @param name The string name to use to encode/decode this member
3209 * (must be a constant global and never change).
3210 * @param member The struct member itself to be encoded.
3211 * @param type The type of the member to encode.
3212 *
3213 * This macro lets you easily add a variable size array of basic data
3214 * types. All the parameters are the same as for
3215 * EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have
3216 * a struct member (of type EET_T_INT) called member_count (note the
3217 * _count appended to the member) that holds the number of items in
3218 * the array. This array will be allocated separately to the struct it
3219 * is in.
3220 *
3221 * @since 1.6.0
3222 * @ingroup Eet_Data_Group
3223 */
3224#define EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, member, type) \
3225 do { \
3226 struct_type ___ett; \
3227 eet_data_descriptor_element_add(edd, name, type, EET_G_VAR_ARRAY, \
3228 (char *)(& (___ett.member)) - \
3229 (char *)(& (___ett)), \
3230 (char *)(& (___ett.member ## _count)) - \
3231 (char *)(& (___ett)), \
3232 NULL, \
3233 NULL); \
3234 } while(0)
3235
3236/**
3237 * Add a fixed size array type to a data descriptor
3238 * @param edd The data descriptor to add the type to.
3239 * @param struct_type The type of the struct.
3240 * @param name The string name to use to encode/decode this member
3241 * (must be a constant global and never change).
3242 * @param member The struct member itself to be encoded.
3243 * @param subtype The type of hash member to add.
3244 *
3245 * This macro lets you easily add a fixed size array of other data
3246 * types. All the parameters are the same as for
3247 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
3248 * exception. This must be the data descriptor of the element that
3249 * is in each member of the array to be stored.
3250 * The array must be defined with a fixed size in the declaration of the
3251 * struct containing it.
3252 *
3253 * @since 1.0.2
3254 * @ingroup Eet_Data_Group
3255 */
3256#define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \
3257 do { \
3258 struct_type ___ett; \
3259 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \
3260 (char *)(& (___ett.member)) - \
3261 (char *)(& (___ett)), \
3262 /* 0, */ sizeof(___ett.member) / \
3263 sizeof(___ett.member[0]), NULL, subtype); \
3264 } while (0)
3265
3266/**
3267 * Add a variable size array type to a data descriptor
3268 * @param edd The data descriptor to add the type to.
3269 * @param struct_type The type of the struct.
3270 * @param name The string name to use to encode/decode this member
3271 * (must be a constant global and never change).
3272 * @param member The struct member itself to be encoded.
3273 * @param subtype The type of hash member to add.
3274 *
3275 * This macro lets you easily add a variable size array of other data
3276 * types. All the parameters are the same as for
3277 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
3278 * exception. This must be the data descriptor of the element that
3279 * is in each member of the array to be stored. This assumes you have
3280 * a struct member (of type EET_T_INT) called member_count (note the
3281 * _count appended to the member) that holds the number of items in
3282 * the array. This array will be allocated separately to the struct it
3283 * is in.
3284 *
3285 * @since 1.0.2
3286 * @ingroup Eet_Data_Group
3287 */
3288#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \
3289 do { \
3290 struct_type ___ett; \
3291 eet_data_descriptor_element_add(edd, \
3292 name, \
3293 EET_T_UNKNOW, \
3294 EET_G_VAR_ARRAY, \
3295 (char *)(& (___ett.member)) - \
3296 (char *)(& (___ett)), \
3297 (char *)(& (___ett.member ## _count)) - \
3298 (char *)(& (___ett)), \
3299 /* 0, */ NULL, \
3300 subtype); \
3301 } while (0)
3302
3303/**
3304 * Add a variable size array type to a data descriptor
3305 * @param edd The data descriptor to add the type to.
3306 * @param struct_type The type of the struct.
3307 * @param name The string name to use to encode/decode this member
3308 * (must be a constant global and never change).
3309 * @param member The struct member itself to be encoded.
3310 *
3311 * This macro lets you easily add a variable size array of strings. All
3312 * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
3313 *
3314 * @since 1.4.0
3315 * @ingroup Eet_Data_Group
3316 */
3317#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member) \
3318 do { \
3319 struct_type ___ett; \
3320 eet_data_descriptor_element_add(edd, \
3321 name, \
3322 EET_T_STRING, \
3323 EET_G_VAR_ARRAY, \
3324 (char *)(& (___ett.member)) - \
3325 (char *)(& (___ett)), \
3326 (char *)(& (___ett.member ## _count)) - \
3327 (char *)(& (___ett)), \
3328 /* 0, */ NULL, \
3329 NULL); \
3330 } while (0)
3331
3332/**
3333 * Add an union type to a data descriptor
3334 * @param edd The data descriptor to add the type to.
3335 * @param struct_type The type of the struct.
3336 * @param name The string name to use to encode/decode this member
3337 * (must be a constant global and never change).
3338 * @param member The struct member itself to be encoded.
3339 * @param type_member The member that give hints on what is in the union.
3340 * @param unified_type Describe all possible type the union could handle.
3341 *
3342 * This macro lets you easily add an union with a member that specify what is inside.
3343 * The @p unified_type is an Eet_Data_Descriptor, but only the entry that match the name
3344 * returned by type_get will be used for each serialized data. The type_get and type_set
3345 * callback of unified_type should be defined.
3346 *
3347 * @since 1.2.4
3348 * @ingroup Eet_Data_Group
3349 * @see Eet_Data_Descriptor_Class
3350 */
3351#define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type) \
3352 do { \
3353 struct_type ___ett; \
3354 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, \
3355 (char *)(& (___ett.member)) - \
3356 (char *)(& (___ett)), \
3357 (char *)(& (___ett.type_member)) - \
3358 (char *)(& (___ett)), \
3359 NULL, unified_type); \
3360 } while (0)
3361
3362/**
3363 * Add a automatically selectable type to a data descriptor
3364 * @param edd The data descriptor to add the type to.
3365 * @param struct_type The type of the struct.
3366 * @param name The string name to use to encode/decode this member
3367 * (must be a constant global and never change).
3368 * @param member The struct member itself to be encoded.
3369 * @param type_member The member that give hints on what is in the union.
3370 * @param unified_type Describe all possible type the union could handle.
3371 *
3372 * This macro lets you easily define what the content of @p member points to depending of
3373 * the content of @p type_member. The type_get and type_set callback of unified_type should
3374 * be defined. If the the type is not know at the time of restoring it, eet will still call
3375 * type_set of @p unified_type but the pointer will be set to a serialized binary representation
3376 * of what eet know. This make it possible, to save this pointer again by just returning the string
3377 * given previously and telling it by setting unknow to EINA_TRUE.
3378 *
3379 * @since 1.2.4
3380 * @ingroup Eet_Data_Group
3381 * @see Eet_Data_Descriptor_Class
3382 */
3383#define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type) \
3384 do { \
3385 struct_type ___ett; \
3386 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT, \
3387 (char *)(& (___ett.member)) - \
3388 (char *)(& (___ett)), \
3389 (char *)(& (___ett.type_member)) - \
3390 (char *)(& (___ett)), \
3391 NULL, unified_type); \
3392 } while (0)
3393
3394/**
3395 * Add a mapping to a data descriptor that will be used by union, variant or inherited type
3396 * @param unified_type The data descriptor to add the mapping to.
3397 * @param name The string name to get/set type.
3398 * @param subtype The matching data descriptor.
3399 *
3400 * @since 1.2.4
3401 * @ingroup Eet_Data_Group
3402 * @see Eet_Data_Descriptor_Class
3403 */
3404#define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \
3405 eet_data_descriptor_element_add(unified_type, \
3406 name, \
3407 EET_T_UNKNOW, \
3408 EET_G_UNKNOWN, \
3409 0, \
3410 0, \
3411 NULL, \
3412 subtype)
3413
3414/**
3415 * @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers
3416 *
3417 * Most of the @ref Eet_Data_Group have alternative versions that
3418 * accounts for ciphers to protect their content.
3419 *
3420 * @see @ref Eet_Cipher_Group
3421 *
3422 * @ingroup Eet_Data_Group
3423 */
3424
3425/**
3426 * Read a data structure from an eet file and decodes it using a cipher.
3427 * @param ef The eet file handle to read from.
3428 * @param edd The data descriptor handle to use when decoding.
3429 * @param name The key the data is stored under in the eet file.
3430 * @param cipher_key The key to use as cipher.
3431 * @return A pointer to the decoded data structure.
3432 *
3433 * This function decodes a data structure stored in an eet file, returning
3434 * a pointer to it if it decoded successfully, or NULL on failure. This
3435 * can save a programmer dozens of hours of work in writing configuration
3436 * file parsing and writing code, as eet does all that work for the program
3437 * and presents a program-friendly data structure, just as the programmer
3438 * likes. Eet can handle members being added or deleted from the data in
3439 * storage and safely zero-fills unfilled members if they were not found
3440 * in the data. It checks sizes and headers whenever it reads data, allowing
3441 * the programmer to not worry about corrupt data.
3442 *
3443 * Once a data structure has been described by the programmer with the
3444 * fields they wish to save or load, storing or retrieving a data structure
3445 * from an eet file, or from a chunk of memory is as simple as a single
3446 * function call.
3447 *
3448 * @see eet_data_read()
3449 *
3450 * @since 1.0.0
3451 * @ingroup Eet_Data_Cipher_Group
3452 */
3453EAPI void *
3454eet_data_read_cipher(Eet_File *ef,
3455 Eet_Data_Descriptor *edd,
3456 const char *name,
3457 const char *cipher_key);
3458
3459/**
3460 * Read a data structure from an eet extended attribute and decodes it using a cipher.
3461 * @param filename The file to extract the extended attribute from.
3462 * @param attribute The attribute to get the data from.
3463 * @param edd The data descriptor handle to use when decoding.
3464 * @param cipher_key The key to use as cipher.
3465 * @return A pointer to the decoded data structure.
3466 *
3467 * This function decodes a data structure stored in an eet extended attribute,
3468 * returning a pointer to it if it decoded successfully, or NULL on failure.
3469 * Eet can handle members being added or deleted from the data in
3470 * storage and safely zero-fills unfilled members if they were not found
3471 * in the data. It checks sizes and headers whenever it reads data, allowing
3472 * the programmer to not worry about corrupt data.
3473 *
3474 * Once a data structure has been described by the programmer with the
3475 * fields they wish to save or load, storing or retrieving a data structure
3476 * from an eet file, from a chunk of memory or from an extended attribute
3477 * is as simple as a single function call.
3478 *
3479 * @since 1.5.0
3480 * @ingroup Eet_Data_Cipher_Group
3481 */
3482EAPI void *
3483eet_data_xattr_cipher_get(const char *filename,
3484 const char *attribute,
3485 Eet_Data_Descriptor *edd,
3486 const char *cipher_key);
3487
3488/**
3489 * Write a data structure from memory and store in an eet file
3490 * using a cipher.
3491 * @param ef The eet file handle to write to.
3492 * @param edd The data descriptor to use when encoding.
3493 * @param name The key to store the data under in the eet file.
3494 * @param cipher_key The key to use as cipher.
3495 * @param data A pointer to the data structure to save and encode.
3496 * @param compress Compression flags for storage.
3497 * @return bytes written on successful write, 0 on failure.
3498 *
3499 * This function is the reverse of eet_data_read_cipher(), saving a data structure
3500 * to an eet file.
3501 *
3502 * @since 1.0.0
3503 * @ingroup Eet_Data_Cipher_Group
3504 */
3505EAPI int
3506eet_data_write_cipher(Eet_File *ef,
3507 Eet_Data_Descriptor *edd,
3508 const char *name,
3509 const char *cipher_key,
3510 const void *data,
3511 int compress);
3512
3513/**
3514 * Write a data structure from memory and store in an eet extended attribute
3515 * using a cipher.
3516 * @param filename The file to write the extended attribute to.
3517 * @param attribute The attribute to store the data to.
3518 * @param edd The data descriptor to use when encoding.
3519 * @param cipher_key The key to use as cipher.
3520 * @param data A pointer to the data structure to save and encode.
3521 * @param flags The policy to use when setting the data.
3522 * @return EINA_TRUE on success, EINA_FALSE on failure.
3523 *
3524 * This function is the reverse of eet_data_xattr_cipher_get(), saving a data structure
3525 * to an eet extended attribute.
3526 *
3527 * @since 1.5.0
3528 * @ingroup Eet_Data_Cipher_Group
3529 */
3530EAPI Eina_Bool
3531eet_data_xattr_cipher_set(const char *filename,
3532 const char *attribute,
3533 Eet_Data_Descriptor *edd,
3534 const char *cipher_key,
3535 const void *data,
3536 Eina_Xattr_Flags flags);
3537
3538/**
3539 * Dump an eet encoded data structure into ascii text using a cipher.
3540 * @param data_in The pointer to the data to decode into a struct.
3541 * @param cipher_key The key to use as cipher.
3542 * @param size_in The size of the data pointed to in bytes.
3543 * @param dumpfunc The function to call passed a string when new
3544 * data is converted to text
3545 * @param dumpdata The data to pass to the @p dumpfunc callback.
3546 * @return 1 on success, 0 on failure
3547 *
3548 * This function will take a chunk of data encoded by
3549 * eet_data_descriptor_encode() and convert it into human readable
3550 * ascii text. It does this by calling the @p dumpfunc callback
3551 * for all new text that is generated. This callback should append
3552 * to any existing text buffer and will be passed the pointer @p
3553 * dumpdata as a parameter as well as a string with new text to be
3554 * appended.
3555 *
3556 * Example:
3557 *
3558 * @code
3559 * void output(void *data, const char *string)
3560 * {
3561 * printf("%s", string);
3562 * }
3563 *
3564 * void dump(const char *file)
3565 * {
3566 * FILE *f;
3567 * int len;
3568 * void *data;
3569 *
3570 * f = fopen(file, "r");
3571 * fseek(f, 0, SEEK_END);
3572 * len = ftell(f);
3573 * rewind(f);
3574 * data = malloc(len);
3575 * fread(data, len, 1, f);
3576 * fclose(f);
3577 * eet_data_text_dump_cipher(data, cipher_key, len, output, NULL);
3578 * }
3579 * @endcode
3580 *
3581 * @see eet_data_text_dump()
3582 *
3583 * @since 1.0.0
3584 * @ingroup Eet_Data_Cipher_Group
3585 */
3586EAPI int
3587eet_data_text_dump_cipher(const void *data_in,
3588 const char *cipher_key,
3589 int size_in,
3590 Eet_Dump_Callback dumpfunc,
3591 void *dumpdata);
3592
3593/**
3594 * Take an ascii encoding from eet_data_text_dump() and re-encode
3595 * in binary using a cipher.
3596 * @param text The pointer to the string data to parse and encode.
3597 * @param cipher_key The key to use as cipher.
3598 * @param textlen The size of the string in bytes (not including 0
3599 * byte terminator).
3600 * @param size_ret This gets filled in with the encoded data blob
3601 * size in bytes.
3602 * @return The encoded data on success, NULL on failure.
3603 *
3604 * This function will parse the string pointed to by @p text and return
3605 * an encoded data lump the same way eet_data_descriptor_encode() takes an
3606 * in-memory data struct and encodes into a binary blob. @p text is a normal
3607 * C string.
3608 *
3609 * @see eet_data_text_undump()
3610 *
3611 * @since 1.0.0
3612 * @ingroup Eet_Data_Cipher_Group
3613 */
3614EAPI void *
3615eet_data_text_undump_cipher(const char *text,
3616 const char *cipher_key,
3617 int textlen,
3618 int *size_ret);
3619
3620/**
3621 * Dump an eet encoded data structure from an eet file into ascii
3622 * text using a cipher.
3623 * @param ef A valid eet file handle.
3624 * @param name Name of the entry. eg: "/base/file_i_want".
3625 * @param cipher_key The key to use as cipher.
3626 * @param dumpfunc The function to call passed a string when new
3627 * data is converted to text
3628 * @param dumpdata The data to pass to the @p dumpfunc callback.
3629 * @return 1 on success, 0 on failure
3630 *
3631 * This function will take an open and valid eet file from
3632 * eet_open() request the data encoded by
3633 * eet_data_descriptor_encode() corresponding to the key @p name
3634 * and convert it into human readable ascii text. It does this by
3635 * calling the @p dumpfunc callback for all new text that is
3636 * generated. This callback should append to any existing text
3637 * buffer and will be passed the pointer @p dumpdata as a parameter
3638 * as well as a string with new text to be appended.
3639 *
3640 * @see eet_data_dump()
3641 *
3642 * @since 1.0.0
3643 * @ingroup Eet_Data_Cipher_Group
3644 */
3645EAPI int
3646eet_data_dump_cipher(Eet_File *ef,
3647 const char *name,
3648 const char *cipher_key,
3649 Eet_Dump_Callback dumpfunc,
3650 void *dumpdata);
3651
3652/**
3653 * Take an ascii encoding from eet_data_dump() and re-encode in
3654 * binary using a cipher.
3655 * @param ef A valid eet file handle.
3656 * @param name Name of the entry. eg: "/base/file_i_want".
3657 * @param cipher_key The key to use as cipher.
3658 * @param text The pointer to the string data to parse and encode.
3659 * @param textlen The size of the string in bytes (not including 0
3660 * byte terminator).
3661 * @param compress Compression flags (1 == compress, 0 = don't compress).
3662 * @return 1 on success, 0 on failure
3663 *
3664 * This function will parse the string pointed to by @p text,
3665 * encode it the same way eet_data_descriptor_encode() takes an
3666 * in-memory data struct and encodes into a binary blob.
3667 *
3668 * The data (optionally compressed) will be in ram, pending a flush to
3669 * disk (it will stay in ram till the eet file handle is closed though).
3670 *
3671 * @see eet_data_undump()
3672 *
3673 * @since 1.0.0
3674 * @ingroup Eet_Data_Cipher_Group
3675 */
3676EAPI int
3677eet_data_undump_cipher(Eet_File *ef,
3678 const char *name,
3679 const char *cipher_key,
3680 const char *text,
3681 int textlen,
3682 int compress);
3683
3684/**
3685 * Decode a data structure from an arbitrary location in memory
3686 * using a cipher.
3687 * @param edd The data descriptor to use when decoding.
3688 * @param data_in The pointer to the data to decode into a struct.
3689 * @param cipher_key The key to use as cipher.
3690 * @param size_in The size of the data pointed to in bytes.
3691 * @return NULL on failure, or a valid decoded struct pointer on success.
3692 *
3693 * This function will decode a data structure that has been encoded using
3694 * eet_data_descriptor_encode(), and return a data structure with all its
3695 * elements filled out, if successful, or NULL on failure.
3696 *
3697 * The data to be decoded is stored at the memory pointed to by @p data_in,
3698 * and is described by the descriptor pointed to by @p edd. The data size is
3699 * passed in as the value to @p size_in, ande must be greater than 0 to
3700 * succeed.
3701 *
3702 * This function is useful for decoding data structures delivered to the
3703 * application by means other than an eet file, such as an IPC or socket
3704 * connection, raw files, shared memory etc.
3705 *
3706 * Please see eet_data_read() for more information.
3707 *
3708 * @see eet_data_descriptor_decode()
3709 *
3710 * @since 1.0.0
3711 * @ingroup Eet_Data_Cipher_Group
3712 */
3713EAPI void *
3714eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd,
3715 const void *data_in,
3716 const char *cipher_key,
3717 int size_in);
3718
3719/**
3720 * Encode a data struct to memory and return that encoded data
3721 * using a cipher.
3722 * @param edd The data descriptor to use when encoding.
3723 * @param data_in The pointer to the struct to encode into data.
3724 * @param cipher_key The key to use as cipher.
3725 * @param size_ret pointer to the an int to be filled with the decoded size.
3726 * @return NULL on failure, or a valid encoded data chunk on success.
3727 *
3728 * This function takes a data structutre in memory and encodes it into a
3729 * serialised chunk of data that can be decoded again by
3730 * eet_data_descriptor_decode(). This is useful for being able to transmit
3731 * data structures across sockets, pipes, IPC or shared file mechanisms,
3732 * without having to worry about memory space, machine type, endianess etc.
3733 *
3734 * The parameter @p edd must point to a valid data descriptor, and
3735 * @p data_in must point to the right data structure to encode. If not, the
3736 * encoding may fail.
3737 *
3738 * On success a non NULL valid pointer is returned and what @p size_ret
3739 * points to is set to the size of this decoded data, in bytes. When the
3740 * encoded data is no longer needed, call free() on it. On failure NULL is
3741 * returned and what @p size_ret points to is set to 0.
3742 *
3743 * Please see eet_data_write() for more information.
3744 *
3745 * @see eet_data_descriptor_encode()
3746 *
3747 * @since 1.0.0
3748 * @ingroup Eet_Data_Cipher_Group
3749 */
3750EAPI void *
3751eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd,
3752 const void *data_in,
3753 const char *cipher_key,
3754 int *size_ret);
3755
3756/**
3757 * @defgroup Eet_Node_Group Low-level Serialization Structures.
3758 *
3759 * Functions that create, destroy and manipulate serialization nodes
3760 * used by @ref Eet_Data_Group.
3761 *
3762 * @{
3763 */
3764
3765/**
3766 * @typedef Eet_Node
3767 * Opaque handle to manage serialization node.
3768 */
3769typedef struct _Eet_Node Eet_Node;
3770
3771/**
3772 * @typedef Eet_Node_Data
3773 * Contains an union that can fit any kind of node.
3774 */
3775typedef struct _Eet_Node_Data Eet_Node_Data;
3776
3777/**
3778 * @struct _Eet_Node_Data
3779 * Contains an union that can fit any kind of node.
3780 */
3781struct _Eet_Node_Data
3782{
3783 union {
3784 char c;
3785 short s;
3786 int i;
3787 long long l;
3788 float f;
3789 double d;
3790 unsigned char uc;
3791 unsigned short us;
3792 unsigned int ui;
3793 unsigned long long ul;
3794 const char *str;
3795 } value;
3796};
3797
3798/**
3799 * @}
3800 */
3801
3802/**
3803 * TODO FIX ME
3804 * @ingroup Eet_Node_Group
3805 */
3806EAPI Eet_Node *
3807eet_node_char_new(const char *name,
3808 char c);
3809
3810/**