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