1 /** 2 @brief Eet Data Handling Library Public API Calls. 3 4 These routines are used for Eet Library interaction. 5 6 @page eet_main Eet 7 8 @date 2000 (created) 9 10 @section eet_toc Table of Contents 11 12 @li @ref eet_main_intro 13 @li @ref eet_main_compiling 14 @li @ref eet_main_next_steps 15 @li @ref eet_main_intro_example 16 17 @section eet_main_intro Introduction 18 19 It is a tiny library designed to write an arbitrary set of chunks of data 20 to a file and optionally compress each chunk (very much like a zip file) 21 and allow fast random-access reading of the file later on. It does not 22 do zip as a zip itself has more complexity than is needed, and it was much 23 simpler to implement this once here. 24 25 Eet is extremely fast, small and simple. Eet files can be very small and 26 highly compressed, making them very optimal for just sending across the 27 internet without having to archive, compress or decompress and install them. 28 They allow for lightning-fast random-access reads once created, making them 29 perfect for storing data that is written once (or rarely) and read many 30 times, but the program does not want to have to read it all in at once. 31 32 It also can encode and decode data structures in memory, as well as image 33 data for saving to Eet files or sending across the network to other 34 machines, or just writing to arbitrary files on the system. All data is 35 encoded in a platform independent way and can be written and read by any 36 architecture. 37 38 @section eet_main_compiling How to compile 39 40 Eet is a library your application links to. The procedure for this is very 41 simple. You simply have to compile your application with the appropriate 42 compiler flags that the @p pkg-config script outputs. For example: 43 44 Compiling C or C++ files into object files: 45 46 @verbatim 47 gcc -c -o main.o main.c `pkg-config --cflags eet` 48 @endverbatim 49 50 Linking object files into a binary executable: 51 52 @verbatim 53 gcc -o my_application main.o `pkg-config --libs eet` 54 @endverbatim 55 56 See @ref pkgconfig 57 58 @section eet_main_next_steps Next Steps 59 60 After you understood what Eet is and installed it in your system 61 you should proceed understanding the programming interface. We'd 62 recommend you to take a while to learn @ref Eina as it is very 63 convenient and optimized, and Eet provides integration with it. 64 65 Recommended reading: 66 67 @li @ref Eet_File_Group to know the basics to open and save files. 68 @li @ref Eet_Data_Group to know the convenient way to serialize and 69 parse your data structures automatically. Just create your 70 descriptors and let Eet do the work for you. 71 72 @section eet_main_intro_example Introductory Examples 73 74 Here is a simple example on how to use Eet to save a series of strings to a 75 file and load them again. The advantage of using Eet over just 76 fprintf() and 77 fscanf() is that not only can these entries be strings, they need no special 78 parsing to handle delimiter characters or escaping, they can be binary data, 79 image data, data structures containing integers, strings, other data 80 structures, linked lists and much more, without the programmer having to 81 worry about parsing, and best of all, Eet is very fast. 82 83 This is just a very simple example that doesn't show all of the capabilities 84 of Eet, but it serves to illustrate its simplicity. 85 86 @include eet-basic.c 87 88 More examples can be found at @ref eet_examples. 89 90 @todo Document data format for images and data structures. 91 92 */ 93 94 #ifndef _EET_H 95 #define _EET_H 96 97 #include <stdlib.h> 98 #include <stdio.h> 99 #include <Efl_Config.h> 100 #include <Eina.h> 101 #include <Emile.h> 102 103 #ifdef EAPI 104 # undef EAPI 105 #endif 106 107 #ifdef _WIN32 108 # ifdef EFL_BUILD 109 # ifdef DLL_EXPORT 110 # define EAPI __declspec(dllexport) 111 # else 112 # define EAPI 113 # endif 114 # else 115 # define EAPI __declspec(dllimport) 116 # endif 117 #else 118 # ifdef __GNUC__ 119 # if __GNUC__ >= 4 120 # define EAPI __attribute__ ((visibility("default"))) 121 # else 122 # define EAPI 123 # endif 124 # else 125 # define EAPI 126 # endif 127 #endif 128 129 #ifdef __cplusplus 130 extern "C" { 131 #endif /* ifdef __cplusplus */ 132 133 /** 134 * @file Eet.h 135 * @brief The file that provides the eet functions. 136 * 137 * This header provides the Eet management functions. 138 * 139 */ 140 141 /** 142 * @def EET_VERSION_MAJOR 143 * The major number of eet version. 144 */ 145 #define EET_VERSION_MAJOR EFL_VERSION_MAJOR 146 /** 147 * @def EET_VERSION_MINOR 148 * The minor number of eet version. 149 */ 150 #define EET_VERSION_MINOR EFL_VERSION_MINOR 151 /** 152 * @typedef Eet_Version 153 * 154 * This is the Eet version information structure that can be used at 155 * runtime to detect which version of eet is being used and adapt 156 * appropriately as follows for example: 157 * 158 * @code 159 * #if defined(EET_VERSION_MAJOR) && (EET_VERSION_MAJOR >= 1) && defined(EET_VERSION_MINOR) && (EET_VERSION_MINOR > 2) 160 * printf("Eet version: %i.%i.%i\n", 161 * eet_version->major, 162 * eet_version->minor, 163 * eet_version->micro); 164 * if (eet_version->revision > 0) 165 * { 166 * printf(" Built from SVN revision # %i\n", eet_version->revision); 167 * } 168 * #endif 169 * @endcode 170 * 171 * Note the \#if check can be dropped if your program refuses to compile or 172 * work with an Eet version less than 1.3.0. 173 */ 174 typedef struct _Eet_Version 175 { 176 int major; /** < major (binary or source incompatible changes) */ 177 int minor; /** < minor (new features, bugfixes, major improvements version) */ 178 int micro; /** < micro (bugfix, internal improvements, no new features version) */ 179 int revision; /** < svn revision (0 if a proper release or the svn revision number Eet is built from) */ 180 } Eet_Version; 181 182 183 /** 184 * @defgroup Eet_Group Top level functions 185 * @ingroup Eet 186 * Functions that affect Eet as a whole. 187 * 188 * @{ 189 */ 190 191 /** 192 * Eet Version Information 193 */ 194 EAPI extern Eet_Version *eet_version; 195 196 /** 197 * @enum _Eet_Error 198 * All the error identifiers known by Eet. 199 */ 200 typedef enum _Eet_Error 201 { 202 EET_ERROR_NONE, /**< No error, it's all fine! */ 203 EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */ 204 EET_ERROR_EMPTY, /**< There was nothing to do */ 205 EET_ERROR_NOT_WRITABLE, /**< Could not write to file or file is #EET_FILE_MODE_READ */ 206 EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */ 207 EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */ 208 EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it is too big */ 209 EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write due a generic Input/Output error */ 210 EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of space */ 211 EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */ 212 EET_ERROR_MMAP_FAILED, /**< Could not mmap file */ 213 EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */ 214 EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */ 215 EET_ERROR_INVALID_SIGNATURE, /**< Signature is invalid */ 216 EET_ERROR_NOT_SIGNED, /**< File or contents are not signed */ 217 EET_ERROR_NOT_IMPLEMENTED, /**< Function is not implemented */ 218 EET_ERROR_PRNG_NOT_SEEDED, /**< Could not introduce random seed */ 219 EET_ERROR_ENCRYPT_FAILED, /**< Could not encrypt contents */ 220 EET_ERROR_DECRYPT_FAILED /**< Could not decrypt contents */ 221 } Eet_Error; /**< Eet error identifiers */ 222 223 /** 224 * @} 225 */ 226 227 /** 228 * @defgroup Eet_Compression Eet Compression Levels 229 * @ingroup Eet 230 * Compression modes/levels supported by Eet. 231 * 232 * @{ 233 */ 234 235 /** 236 * @enum _Eet_Compression 237 * All the compression modes known by Eet. 238 */ 239 240 typedef enum _Eet_Compression 241 { 242 EET_COMPRESSION_NONE = 0, /**< No compression at all @since 1.7 */ 243 EET_COMPRESSION_DEFAULT = 1, /**< Default compression (Zlib) @since 1.7 */ 244 EET_COMPRESSION_LOW = 2, /**< Fast but minimal compression (Zlib) @since 1.7 */ 245 EET_COMPRESSION_MED = 6, /**< Medium compression level (Zlib) @since 1.7 */ 246 EET_COMPRESSION_HI = 9, /**< Slow but high compression level (Zlib) @since 1.7 */ 247 EET_COMPRESSION_VERYFAST = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */ 248 EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST) (LZ4) @since 1.7 */ 249 250 EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Don't use it @since 1.7 */ 251 EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Don't use it @since 1.7 */ 252 EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Don't use it @since 1.7 */ 253 EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Don't use it @since 1.7 */ 254 EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Don't use it @since 1.7 */ 255 } Eet_Compression; /**< Eet compression modes @since 1.7 */ 256 257 /** 258 * @} 259 */ 260 261 /** 262 * @ingroup Eet_Group 263 * @brief Initializes the EET library. 264 * 265 * The first time this function is called, it will perform all the internal 266 * initialization required for the library to function properly and increment 267 * the initialization counter. Any subsequent call only increment this counter 268 * and return its new value, so it's safe to call this function more than once. 269 * 270 * @return The new init count. Will be @c 0 if initialization failed. 271 * 272 * @since 1.0.0 273 */ 274 EAPI int 275 eet_init(void); 276 277 /** 278 * @ingroup Eet_Group 279 * @brief Shuts down the EET library. 280 * 281 * If eet_init() was called more than once for the running application, 282 * eet_shutdown() will decrement the initialization counter and return its 283 * new value, without doing anything else. When the counter reaches 0, all 284 * of the internal elements will be shutdown and any memory used freed. 285 * 286 * @return The new init count. 287 * 288 * @since 1.0.0 289 */ 290 EAPI int 291 eet_shutdown(void); 292 293 /** 294 * @ingroup Eet_Group 295 * @brief Clears eet cache. 296 * 297 * For a faster access to previously accessed data, Eet keeps an internal 298 * cache of files. These files will be freed automatically only when 299 * they are unused and the cache gets full, in order based on the last time 300 * they were used. 301 * On systems with little memory this may present an unnecessary constraint, 302 * so eet_clearcache() is available for users to reclaim the memory used by 303 * files that are no longer needed. Those that were open using 304 * ::EET_FILE_MODE_WRITE or ::EET_FILE_MODE_READ_WRITE and have modifications, 305 * will be written down to disk before flushing them from memory. 306 * 307 * @since 1.0.0 308 */ 309 EAPI void 310 eet_clearcache(void); 311 312 /** 313 * @defgroup Eet_File_Group Eet File Main Functions 314 * @ingroup Eet 315 * 316 * Functions to create, destroy and do basic manipulation of 317 * #Eet_File handles. 318 * 319 * This section explains how to use the most basic Eet functions, which 320 * are used to work with eet files, read data from them, store it back in or 321 * take a look at what entries it contains, without making use of the 322 * serialization capabilities explained in @ref Eet_Data_Group. 323 * 324 * The following example will serve as an introduction to most, if not all, 325 * of these functions. 326 * 327 * If you are only using Eet, this is the only header you need to include. 328 * @dontinclude eet-file.c 329 * @skipline Eet.h 330 * 331 * Now let's create ourselves an eet file to play with. The following function 332 * shows step by step how to open a file and write some data in it. 333 * First, we define our file handler and some other things we'll put in it. 334 * @line static int 335 * @skip Eet_File 336 * @until "; 337 * @skip eet_open 338 * 339 * We open a new file in write mode, and if it fails, we just return, since 340 * there's not much more we can do about it.. 341 * @until return 342 * 343 * Now, we need to write some data in our file. For now, strings will suffice, 344 * so let's just dump a bunch of them in there. 345 * @until } 346 * 347 * As you can see, we copied a string into our static buffer, which is a bit 348 * bigger than the full length of the string, and then told Eet to write it 349 * into the file, compressed, returning the size of the data written into the 350 * file. 351 * This is all to show that Eet treats data as just data. It doesn't matter 352 * what that data represents (for now), it's all just bytes for it. As running 353 * the following code will show, we took a string of around 30 bytes and put it 354 * in a buffer of 1024 bytes, but the returned size won't be any of those. 355 * @until printf 356 * 357 * Next, we copy into our buffer our set of strings, including their null 358 * terminators and write them into the file. No error checking for the sake 359 * of brevity. And a call to eet_sync() to make sure all out data is 360 * properly written down to disk, even though we haven't yet closed the file. 361 * @until eet_sync 362 * 363 * One more write, this time our large array of binary data and... well, I 364 * couldn't come up with a valid use of the last set of strings we stored, 365 * so let's take it out from the file with eet_delete(). 366 * @until eet_delete 367 * 368 * Finally, we close the file, saving any changes back to disk and return. 369 * Notice how, if there's any error closing the file or saving its contents, 370 * the return value from the function will be a false one, which later on 371 * will make the program exit with an error code. 372 * @until return 373 * 374 * Moving onto our main function, we will open the same file and read it back. 375 * Trivial, but it'll show how we can do so in more than one way. We'll skip 376 * the variable declarations, as they aren't very different from what we've 377 * seen already. 378 * 379 * We start from the beginning by initializing Eet so things in general work. 380 * Forgetting to do so will result in weird results or crashes when calling 381 * any eet function, so if you experience something like that, the first thing 382 * to look at is whether eet_init() is missing. 383 * Then we call our @p create_eet_file function, described above, to make 384 * sure we have something to work with. If the function fails it will return 385 * 0 and we just exit, since nothing from here onwards will work anyway. 386 * @skip eet_init 387 * @until return 388 * 389 * Let's take a look now at what entries our file has. For this, we use 390 * eet_list(), which will return a list of strings, each being the name of 391 * one entry. Since we skipped before, it may be worth noting that @p list 392 * is declared as a @p char **. 393 * The @p num parameter will, of course, have the number of entries contained 394 * in our file. 395 * If everything's fine, we'll get our list and print it to the screen, and 396 * once done with it, we free the list. That's just the list, not its contents, 397 * as they are internal strings used by Eet and trying to free them will surely 398 * break things. 399 * @until } 400 * 401 * Reading back plain data is simple. Just a call to eet_read() with the file 402 * to read from, and the name of the entry we are interested in. We get back 403 * our data and the passed @p size parameter will contain the size of it. If 404 * the data was stored compressed, it will decompressed first. 405 * @until } 406 * 407 * Another simple read for the set of strings from before, except those were 408 * deleted, so we should get a NULL return and continue normally. 409 * @until } 410 * 411 * Finally, we'll get our binary data in the same way we got the strings. Once 412 * again, it makes no difference for Eet what the data is, it's up to us to 413 * know how to handle it. 414 * @until { 415 * 416 * Now some cheating, we know that this data is an Eet file because, well... 417 * we just know it. So we are going to open it and take a look at its insides. 418 * For this, eet_open() won't work, as it needs to have a file on disk to read 419 * from and all we have is some data in RAM. 420 * 421 * So how do we do? One way would be to create a normal file and write down 422 * our data, then open it with eet_open(). Another, faster and more efficient 423 * if all we want to do is read the file, is to use eet_memopen_read(). 424 * @until memopen 425 * 426 * As you can see, the size we got from our previous read was put to good use 427 * this time. Unlike the first one where all we had were strings, the size 428 * of the data read only serves to demonstrate that we are reading back the 429 * entire size of our original @p buf variable. 430 * 431 * A little peeking to see how many entries the file has and to make an 432 * example of eet_num_entries() to get that number when we don't care about 433 * their names. 434 * @until printf 435 * 436 * More cheating follows. Just like we knew this was an Eet file, we also know 437 * what key to read from, and on top of that we know that the data in it is not 438 * compressed. 439 * Knowing all this allows us to take some shortcuts. 440 * @until read_direct 441 * 442 * That's a direct print of our data, whatever that data is. We don't want 443 * to worry about having to free it later, so we just used eet_direct_read() 444 * to tell Eet to gives a pointer to the internal data in the file, without 445 * duplicating it. Since we said that data was not compressed, we shouldn't 446 * worry about printing garbage to the screen (and yes, we also know the data 447 * is yet another string). 448 * We also don't care about the size of the data as it was stored in the file, 449 * so we passed NULL as the size parameter. 450 * One very important note about this, however, is that we don't care about 451 * the size parameter because the data in the file contains the null 452 * terminator for the string. So when using Eet to store strings this way, 453 * it's very important to consider whether you will keep that final null 454 * byte, or to always get the size read and do the necessary checks and copies. 455 * It's up to the user and the particular use cases to decide how this will 456 * be done. 457 * 458 * With everything done, close this second file and free the data used to open 459 * it. And this is important, we can't free that data until we are done with 460 * the file, as Eet is using it. When opening with eet_memopen_read(), the data 461 * passed to it must be available for as long as the the file is open. 462 * @until } 463 * 464 * Finally, we close the first file, shutdown all internal resources used by 465 * Eet and leave our main function, thus terminating our program. 466 * @until return 467 * 468 * You can look at the full code of the example @ref eet-file.c "here". 469 * @{ 470 */ 471 472 /** 473 * @enum _Eet_File_Mode 474 * Modes that a file can be opened. 475 */ 476 typedef enum _Eet_File_Mode 477 { 478 EET_FILE_MODE_INVALID = -1, 479 EET_FILE_MODE_READ, /**< File is read-only. */ 480 EET_FILE_MODE_WRITE, /**< File is write-only. */ 481 EET_FILE_MODE_READ_WRITE /**< File is for both read and write */ 482 } Eet_File_Mode; /**< Modes that a file can be opened. */ 483 484 /** 485 * @typedef Eet_Image_Encoding 486 * Specify lossy encoding for image 487 * @since 1.10 488 */ 489 typedef Emile_Image_Encoding Eet_Image_Encoding; 490 491 #define EET_IMAGE_LOSSLESS EMILE_IMAGE_LOSSLESS 492 #define EET_IMAGE_JPEG EMILE_IMAGE_JPEG 493 #define EET_IMAGE_ETC1 EMILE_IMAGE_ETC1 494 #define EET_IMAGE_ETC2_RGB EMILE_IMAGE_ETC2_RGB 495 #define EET_IMAGE_ETC2_RGBA EMILE_IMAGE_ETC2_RGBA 496 #define EET_IMAGE_ETC1_ALPHA EMILE_IMAGE_ETC1_ALPHA 497 498 /** 499 * @typedef Eet_Colorspace 500 * Specify colorspace for image 501 * @since 1.10 502 */ 503 typedef Emile_Colorspace Eet_Colorspace; 504 505 #define EET_COLORSPACE_ARGB8888 EMILE_COLORSPACE_ARGB8888 506 #define EET_COLORSPACE_GRY8 EMILE_COLORSPACE_GRY8 507 #define EET_COLORSPACE_AGRY88 EMILE_COLORSPACE_AGRY88 508 #define EET_COLORSPACE_ETC1 EMILE_COLORSPACE_ETC1 509 #define EET_COLORSPACE_RGB8_ETC2 EMILE_COLORSPACE_RGB8_ETC2 510 #define EET_COLORSPACE_RGBA8_ETC2_EAC EMILE_COLORSPACE_RGBA8_ETC2_EAC 511 #define EET_COLORSPACE_ETC1_ALPHA EMILE_COLORSPACE_ETC1_ALPHA 512 513 /** 514 * @typedef Eet_File 515 * Opaque handle that defines an Eet file (or memory). 516 * 517 * This handle will be returned by the functions eet_open() and 518 * eet_memopen_read() and is used by every other function that affects the 519 * file in any way. When you are done with it, call eet_close() to close it 520 * and, if the file was open for writing, write down to disk any changes made 521 * to it. 522 * 523 * @see eet_open() 524 * @see eet_memopen_read() 525 * @see eet_close() 526 */ 527 typedef struct _Eet_File Eet_File; 528 529 /** 530 * @typedef Eet_Dictionary 531 * Opaque handle that defines a file-backed (mmaped) dictionary of strings. 532 */ 533 typedef struct _Eet_Dictionary Eet_Dictionary; 534 535 /** 536 * @typedef Eet_Entry 537 * Eet files may contains multiple Entries per file, this handle describe them. You can get that handle from an iterator given by eet_list_entries(). 538 * 539 * @see eet_list_entries() 540 * @since 1.8.0 541 */ 542 typedef struct _Eet_Entry Eet_Entry; 543 struct _Eet_Entry 544 { 545 const char *name; /**< The entry name */ 546 547 int offset; /**< Where it start in the file */ 548 int size; /**< The size on disk */ 549 int data_size; /**< The decompressed size if relevant */ 550 551 Eina_Bool compression; /**< Is this data compressed ? */ 552 Eina_Bool ciphered; /**< Is it ciphered ? */ 553 Eina_Bool alias; /**< Is it an alias ? */ 554 }; 555 556 /** 557 * @} 558 */ 559 560 /** 561 * @ingroup Eet_File_Group 562 * @brief Opens an eet file on disk, and returns a handle to it. 563 * @param file The file path to the eet file. eg: @c "/tmp/file.eet". 564 * @param mode The mode for opening. Either #EET_FILE_MODE_READ, 565 * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE. 566 * @return An opened eet file handle. 567 * 568 * This function will open an exiting eet file for reading, and build 569 * the directory table in memory and return a handle to the file, if it 570 * exists and can be read, and no memory errors occur on the way, otherwise 571 * NULL will be returned. 572 * 573 * It will also open an eet file for writing. This will, if successful, 574 * delete the original file and replace it with a new empty file, till 575 * the eet file handle is closed or flushed. If it cannot be opened for 576 * writing or a memory error occurs, NULL is returned. 577 * 578 * You can also open the file for read/write. If you then write a key that 579 * does not exist it will be created, if the key exists it will be replaced 580 * by the new data. 581 * 582 * If the same file is opened multiple times, then the same file handle will 583 * be returned as eet maintains an internal list of all currently open 584 * files. Note that it considers files opened for read only and those opened 585 * for read/write and write only as 2 separate sets. Those that do not write 586 * to the file and those that do. Eet will allow 2 handles to the same file 587 * if they are in the 2 separate lists/groups. That means opening a file for 588 * read only looks in the read only set, and returns a handle to that file 589 * handle and increments its reference count. If you open a file for read/write 590 * or write only it looks in the write set and returns a handle after 591 * incrementing the reference count. You need to close an eet file handle 592 * as many times as it has been opened to maintain correct reference counts. 593 * Files whose modified timestamp or size do not match those of the existing 594 * referenced file handles will not be returned and a new handle will be 595 * returned instead. 596 * 597 * @since 1.0.0 598 */ 599 EAPI Eet_File * 600 eet_open(const char *file, 601 Eet_File_Mode mode); 602 603 /** 604 * @ingroup Eet_File_Group 605 * @brief Opens an eet file on disk from an Eina_File handle, and returns a handle to it. 606 * @param file The Eina_File handle to map to an eet file. 607 * @return An opened eet file handle. 608 * 609 * This function will open an exiting eet file for reading, and build 610 * the directory table in memory and return a handle to the file, if it 611 * exists and can be read, and no memory errors occur on the way, otherwise 612 * NULL will be returned. 613 * 614 * This function can't open file for writing only read only mode is supported for now. 615 * 616 * If the same file is opened multiple times, then the same file handle will 617 * be returned as eet maintains an internal list of all currently open 618 * files. That means opening a file for read only looks in the read only set, 619 * and returns a handle to that file handle and increments its reference count. 620 * You need to close an eet file handle as many times as it has been opened to 621 * maintain correct reference counts. 622 * 623 * @since 1.8.0 624 */ 625 EAPI Eet_File * 626 eet_mmap(const Eina_File *file); 627 628 /** 629 * @ingroup Eet_File_Group 630 * Opens an eet file directly from a memory location. The data is not copied, 631 * so you must keep it around as long as the eet file is open. There is 632 * currently no cache for this kind of Eet_File, so it's reopened every time 633 * you use eet_memopen_read. 634 * @param data Address of file in memory. 635 * @param size Size of memory to be read. 636 * @return A handle to the file. 637 * 638 * Files opened this way will always be in read-only mode. 639 * 640 * @since 1.1.0 641 */ 642 EAPI Eet_File * 643 eet_memopen_read(const void *data, 644 size_t size); 645 646 /** 647 * @ingroup Eet_File_Group 648 * @brief Gets the mode an Eet_File was opened with. 649 * @param ef A valid eet file handle. 650 * @return The mode ef was opened with. 651 * 652 * @since 1.0.0 653 */ 654 EAPI Eet_File_Mode 655 eet_mode_get(Eet_File *ef); 656 657 /** 658 * @ingroup Eet_File_Group 659 * @brief Closes an eet file handle and flush pending writes. 660 * @param ef A valid eet file handle. 661 * @return An eet error identifier. 662 * 663 * This function will flush any pending writes to disk if the eet file 664 * was opened for write, and free all data associated with the file handle 665 * and file, and close the file. If it was opened for read (or read/write), 666 * the file handle may still be held open internally for caching purposes. 667 * To flush speculatively held eet file handles use eet_clearcache(). 668 * 669 * If the eet file handle is not valid nothing will be done. 670 * 671 * @since 1.0.0 672 * 673 * @see eet_clearcache() 674 */ 675 EAPI Eet_Error 676 eet_close(Eet_File *ef); 677 678 /** 679 * @ingroup Eet_File_Group 680 * @brief Syncs content of an eet file handle, flushing pending writes. 681 * @param ef A valid eet file handle. 682 * @return An eet error identifier. 683 * 684 * This function will flush any pending writes to disk. The eet file must 685 * be opened for write. 686 * 687 * If the eet file handle is not valid nothing will be done. 688 * 689 * @since 1.2.4 690 */ 691 EAPI Eet_Error 692 eet_sync(Eet_File *ef); 693 694 /** 695 * @ingroup Eet_File_Group 696 * @brief Returns a handle to the shared string dictionary of the Eet file 697 * @param ef A valid eet file handle. 698 * @return A handle to the dictionary of the file 699 * 700 * This function returns a handle to the dictionary of an Eet file whose 701 * handle is @p ef, if a dictionary exists. NULL is returned otherwise or 702 * if the file handle is known to be invalid. 703 * 704 * @see eet_dictionary_string_check() to know if given string came 705 * from the dictionary or it was dynamically allocated using 706 * the #Eet_Data_Descriptor_Class instructions. 707 * 708 * @since 1.0.0 709 */ 710 EAPI Eet_Dictionary * 711 eet_dictionary_get(Eet_File *ef); 712 713 /** 714 * @ingroup Eet_File_Group 715 * @brief Checks if a given string comes from a given dictionary 716 * @param ed A valid dictionary handle 717 * @param string A valid 0 byte terminated C string 718 * @return @c 1 if it is in the dictionary, @c 0 otherwise 719 * 720 * This checks the given dictionary to see if the given string is actually 721 * inside that dictionary (i.e. comes from it) and returns @c 1 if it does. 722 * If the dictionary handle is invalid, the string is NULL or the string is 723 * not in the dictionary, @c 0 is returned. 724 * 725 * @since 1.0.0 726 */ 727 EAPI int 728 eet_dictionary_string_check(Eet_Dictionary *ed, 729 const char *string); 730 731 /** 732 * @ingroup Eet_File_Group 733 * @brief Returns the number of strings inside a dictionary. 734 * @param ed A valid dictionary handle 735 * @return the number of strings inside a dictionary 736 * 737 * @since 1.6.0 738 */ 739 EAPI int 740 eet_dictionary_count(const Eet_Dictionary *ed); 741 742 /** 743 * @ingroup Eet_File_Group 744 * @brief Reads a specified entry from an eet file and return data. 745 * @param ef A valid eet file handle opened for reading. 746 * @param name Name of the entry. eg: "/base/file_i_want". 747 * @param size_ret Number of bytes read from entry and returned. 748 * @return The data stored in that entry in the eet file. 749 * 750 * This function finds an entry in the eet file that is stored under the 751 * name specified, and returns that data, decompressed, if successful. 752 * NULL is returned if the lookup fails or if memory errors are 753 * encountered. It is the job of the calling program to call free() on 754 * the returned data. The number of bytes in the returned data chunk are 755 * placed in size_ret. 756 * 757 * If the eet file handle is not valid NULL is returned and size_ret is 758 * filled with @c 0. 759 * 760 * @see eet_read_cipher() 761 * 762 * @since 1.0.0 763 */ 764 EAPI void * 765 eet_read(Eet_File *ef, 766 const char *name, 767 int *size_ret); 768 769 /** 770 * @ingroup Eet_File_Group 771 * @brief Reads a specified entry from an eet file and return data. 772 * @param ef A valid eet file handle opened for reading. 773 * @param name Name of the entry. eg: "/base/file_i_want". 774 * @param size_ret Number of bytes read from entry and returned. 775 * @return The data stored in that entry in the eet file. 776 * 777 * This function finds an entry in the eet file that is stored under the 778 * name specified, and returns that data if not compressed and successful. 779 * NULL is returned if the lookup fails or if memory errors are 780 * encountered or if the data is compressed. The calling program must never 781 * call free() on the returned data. The number of bytes in the returned 782 * data chunk are placed in size_ret. 783 * 784 * If the eet file handle is not valid NULL is returned and size_ret is 785 * filled with @c 0. 786 * 787 * @since 1.0.0 788 */ 789 EAPI const void * 790 eet_read_direct(Eet_File *ef, 791 const char *name, 792 int *size_ret); 793 794 /** 795 * @ingroup Eet_File_Group 796 * @brief Write a specified entry to an eet file handle. 797 * @param ef A valid eet file handle opened for writing. 798 * @param name Name of the entry. eg: "/base/file_i_want". 799 * @param data Pointer to the data to be stored. 800 * @param size Length in bytes in the data to be stored. 801 * @param compress Compression flags (1 == compress, 0 = don't compress). 802 * @return bytes written on successful write, 0 on failure. 803 * 804 * This function will write the specified chunk of data to the eet file 805 * and return greater than 0 on success. 0 will be returned on failure. 806 * 807 * The eet file handle must be a valid file handle for an eet file opened 808 * for writing. If it is not, 0 will be returned and no action will be 809 * performed. 810 * 811 * Name, and data must not be NULL, and size must be > 0. If these 812 * conditions are not met, 0 will be returned. 813 * 814 * The data will be copied (and optionally compressed) in ram, pending 815 * a flush to disk (it will stay in ram till the eet file handle is 816 * closed though). 817 * 818 * @see eet_write_cipher() 819 * 820 * @since 1.0.0 821 */ 822 EAPI int 823 eet_write(Eet_File *ef, 824 const char *name, 825 const void *data, 826 int size, 827 int compress); 828 829 /** 830 * @ingroup Eet_File_Group 831 * @brief Deletes a specified entry from an Eet file being written or re-written. 832 * @param ef A valid eet file handle opened for writing. 833 * @param name Name of the entry. eg: "/base/file_i_want". 834 * @return Success or failure of the delete. 835 * 836 * This function will delete the specified chunk of data from the eet file 837 * and return greater than 0 on success. 0 will be returned on failure. 838 * 839 * The eet file handle must be a valid file handle for an eet file opened 840 * for writing. If it is not, 0 will be returned and no action will be 841 * performed. 842 * 843 * Name, must not be NULL, otherwise 0 will be returned. 844 * 845 * @since 1.0.0 846 */ 847 EAPI int 848 eet_delete(Eet_File *ef, 849 const char *name); 850 851 /** 852 * @ingroup Eet_File_Group 853 * @brief Alias a specific section to another one. Destination may exist or not, 854 * no checks are done. 855 * @param ef A valid eet file handle opened for writing. 856 * @param name Name of the new entry. eg: "/base/file_i_want". 857 * @param destination Actual source of the aliased entry eg: "/base/the_real_stuff_i_want". 858 * @param compress Compression flags (1 == compress, 0 = don't compress). 859 * @return EINA_TRUE on success, EINA_FALSE on failure. 860 * 861 * Name and Destination must not be NULL, otherwise EINA_FALSE will be returned. 862 * The equivalent of this would be calling 'ln -s destination name' 863 * 864 * @since 1.3.3 865 */ 866 EAPI Eina_Bool 867 eet_alias(Eet_File *ef, 868 const char *name, 869 const char *destination, 870 int compress); 871 872 /** 873 * @ingroup Eet_File_Group 874 * @brief Retrieves the filename of an Eet_File. 875 * @param ef A valid eet file handle opened for writing. 876 * @return The stringshared file string opened with eet_open(), or NULL on error 877 * 878 * @note This function will return NULL for files opened with eet_memopen_read() 879 * 880 * @since 1.6 881 */ 882 EAPI const char * 883 eet_file_get(Eet_File *ef); 884 885 /** 886 * @ingroup Eet_File_Group 887 * @brief Retrieves the destination name of an alias. 888 * @param ef A valid eet file handle opened for writing 889 * @param name Name of the entry. eg: "/base/file_i_want" 890 * @return Destination of the alias. eg: "/base/the_real_stuff_i_want", NULL on failure 891 * 892 * Name must not be NULL, otherwise NULL will be returned. 893 * 894 * @since 1.5 895 */ 896 EAPI const char * 897 eet_alias_get(Eet_File *ef, 898 const char *name); 899 900 /** 901 * @ingroup Eet_File_Group 902 * @brief Lists all entries in eet file matching shell glob. 903 * @param ef A valid eet file handle. 904 * @param glob A shell glob to match against. 905 * @param count_ret Number of entries found to match. 906 * @return Pointer to an array of strings. 907 * 908 * This function will list all entries in the eet file matching the 909 * supplied shell glob and return an allocated list of their names, if 910 * there are any, and if no memory errors occur. 911 * 912 * The eet file handle must be valid and glob must not be NULL, or NULL 913 * will be returned and count_ret will be filled with @c 0. 914 * 915 * The calling program must call free() on the array returned, but NOT 916 * on the string pointers in the array. They are taken as read-only 917 * internals from the eet file handle. They are only valid as long as 918 * the file handle is not closed. When it is closed those pointers in the 919 * array are now not valid and should not be used. 920 * 921 * On success, the array returned will have a list of string pointers 922 * that are the names of the entries that matched, and count_ret will have 923 * the number of entries in this array placed in it. 924 * 925 * Hint: an easy way to list all entries in an eet file is to use a glob 926 * value of "*". 927 * 928 * @since 1.0.0 929 */ 930 EAPI char ** 931 eet_list(Eet_File *ef, 932 const char *glob, 933 int *count_ret); 934 935 /** 936 * @ingroup Eet_File_Group 937 * @brief Returns an iterator that will describe each entry of an Eet_File. 938 * @param ef A valid eet file handle. 939 * @return An iterator of Eet_Entry. 940 * 941 * @since 1.8.0 942 */ 943 944 EAPI Eina_Iterator *eet_list_entries(Eet_File *ef); 945 946 /** 947 * @ingroup Eet_File_Group 948 * @brief Returns the number of entries in the specified eet file. 949 * @param ef A valid eet file handle. 950 * @return Number of entries in ef or @c -1 if the number of entries 951 * cannot be read due to open mode restrictions. 952 * 953 * @since 1.0.0 954 */ 955 EAPI int 956 eet_num_entries(Eet_File *ef); 957 958 /** 959 * @defgroup Eet_File_Cipher_Group Eet File Ciphered Main Functions 960 * @ingroup Eet_File_Group 961 * 962 * Most of the @ref Eet_File_Group have alternative versions that 963 * accounts for ciphers to protect their content. 964 * 965 * @see @ref Eet_Cipher_Group 966 * 967 */ 968 969 /** 970 * @ingroup Eet_File_Cipher_Group 971 * @brief Reads a specified entry from an eet file and return data using a cipher. 972 * @param ef A valid eet file handle opened for reading. 973 * @param name Name of the entry. eg: "/base/file_i_want". 974 * @param size_ret Number of bytes read from entry and returned. 975 * @param cipher_key The key to use as cipher. 976 * @return The data stored in that entry in the eet file. 977 * 978 * This function finds an entry in the eet file that is stored under the 979 * name specified, and returns that data, decompressed, if successful. 980 * NULL is returned if the lookup fails or if memory errors are 981 * encountered. It is the job of the calling program to call free() on 982 * the returned data. The number of bytes in the returned data chunk are 983 * placed in size_ret. 984 * 985 * If the eet file handle is not valid NULL is returned and size_ret is 986 * filled with @c 0. 987 * 988 * @see eet_read() 989 * 990 * @since 1.0.0 991 */ 992 EAPI void * 993 eet_read_cipher(Eet_File *ef, 994 const char *name, 995 int *size_ret, 996 const char *cipher_key); 997 998 /** 999 * @ingroup Eet_File_Cipher_Group 1000 * @brief Writes a specified entry to an eet file handle using a cipher. 1001 * @param ef A valid eet file handle opened for writing. 1002 * @param name Name of the entry. eg: "/base/file_i_want". 1003 * @param data Pointer to the data to be stored. 1004 * @param size Length in bytes in the data to be stored. 1005 * @param compress Compression flags (1 == compress, 0 = don't compress). 1006 * @param cipher_key The key to use as cipher. 1007 * @return Bytes written on successful write, @c 0 on failure. 1008 * 1009 * This function will write the specified chunk of data to the eet file 1010 * and return greater than @c 0 on success. 0 will be returned on failure. 1011 * 1012 * The eet file handle must be a valid file handle for an eet file opened 1013 * for writing. If it is not, @c 0 will be returned and no action will be 1014 * performed. 1015 * 1016 * Name, and data must not be NULL, and size must be > 0. If these 1017 * conditions are not met, 0 will be returned. 1018 * 1019 * The data will be copied (and optionally compressed) in ram, pending 1020 * a flush to disk (it will stay in ram till the eet file handle is 1021 * closed though). 1022 * 1023 * @see eet_write() 1024 * 1025 * @since 1.0.0 1026 */ 1027 EAPI int 1028 eet_write_cipher(Eet_File *ef, 1029 const char *name, 1030 const void *data, 1031 int size, 1032 int compress, 1033 const char *cipher_key); 1034 1035 /** 1036 * @defgroup Eet_File_Image_Group Image Store and Load 1037 * @ingroup Eet 1038 * 1039 * Eet efficiently stores and loads images, including alpha 1040 * channels and lossy compressions. 1041 * 1042 * Eet can handle both lossy compression with different levels of quality and 1043 * non-lossy compression with different compression levels. It's also possible, 1044 * given an image data, to only read its header to get the image information 1045 * without decoding the entire content for it. 1046 * 1047 * The encode family of functions will take an image raw buffer and its 1048 * parameters and compress it in memory, returning the new buffer. 1049 * Likewise, the decode functions will read from the given location in memory 1050 * and return the uncompressed image. 1051 * 1052 * The read and write functions will, respectively, encode and decode to or 1053 * from an Eet file, under the specified key. 1054 * 1055 * These functions are fairly low level and the same functionality can be 1056 * achieved using Evas and Edje, making it much easier to work with images 1057 * as well as not needing to worry about things like scaling them. 1058 */ 1059 1060 /** 1061 * @ingroup Eet_File_Image_Group 1062 * @brief Reads just the header data for an image and dont decode the pixels. 1063 * @param ef A valid eet file handle opened for reading. 1064 * @param name Name of the entry. eg: "/base/file_i_want". 1065 * @param w A pointer to the unsigned int to hold the width in pixels. 1066 * @param h A pointer to the unsigned int to hold the height in pixels. 1067 * @param alpha A pointer to the int to hold the alpha flag. 1068 * @param compress A pointer to the int to hold the compression amount. 1069 * @param quality A pointer to the int to hold the quality amount. 1070 * @param lossy A pointer to the int to hold the lossiness flag. 1071 * @return @c 1 on successful decode, @c 0 otherwise 1072 * 1073 * Reads and decodes the image header data stored under the given key and 1074 * Eet file. 1075 * 1076 * The information decoded is placed in each of the parameters, which must be 1077 * provided. The width and height, measured in pixels, will be stored under 1078 * the variables pointed by @p w and @p h, respectively. If the read or 1079 * decode of the header fails, this values will be 0. The @p alpha parameter 1080 * will be 1 or 0, denoting if the alpha channel of the image is used or not. 1081 * If the image was losslessly compressed, the @p compress parameter will hold 1082 * the compression amount used, ranging from 0 to 9 and @p lossy will be 0. 1083 * In the case of lossy compression, @p lossy will be 1, and the compression 1084 * quality will be placed under @p quality, with a value ranging from 0 to 100. 1085 * 1086 * @see eet_data_image_header_decode() 1087 * @see eet_data_image_header_read_cipher() 1088 * 1089 * @since 1.0.0 1090 */ 1091 EAPI int 1092 eet_data_image_header_read(Eet_File *ef, 1093 const char *name, 1094 unsigned int *w, 1095 unsigned int *h, 1096 int *alpha, 1097 int *compress, 1098 int *quality, 1099 Eet_Image_Encoding *lossy); 1100 1101 /** 1102 * @ingroup Eet_File_Image_Group 1103 * @brief Reads image data from the named key in the eet file. 1104 * @param ef A valid eet file handle opened for reading. 1105 * @param name Name of the entry. eg: "/base/file_i_want". 1106 * @param w A pointer to the unsigned int to hold the width in pixels. 1107 * @param h A pointer to the unsigned int to hold the height in pixels. 1108 * @param alpha A pointer to the int to hold the alpha flag. 1109 * @param compress A pointer to the int to hold the compression amount. 1110 * @param quality A pointer to the int to hold the quality amount. 1111 * @param lossy A pointer to the int to hold the lossiness flag. 1112 * @return The image pixel data decoded 1113 * 1114 * Reads and decodes the image stored in the given Eet file under the named 1115 * key. 1116 * 1117 * The returned pixel data is a linear array of pixels starting from the 1118 * top-left of the image, scanning row by row from left to right. Each pile 1119 * is a 32bit value, with the high byte being the alpha channel, the next being 1120 * red, then green, and the low byte being blue. 1121 * 1122 * The rest of the parameters are the same as in eet_data_image_header_read(). 1123 * 1124 * On success the function returns a pointer to the image data decoded. The 1125 * calling application is responsible for calling free() on the image data 1126 * when it is done with it. On failure NULL is returned and the parameter 1127 * values may not contain any sensible data. 1128 * 1129 * @see eet_data_image_header_read() 1130 * @see eet_data_image_decode() 1131 * @see eet_data_image_read_cipher() 1132 * @see eet_data_image_read_to_surface() 1133 * 1134 * @since 1.0.0 1135 */ 1136 EAPI void * 1137 eet_data_image_read(Eet_File *ef, 1138 const char *name, 1139 unsigned int *w, 1140 unsigned int *h, 1141 int *alpha, 1142 int *compress, 1143 int *quality, 1144 Eet_Image_Encoding *lossy); 1145 1146 /** 1147 * @ingroup Eet_File_Image_Group 1148 * @brief Reads image data from the named key in the eet file and store it in the given buffer. 1149 * @param ef A valid eet file handle opened for reading. 1150 * @param name Name of the entry. eg: "/base/file_i_want". 1151 * @param src_x The starting x coordinate from where to dump the stream. 1152 * @param src_y The starting y coordinate from where to dump the stream. 1153 * @param d A pointer to the pixel surface. 1154 * @param w The expected width in pixels of the pixel surface to decode. 1155 * @param h The expected height in pixels of the pixel surface to decode. 1156 * @param row_stride The length of a pixels line in the destination surface. 1157 * @param alpha A pointer to the int to hold the alpha flag. 1158 * @param compress A pointer to the int to hold the compression amount. 1159 * @param quality A pointer to the int to hold the quality amount. 1160 * @param lossy A pointer to the int to hold the lossiness flag. 1161 * @return @c 1 on success, @c 0 otherwise. 1162 * 1163 * Reads and decodes the image stored in the given Eet file, placing the 1164 * resulting pixel data in the buffer pointed by the user. 1165 * 1166 * Like eet_data_image_read(), it takes the image data stored under the 1167 * @p name key in the @p ef file, but instead of returning a new buffer with 1168 * the pixel data, it places the result in the buffer pointed by @p d, which 1169 * must be provided by the user and of sufficient size to hold the requested 1170 * portion of the image. 1171 * 1172 * The @p src_x and @p src_y parameters indicate the top-left corner of the 1173 * section of the image to decode. These have to be higher or equal than 0 and 1174 * less than the respective total width and height of the image. The width 1175 * and height of the section of the image to decode are given in @p w and @p h 1176 * and also can't be higher than the total width and height of the image. 1177 * 1178 * The @p row_stride parameter indicates the length in bytes of each line in 1179 * the destination buffer and it has to be at least @p w * 4. 1180 * 1181 * All the other parameters are the same as in eet_data_image_read(). 1182 * 1183 * On success the function returns 1, and 0 on failure. On failure the 1184 * parameter values may not contain any sensible data. 1185 * 1186 * @see eet_data_image_read() 1187 * @see eet_data_image_decode() 1188 * @see eet_data_image_decode_to_surface() 1189 * @see eet_data_image_read_to_surface_cipher() 1190 * @see eet_data_image_decode_to_cspace_surface_cipher() 1191 * 1192 * @since 1.0.2 1193 */ 1194 EAPI int 1195 eet_data_image_read_to_surface(Eet_File *ef, 1196 const char *name, 1197 unsigned int src_x, 1198 unsigned int src_y, 1199 unsigned int *d, 1200 unsigned int w, 1201 unsigned int h, 1202 unsigned int row_stride, 1203 int *alpha, 1204 int *compress, 1205 int *quality, 1206 Eet_Image_Encoding *lossy); 1207 1208 /** 1209 * @ingroup Eet_File_Image_Group 1210 * @brief Writes image data to the named key in an eet file. 1211 * @param ef A valid eet file handle opened for writing. 1212 * @param name Name of the entry. eg: "/base/file_i_want". 1213 * @param data A pointer to the image pixel data. 1214 * @param w The width of the image in pixels. 1215 * @param h The height of the image in pixels. 1216 * @param alpha The alpha channel flag. 1217 * @param compress The compression amount. 1218 * @param quality The quality encoding amount. 1219 * @param lossy The lossiness flag. 1220 * @return Success if the data was encoded and written or not. 1221 * 1222 * This function takes image pixel data and encodes it in an eet file 1223 * stored under the supplied name key, and returns how many bytes were 1224 * actually written to encode the image data. 1225 * 1226 * The data expected is the same format as returned by eet_data_image_read. 1227 * If this is not the case weird things may happen. Width and height must 1228 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning 1229 * the alpha values are not useful and 1 meaning they are). Compress can 1230 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression). 1231 * This is only used if the image is not lossily encoded. Quality is used on 1232 * lossy compression and should be a value from 0 to 100. The lossy flag 1233 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with 1234 * image quality loss (but then have a much smaller encoding). 1235 * 1236 * On success this function returns the number of bytes that were required 1237 * to encode the image data, or on failure it returns 0. 1238 * 1239 * @see eet_data_image_read() 1240 * @see eet_data_image_encode() 1241 * @see eet_data_image_write_cipher() 1242 * 1243 * @since 1.0.0 1244 */ 1245 EAPI int 1246 eet_data_image_write(Eet_File *ef, 1247 const char *name, 1248 const void *data, 1249 unsigned int w, 1250 unsigned int h, 1251 int alpha, 1252 int compress, 1253 int quality, 1254 Eet_Image_Encoding lossy); 1255 1256 /** 1257 * @ingroup Eet_File_Image_Group 1258 * @brief Decodes Image data header only to get information. 1259 * @param data The encoded pixel data. 1260 * @param size The size, in bytes, of the encoded pixel data. 1261 * @param w A pointer to the unsigned int to hold the width in pixels. 1262 * @param h A pointer to the unsigned int to hold the height in pixels. 1263 * @param alpha A pointer to the int to hold the alpha flag. 1264 * @param compress A pointer to the int to hold the compression amount. 1265 * @param quality A pointer to the int to hold the quality amount. 1266 * @param lossy A pointer to the int to hold the lossiness flag. 1267 * @return @c 1 on success, @c 0 on failure. 1268 * 1269 * This function works exactly like eet_data_image_header_read(), but instead 1270 * of reading from an Eet file, it takes the buffer of size @p size pointed 1271 * by @p data, which must be a valid Eet encoded image. 1272 * 1273 * On success the function returns @c 1 indicating the header was read and 1274 * decoded properly, or @c 0 on failure. 1275 * 1276 * @see eet_data_image_header_read() 1277 * @see eet_data_image_header_decode_cipher() 1278 * 1279 * @since 1.0.0 1280 */ 1281 EAPI int 1282 eet_data_image_header_decode(const void *data, 1283 int size, 1284 unsigned int *w, 1285 unsigned int *h, 1286 int *alpha, 1287 int *compress, 1288 int *quality, 1289 Eet_Image_Encoding *lossy); 1290 1291 /** 1292 * @ingroup Eet_File_Image_Group 1293 * @brief Decodes Image data into pixel data. 1294 * @param data The encoded pixel data. 1295 * @param size The size, in bytes, of the encoded pixel data. 1296 * @param w A pointer to the unsigned int to hold the width in pixels. 1297 * @param h A pointer to the unsigned int to hold the height in pixels. 1298 * @param alpha A pointer to the int to hold the alpha flag. 1299 * @param compress A pointer to the int to hold the compression amount. 1300 * @param quality A pointer to the int to hold the quality amount. 1301 * @param lossy A pointer to the int to hold the lossiness flag. 1302 * @return The image pixel data decoded 1303 * 1304 * This function takes encoded pixel data and decodes it into raw RGBA 1305 * pixels on success. 1306 * 1307 * It works exactly like eet_data_image_read(), but it takes the encoded 1308 * data in the @p data buffer of size @p size, instead of reading from a file. 1309 * All the others parameters are also the same. 1310 * 1311 * On success the function returns a pointer to the image data decoded. The 1312 * calling application is responsible for calling free() on the image data 1313 * when it is done with it. On failure NULL is returned and the parameter 1314 * values may not contain any sensible data. 1315 * 1316 * @see eet_data_image_read() 1317 * @see eet_data_image_decode_cipher() 1318 * 1319 * @since 1.0.0 1320 */ 1321 EAPI void * 1322 eet_data_image_decode(const void *data, 1323 int size, 1324 unsigned int *w, 1325 unsigned int *h, 1326 int *alpha, 1327 int *compress, 1328 int *quality, 1329 Eet_Image_Encoding *lossy); 1330 1331 /** 1332 * @ingroup Eet_File_Image_Group 1333 * @brief Decodes Image data into pixel data and stores in the given buffer. 1334 * @param data The encoded pixel data. 1335 * @param size The size, in bytes, of the encoded pixel data. 1336 * @param src_x The starting x coordinate from where to dump the stream. 1337 * @param src_y The starting y coordinate from where to dump the stream. 1338 * @param d A pointer to the pixel surface. 1339 * @param w The expected width in pixels of the pixel surface to decode. 1340 * @param h The expected height in pixels of the pixel surface to decode. 1341 * @param row_stride The length of a pixels line in the destination surface. 1342 * @param alpha A pointer to the int to hold the alpha flag. 1343 * @param compress A pointer to the int to hold the compression amount. 1344 * @param quality A pointer to the int to hold the quality amount. 1345 * @param lossy A pointer to the int to hold the lossiness flag. 1346 * @return @c 1 on success, @c 0 otherwise. 1347 * 1348 * Like eet_data_image_read_to_surface(), but reading the given @p data buffer 1349 * instead of a file. 1350 * 1351 * On success the function returns 1, and 0 on failure. On failure the 1352 * parameter values may not contain any sensible data. 1353 * 1354 * @see eet_data_image_read_to_surface() 1355 * @see eet_data_image_decode_to_surface_cipher() 1356 * 1357 * @since 1.0.2 1358 */ 1359 EAPI int 1360 eet_data_image_decode_to_surface(const void *data, 1361 int size, 1362 unsigned int src_x, 1363 unsigned int src_y, 1364 unsigned int *d, 1365 unsigned int w, 1366 unsigned int h, 1367 unsigned int row_stride, 1368 int *alpha, 1369 int *compress, 1370 int *quality, 1371 Eet_Image_Encoding *lossy); 1372 1373 /** 1374 * @ingroup Eet_File_Image_Group 1375 * @brief Encodes image data for storage or transmission. 1376 * @param data A pointer to the image pixel data. 1377 * @param size_ret A pointer to an int to hold the size of the returned data. 1378 * @param w The width of the image in pixels. 1379 * @param h The height of the image in pixels. 1380 * @param alpha The alpha channel flag. 1381 * @param compress The compression amount. 1382 * @param quality The quality encoding amount. 1383 * @param lossy The lossiness flag. 1384 * @return The encoded image data. 1385 * 1386 * This function stakes image pixel data and encodes it with compression and 1387 * possible loss of quality (as a trade off for size) for storage or 1388 * transmission to another system. 1389 * 1390 * It works like eet_data_image_write(), but instead of writing the encoded 1391 * image into an Eet file, it allocates a new buffer of the size required and 1392 * returns the encoded data in it. 1393 * 1394 * On success this function returns a pointer to the encoded data that you 1395 * can free with free() when no longer needed. 1396 * 1397 * @see eet_data_image_write() 1398 * @see eet_data_image_read() 1399 * @see eet_data_image_encode_cipher() 1400 * 1401 * @since 1.0.0 1402 */ 1403 EAPI void * 1404 eet_data_image_encode(const void *data, 1405 int *size_ret, 1406 unsigned int w, 1407 unsigned int h, 1408 int alpha, 1409 int compress, 1410 int quality, 1411 Eet_Image_Encoding lossy); 1412 1413 /** 1414 * @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Cipher 1415 * @ingroup Eet_File_Image_Group 1416 * 1417 * Most of the @ref Eet_File_Image_Group have alternative versions 1418 * that accounts for ciphers to protect their content. 1419 * 1420 * @see @ref Eet_Cipher_Group 1421 * 1422 */ 1423 1424 /** 1425 * @ingroup Eet_File_Image_Cipher_Group 1426 * @brief Reads just the header data for an image and dont decode the pixels 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 w A pointer to the unsigned int to hold the width in pixels. 1431 * @param h A pointer to the unsigned int to hold the height in pixels. 1432 * @param alpha A pointer to the int to hold the alpha flag. 1433 * @param compress A pointer to the int to hold the compression amount. 1434 * @param quality A pointer to the int to hold the quality amount. 1435 * @param lossy A pointer to the int to hold the lossiness flag. 1436 * @return @c 1 on successful decode, @c 0 otherwise 1437 * 1438 * This function reads an image from an eet file stored under the named 1439 * key in the eet file and return a pointer to the decompressed pixel data. 1440 * 1441 * The other parameters of the image (width, height etc.) are placed into 1442 * the values pointed to (they must be supplied). The pixel data is a linear 1443 * array of pixels starting from the top-left of the image scanning row by 1444 * row from left to right. Each pixel is a 32bit value, with the high byte 1445 * being the alpha channel, the next being red, then green, and the low byte 1446 * being blue. The width and height are measured in pixels and will be 1447 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1448 * that the alpha channel is not used. 1 denotes that it is significant. 1449 * Compress is filled with the compression value/amount the image was 1450 * stored with. The quality value is filled with the quality encoding of 1451 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1452 * the image was encoded lossily or not. 1453 * 1454 * On success the function returns @c 1 indicating the header was read and 1455 * decoded properly, or @c 0 on failure. 1456 * 1457 * @see eet_data_image_header_read() 1458 * 1459 * @since 1.0.0 1460 */ 1461 EAPI int 1462 eet_data_image_header_read_cipher(Eet_File *ef, 1463 const char *name, 1464 const char *cipher_key, 1465 unsigned int *w, 1466 unsigned int *h, 1467 int *alpha, 1468 int *compress, 1469 int *quality, 1470 Eet_Image_Encoding *lossy); 1471 1472 /** 1473 * @ingroup Eet_File_Image_Group 1474 * @brief Gets the colorspace Eet can decode into of a given eet image resource. 1475 * 1476 * @param ef A valid eet file handle opened for reading. 1477 * @param name Name of the entry. eg: "/base/file_i_want". 1478 * @param cipher_key The key to use as cipher. 1479 * @param cspaces Returned pointer by Eet to a list of possible decoding colorspace finished by @c EET_COLORSPACE_ARGB8888. If @c NULL, only EET_COLORSPACE_ARGB8888 is supported. 1480 * @return 1 on successful get, 0 otherwise. 1481 * 1482 * @since 1.10.0 1483 */ 1484 EAPI int 1485 eet_data_image_colorspace_get(Eet_File *ef, 1486 const char *name, 1487 const char *cipher_key, 1488 const Eet_Colorspace **cspaces); 1489 1490 /** 1491 * @ingroup Eet_File_Image_Cipher_Group 1492 * @brief Reads image data from the named key in the eet file using a cipher. 1493 * @param ef A valid eet file handle opened for reading. 1494 * @param name Name of the entry. eg: "/base/file_i_want". 1495 * @param cipher_key The key to use as cipher. 1496 * @param w A pointer to the unsigned int to hold the width in pixels. 1497 * @param h A pointer to the unsigned int to hold the height in pixels. 1498 * @param alpha A pointer to the int to hold the alpha flag. 1499 * @param compress A pointer to the int to hold the compression amount. 1500 * @param quality A pointer to the int to hold the quality amount. 1501 * @param lossy A pointer to the int to hold the lossiness flag. 1502 * @return The image pixel data decoded 1503 * 1504 * This function reads an image from an eet file stored under the named 1505 * key in the eet file and return a pointer to the decompressed pixel data. 1506 * 1507 * The other parameters of the image (width, height etc.) are placed into 1508 * the values pointed to (they must be supplied). The pixel data is a linear 1509 * array of pixels starting from the top-left of the image scanning row by 1510 * row from left to right. Each pixel is a 32bit value, with the high byte 1511 * being the alpha channel, the next being red, then green, and the low byte 1512 * being blue. The width and height are measured in pixels and will be 1513 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1514 * that the alpha channel is not used. 1 denotes that it is significant. 1515 * Compress is filled with the compression value/amount the image was 1516 * stored with. The quality value is filled with the quality encoding of 1517 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1518 * the image was encoded lossily or not. 1519 * 1520 * On success the function returns a pointer to the image data decoded. The 1521 * calling application is responsible for calling free() on the image data 1522 * when it is done with it. On failure NULL is returned and the parameter 1523 * values may not contain any sensible data. 1524 * 1525 * @see eet_data_image_read() 1526 * 1527 * @since 1.0.0 1528 */ 1529 EAPI void * 1530 eet_data_image_read_cipher(Eet_File *ef, 1531 const char *name, 1532 const char *cipher_key, 1533 unsigned int *w, 1534 unsigned int *h, 1535 int *alpha, 1536 int *compress, 1537 int *quality, 1538 Eet_Image_Encoding *lossy); 1539 1540 /** 1541 * @ingroup Eet_File_Image_Cipher_Group 1542 * @brief Reads image data from the named key in the eet file using a cipher. 1543 * @param ef A valid eet file handle opened for reading. 1544 * @param name Name of the entry. eg: "/base/file_i_want". 1545 * @param cipher_key The key to use as cipher. 1546 * @param src_x The starting x coordinate from where to dump the stream. 1547 * @param src_y The starting y coordinate from where to dump the stream. 1548 * @param d A pointer to the pixel surface. 1549 * @param w The expected width in pixels of the pixel surface to decode. 1550 * @param h The expected height in pixels of the pixel surface to decode. 1551 * @param row_stride The length of a pixels line in the destination surface. 1552 * @param alpha A pointer to the int to hold the alpha flag. 1553 * @param compress A pointer to the int to hold the compression amount. 1554 * @param quality A pointer to the int to hold the quality amount. 1555 * @param lossy A pointer to the int to hold the lossiness flag. 1556 * @return @c 1 on success, @c 0 otherwise. 1557 * 1558 * This function reads an image from an eet file stored under the named 1559 * key in the eet file and store the decompressed pixel data in the provided 1560 * surface with an @c EET_COLORSPACE_ARGB8888 colorspace. 1561 * 1562 * The other parameters of the image (width, height etc.) are placed into 1563 * the values pointed to (they must be supplied). The pixel data is a linear 1564 * array of pixels starting from the top-left of the image scanning row by 1565 * row from left to right. Each pixel is a 32bit value, with the high byte 1566 * being the alpha channel, the next being red, then green, and the low byte 1567 * being blue. The width and height are measured in pixels and will be 1568 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1569 * that the alpha channel is not used. 1 denotes that it is significant. 1570 * Compress is filled with the compression value/amount the image was 1571 * stored with. The quality value is filled with the quality encoding of 1572 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1573 * the image was encoded lossily or not. 1574 * 1575 * On success the function returns 1, and 0 on failure. On failure the 1576 * parameter values may not contain any sensible data. 1577 * 1578 * @see eet_data_image_read_to_surface() 1579 * @see eet_data_image_decode_to_cspace_surface_cipher() 1580 * 1581 * @since 1.0.2 1582 */ 1583 EAPI int 1584 eet_data_image_read_to_surface_cipher(Eet_File *ef, 1585 const char *name, 1586 const char *cipher_key, 1587 unsigned int src_x, 1588 unsigned int src_y, 1589 unsigned int *d, 1590 unsigned int w, 1591 unsigned int h, 1592 unsigned int row_stride, 1593 int *alpha, 1594 int *compress, 1595 int *quality, 1596 Eet_Image_Encoding *lossy); 1597 1598 1599 /** 1600 * @ingroup Eet_File_Image_Cipher_Group 1601 * @brief Reads image data from the named key in the eet file using a cipher. 1602 * @param ef A valid eet file handle opened for reading. 1603 * @param name Name of the entry. eg: "/base/file_i_want". 1604 * @param cipher_key The key to use as cipher. 1605 * @param src_x The starting x coordinate from where to dump the stream. 1606 * @param src_y The starting y coordinate from where to dump the stream. 1607 * @param d A pointer to the pixel surface. 1608 * @param w The expected width in pixels of the pixel surface to decode. 1609 * @param h The expected height in pixels of the pixel surface to decode. 1610 * @param row_stride The length of a pixels line in the destination surface. 1611 * @param cspace The color space of the pixels surface. 1612 * @param alpha A pointer to the int to hold the alpha flag. 1613 * @param comp A pointer to the int to hold the compression amount. 1614 * @param quality A pointer to the int to hold the quality amount. 1615 * @param lossy A pointer to the int to hold the lossiness flag. 1616 * @return @c 1 on success, @c 0 otherwise. 1617 * 1618 * This function reads an image from an eet file stored under the named 1619 * key in the eet file and store the decompressed pixel data in the provided 1620 * surface colorspace. 1621 * 1622 * The other parameters of the image (width, height etc.) are placed into 1623 * the values pointed to (they must be supplied). The pixel data is a linear 1624 * array of pixels starting from the top-left of the image scanning row by 1625 * row from left to right. Each pixel is a 32bit value, with the high byte 1626 * being the alpha channel, the next being red, then green, and the low byte 1627 * being blue. The width and height are measured in pixels and will be 1628 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1629 * that the alpha channel is not used. 1 denotes that it is significant. 1630 * Compress is filled with the compression value/amount the image was 1631 * stored with. The quality value is filled with the quality encoding of 1632 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1633 * the image was encoded lossily or not. 1634 * 1635 * On success the function returns 1, and 0 on failure. On failure the 1636 * parameter values may not contain any sensible data. 1637 * 1638 * @see eet_data_image_read_to_surface() 1639 * @see eet_data_image_decode_to_cspace_surface_cipher() 1640 * @see eet_data_image_read_to_surface_cipher() 1641 * 1642 * @since 1.10.0 1643 */ 1644 EAPI int 1645 eet_data_image_read_to_cspace_surface_cipher(Eet_File *ef, 1646 const char *name, 1647 const char *cipher_key, 1648 unsigned int src_x, 1649 unsigned int src_y, 1650 unsigned int *d, 1651 unsigned int w, 1652 unsigned int h, 1653 unsigned int row_stride, 1654 Eet_Colorspace cspace, 1655 int *alpha, 1656 int *comp, 1657 int *quality, 1658 Eet_Image_Encoding *lossy); 1659 1660 1661 /** 1662 * @ingroup Eet_File_Image_Cipher_Group 1663 * @brief Reads image data from the named key in the eet file using a cipher. 1664 * @param data The encoded pixel data. 1665 * @param cipher_key The key to use as cipher. 1666 * @param size The size, in bytes, of the encoded pixel data. 1667 * @param src_x The starting x coordinate from where to dump the stream. 1668 * @param src_y The starting y coordinate from where to dump the stream. 1669 * @param d A pointer to the pixel surface. 1670 * @param w The expected width in pixels of the pixel surface to decode. 1671 * @param h The expected height in pixels of the pixel surface to decode. 1672 * @param row_stride The length of a pixels line in the destination surface. 1673 * @param cspace The color space of the pixel surface 1674 * @param alpha A pointer to the int to hold the alpha flag. 1675 * @param comp A pointer to the int to hold the compression amount. 1676 * @param quality A pointer to the int to hold the quality amount. 1677 * @param lossy A pointer to the int to hold the lossiness flag. 1678 * @return @c 1 on success, @c 0 otherwise. 1679 * 1680 * This function reads an image from an eet file stored under the named 1681 * key in the eet file and store the decompressed pixels in the specified 1682 * color space inside the given surface. 1683 * 1684 * The other parameters of the image (width, height etc.) are placed into 1685 * the values pointed to (they must be supplied). The pixel data is a linear 1686 * array of pixels starting from the top-left of the image scanning row by 1687 * row from left to right. Each pixel is a 32bit value, with the high byte 1688 * being the alpha channel, the next being red, then green, and the low byte 1689 * being blue. The width and height are measured in pixels and will be 1690 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1691 * that the alpha channel is not used. 1 denotes that it is significant. 1692 * Compress is filled with the compression value/amount the image was 1693 * stored with. The quality value is filled with the quality encoding of 1694 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1695 * the image was encoded lossily or not. 1696 * 1697 * On success the function returns 1, and 0 on failure. On failure the 1698 * parameter values may not contain any sensible data. 1699 * 1700 * @see eet_data_image_read_to_surface() 1701 * @see eet_data_image_read_to_surface_cipher() 1702 * 1703 * @since 1.10.0 1704 */ 1705 1706 EAPI int 1707 eet_data_image_decode_to_cspace_surface_cipher(const void *data, 1708 const char *cipher_key, 1709 int size, 1710 unsigned int src_x, 1711 unsigned int src_y, 1712 unsigned int *d, 1713 unsigned int w, 1714 unsigned int h, 1715 unsigned int row_stride, 1716 Eet_Colorspace cspace, 1717 int *alpha, 1718 int *comp, 1719 int *quality, 1720 Eet_Image_Encoding *lossy); 1721 1722 /** 1723 * @ingroup Eet_File_Image_Cipher_Group 1724 * @brief Writes image data to the named key in an eet file using a cipher. 1725 * @param ef A valid eet file handle opened for writing. 1726 * @param name Name of the entry. eg: "/base/file_i_want". 1727 * @param cipher_key The key to use as cipher. 1728 * @param data A pointer to the image pixel data. 1729 * @param w The width of the image in pixels. 1730 * @param h The height of the image in pixels. 1731 * @param alpha The alpha channel flag. 1732 * @param compress The compression amount. 1733 * @param quality The quality encoding amount. 1734 * @param lossy The lossiness flag. 1735 * @return Success if the data was encoded and written or not. 1736 * 1737 * This function takes image pixel data and encodes it in an eet file 1738 * stored under the supplied name key, and returns how many bytes were 1739 * actually written to encode the image data. 1740 * 1741 * The data expected is the same format as returned by eet_data_image_read. 1742 * If this is not the case weird things may happen. Width and height must 1743 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning 1744 * the alpha values are not useful and 1 meaning they are). Compress can 1745 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression). 1746 * This is only used if the image is not lossily encoded. Quality is used on 1747 * lossy compression and should be a value from 0 to 100. The lossy flag 1748 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with 1749 * image quality loss (but then have a much smaller encoding). 1750 * 1751 * On success this function returns the number of bytes that were required 1752 * to encode the image data, or on failure it returns 0. 1753 * 1754 * @see eet_data_image_write() 1755 * 1756 * @since 1.0.0 1757 */ 1758 EAPI int 1759 eet_data_image_write_cipher(Eet_File *ef, 1760 const char *name, 1761 const char *cipher_key, 1762 const void *data, 1763 unsigned int w, 1764 unsigned int h, 1765 int alpha, 1766 int compress, 1767 int quality, 1768 Eet_Image_Encoding lossy); 1769 1770 /** 1771 * @ingroup Eet_File_Image_Cipher_Group 1772 * @brief Decodes Image data header only to get information using a cipher. 1773 * @param data The encoded pixel data. 1774 * @param cipher_key The key to use as cipher. 1775 * @param size The size, in bytes, of the encoded pixel data. 1776 * @param w A pointer to the unsigned int to hold the width in pixels. 1777 * @param h A pointer to the unsigned int to hold the height in pixels. 1778 * @param alpha A pointer to the int to hold the alpha flag. 1779 * @param compress A pointer to the int to hold the compression amount. 1780 * @param quality A pointer to the int to hold the quality amount. 1781 * @param lossy A pointer to the int to hold the lossiness flag. 1782 * @return @c 1 on success, @c 0 on failure. 1783 * 1784 * This function takes encoded pixel data and decodes it into raw RGBA 1785 * pixels on success. 1786 * 1787 * The other parameters of the image (width, height etc.) are placed into 1788 * the values pointed to (they must be supplied). The pixel data is a linear 1789 * array of pixels starting from the top-left of the image scanning row by 1790 * row from left to right. Each pixel is a 32bit value, with the high byte 1791 * being the alpha channel, the next being red, then green, and the low byte 1792 * being blue. The width and height are measured in pixels and will be 1793 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1794 * that the alpha channel is not used. 1 denotes that it is significant. 1795 * Compress is filled with the compression value/amount the image was 1796 * stored with. The quality value is filled with the quality encoding of 1797 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1798 * the image was encoded lossily or not. 1799 * 1800 * On success the function returns 1 indicating the header was read and 1801 * decoded properly, or 0 on failure. 1802 * 1803 * @see eet_data_image_header_decode() 1804 * 1805 * @since 1.0.0 1806 */ 1807 EAPI int 1808 eet_data_image_header_decode_cipher(const void *data, 1809 const char *cipher_key, 1810 int size, 1811 unsigned int *w, 1812 unsigned int *h, 1813 int *alpha, 1814 int *compress, 1815 int *quality, 1816 Eet_Image_Encoding *lossy); 1817 1818 /** 1819 * @ingroup Eet_File_Image_Cipher_Group 1820 * @brief Decodes Image data into pixel data using a cipher. 1821 * @param data The encoded pixel data. 1822 * @param cipher_key The key to use as cipher. 1823 * @param size The size, in bytes, of the encoded pixel data. 1824 * @param w A pointer to the unsigned int to hold the width in pixels. 1825 * @param h A pointer to the unsigned int to hold the height in pixels. 1826 * @param alpha A pointer to the int to hold the alpha flag. 1827 * @param compress A pointer to the int to hold the compression amount. 1828 * @param quality A pointer to the int to hold the quality amount. 1829 * @param lossy A pointer to the int to hold the lossiness flag. 1830 * @return The image pixel data decoded 1831 * 1832 * This function takes encoded pixel data and decodes it into raw RGBA 1833 * pixels on success. 1834 * 1835 * The other parameters of the image (width, height etc.) are placed into 1836 * the values pointed to (they must be supplied). The pixel data is a linear 1837 * array of pixels starting from the top-left of the image scanning row by 1838 * row from left to right. Each pixel is a 32bit value, with the high byte 1839 * being the alpha channel, the next being red, then green, and the low byte 1840 * being blue. The width and height are measured in pixels and will be 1841 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1842 * that the alpha channel is not used. 1 denotes that it is significant. 1843 * Compress is filled with the compression value/amount the image was 1844 * stored with. The quality value is filled with the quality encoding of 1845 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1846 * the image was encoded lossily or not. 1847 * 1848 * On success the function returns a pointer to the image data decoded. The 1849 * calling application is responsible for calling free() on the image data 1850 * when it is done with it. On failure NULL is returned and the parameter 1851 * values may not contain any sensible data. 1852 * 1853 * @see eet_data_image_decode() 1854 * 1855 * @since 1.0.0 1856 */ 1857 EAPI void * 1858 eet_data_image_decode_cipher(const void *data, 1859 const char *cipher_key, 1860 int size, 1861 unsigned int *w, 1862 unsigned int *h, 1863 int *alpha, 1864 int *compress, 1865 int *quality, 1866 Eet_Image_Encoding *lossy); 1867 1868 /** 1869 * @ingroup Eet_File_Image_Cipher_Group 1870 * @brief Decodes Image data into pixel data using a cipher. 1871 * @param data The encoded pixel data. 1872 * @param cipher_key The key to use as cipher. 1873 * @param size The size, in bytes, of the encoded pixel data. 1874 * @param src_x The starting x coordinate from where to dump the stream. 1875 * @param src_y The starting y coordinate from where to dump the stream. 1876 * @param d A pointer to the pixel surface. 1877 * @param w The expected width in pixels of the pixel surface to decode. 1878 * @param h The expected height in pixels of the pixel surface to decode. 1879 * @param row_stride The length of a pixels line in the destination surface. 1880 * @param alpha A pointer to the int to hold the alpha flag. 1881 * @param compress A pointer to the int to hold the compression amount. 1882 * @param quality A pointer to the int to hold the quality amount. 1883 * @param lossy A pointer to the int to hold the lossiness flag. 1884 * @return @c 1 on success, @c 0 otherwise. 1885 * 1886 * This function takes encoded pixel data and decodes it into raw RGBA 1887 * pixels on success. 1888 * 1889 * The other parameters of the image (alpha, compress etc.) are placed into 1890 * the values pointed to (they must be supplied). The pixel data is a linear 1891 * array of pixels starting from the top-left of the image scanning row by 1892 * row from left to right. Each pixel is a 32bit value, with the high byte 1893 * being the alpha channel, the next being red, then green, and the low byte 1894 * being blue. The width and height are measured in pixels and will be 1895 * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes 1896 * that the alpha channel is not used. 1 denotes that it is significant. 1897 * Compress is filled with the compression value/amount the image was 1898 * stored with. The quality value is filled with the quality encoding of 1899 * the image file (0 - 100). The lossy flags is either 0 or 1 as to if 1900 * the image was encoded lossily or not. 1901 * 1902 * On success the function returns 1, and 0 on failure. On failure the 1903 * parameter values may not contain any sensible data. 1904 * 1905 * @see eet_data_image_decode_to_surface() 1906 * 1907 * @since 1.0.2 1908 */ 1909 EAPI int 1910 eet_data_image_decode_to_surface_cipher(const void *data, 1911 const char *cipher_key, 1912 int size, 1913 unsigned int src_x, 1914 unsigned int src_y, 1915 unsigned int *d, 1916 unsigned int w, 1917 unsigned int h, 1918 unsigned int row_stride, 1919 int *alpha, 1920 int *compress, 1921 int *quality, 1922 Eet_Image_Encoding *lossy); 1923 1924 /** 1925 * @ingroup Eet_File_Image_Cipher_Group 1926 * @brief Encodes image data for storage or transmission using a cipher. 1927 * @param data A pointer to the image pixel data. 1928 * @param cipher_key The key to use as cipher. 1929 * @param size_ret A pointer to an int to hold the size of the returned data. 1930 * @param w The width of the image in pixels. 1931 * @param h The height of the image in pixels. 1932 * @param alpha The alpha channel flag. 1933 * @param compress The compression amount. 1934 * @param quality The quality encoding amount. 1935 * @param lossy The lossiness flag. 1936 * @return The encoded image data. 1937 * 1938 * This function stakes image pixel data and encodes it with compression and 1939 * possible loss of quality (as a trade off for size) for storage or 1940 * transmission to another system. 1941 * 1942 * The data expected is the same format as returned by eet_data_image_read. 1943 * If this is not the case weird things may happen. Width and height must 1944 * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning 1945 * the alpha values are not useful and 1 meaning they are). Compress can 1946 * be from 0 to 9 (0 meaning no compression, 9 meaning full compression). 1947 * This is only used if the image is not lossily encoded. Quality is used on 1948 * lossy compression and should be a value from 0 to 100. The lossy flag 1949 * can be 0 or 1. 0 means encode losslessly and 1 means to encode with 1950 * image quality loss (but then have a much smaller encoding). 1951 * 1952 * On success this function returns a pointer to the encoded data that you 1953 * can free with free() when no longer needed. 1954 * 1955 * @see eet_data_image_encode() 1956 * 1957 * @since 1.0.0 1958 */ 1959 EAPI void * 1960 eet_data_image_encode_cipher(const void *data, 1961 const char *cipher_key, 1962 unsigned int w, 1963 unsigned int h, 1964 int alpha, 1965 int compress, 1966 int quality, 1967 Eet_Image_Encoding lossy, 1968 int *size_ret); 1969 1970 /** 1971 * @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms 1972 * @ingroup Eet 1973 * 1974 * Eet allows one to protect entries of an #Eet_File 1975 * individually. This may be used to ensure data was not tampered or 1976 * that third party does not read your data. 1977 * 1978 * @see @ref Eet_File_Cipher_Group 1979 * @see @ref Eet_File_Image_Cipher_Group 1980 * 1981 * @{ 1982 */ 1983 1984 /** 1985 * @typedef Eet_Key 1986 * Opaque handle that defines an identity (also known as key) 1987 * in Eet's cipher system. 1988 */ 1989 typedef struct _Eet_Key Eet_Key; 1990 1991 /** 1992 * @} 1993 */ 1994 1995 /** 1996 * @ingroup Eet_Cipher_Group 1997 * @brief Callback used to request if needed the password of a private key. 1998 * 1999 * @param buffer the buffer where to store the password. 2000 * @param size the maximum password size (size of buffer, including '@\0'). 2001 * @param rwflag if the buffer is also readable or just writable. 2002 * @param data currently unused, may contain some context in future. 2003 * @return @c 1 on success and password was set to @p buffer, @c 0 on failure. 2004 * 2005 * @since 1.2.0 2006 */ 2007 typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data); 2008 2009 /** 2010 * @ingroup Eet_Cipher_Group 2011 * @brief Creates an Eet_Key needed for signing an eet file. 2012 * 2013 * The certificate should provide the public that match the private key. 2014 * No verification is done to ensure that. 2015 * 2016 * @param certificate_file The file where to find the certificate. 2017 * @param private_key_file The file that contains the private key. 2018 * @param cb Function to callback if password is required to unlock 2019 * private key. 2020 * @return A key handle to use, or @c NULL on failure. 2021 * 2022 * @see eet_identity_close() 2023 * 2024 * @warning You need to compile signature support in EET. 2025 * @since 1.2.0 2026 */ 2027 EAPI Eet_Key * 2028 eet_identity_open(const char *certificate_file, 2029 const char *private_key_file, 2030 Eet_Key_Password_Callback cb); 2031 2032 /** 2033 * @ingroup Eet_Cipher_Group 2034 * @brief Close and release all resource used by an Eet_Key. 2035 * A reference counter prevent it from being freed until all file 2036 * using it are also closed. 2037 * 2038 * @param key the key handle to close and free resources. 2039 * 2040 * @since 1.2.0 2041 */ 2042 EAPI void 2043 eet_identity_close(Eet_Key *key); 2044 2045 /** 2046 * @ingroup Eet_Cipher_Group 2047 * @brief Sets a key to sign a file. 2048 * 2049 * @param ef the file to set the identity. 2050 * @param key the key handle to set as identity. 2051 * @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or 2052 * #EET_ERROR_NONE on success. 2053 * 2054 * @since 1.2.0 2055 */ 2056 EAPI Eet_Error 2057 eet_identity_set(Eet_File *ef, 2058 Eet_Key *key); 2059 2060 /** 2061 * @ingroup Eet_Cipher_Group 2062 * @brief Displays both private and public key of an Eet_Key. 2063 * 2064 * @param key the handle to print. 2065 * @param out where to print. 2066 * 2067 * @warning You need to compile signature support in EET. 2068 * @since 1.2.0 2069 */ 2070 EAPI void 2071 eet_identity_print(Eet_Key *key, 2072 FILE *out); 2073 2074 /** 2075 * @ingroup Eet_Cipher_Group 2076 * @brief Compares the identify certificate of an eet file against a stored one 2077 * 2078 * @param ef The file handle to check the identify of 2079 * @param certificate_file The path to the certificate file 2080 * @return @c EINA_TRUE if the certificates match, otherwise @c EINA_FALSE 2081 * 2082 * The @p ef file handle mus be valid, and a signed file, otherwise 2083 * checking will fail. The path to the certificate file must be a valid 2084 * file path to a 'pem' format file (the same used for siging with 2085 * eet_identity_open() as a certificate file). 2086 * 2087 * @note This function can not be used to provide any security mechanism. You 2088 * need to check your x509 certificate against a chain of trust to have a proper 2089 * security. This is just a convenience test function. 2090 * @warning You need to compile signature support in EET. 2091 * @since 1.13 2092 */ 2093 EAPI Eina_Bool 2094 eet_identity_verify(Eet_File *ef, 2095 const char *certificate_file); 2096 2097 /** 2098 * @ingroup Eet_Cipher_Group 2099 * @brief Gets the x509 der certificate associated with an Eet_File. Will return NULL 2100 * if the file is not signed. 2101 * 2102 * @param ef The file handle to query. 2103 * @param der_length The length of returned data, may be @c NULL. 2104 * @return the x509 certificate or @c NULL on error. 2105 * 2106 * @since 1.2.0 2107 */ 2108 EAPI const void * 2109 eet_identity_x509(Eet_File *ef, 2110 int *der_length); 2111 2112 /** 2113 * @ingroup Eet_Cipher_Group 2114 * @brief Gets the raw signature associated with an Eet_File. Will return NULL 2115 * if the file is not signed. 2116 * 2117 * @param ef The file handle to query. 2118 * @param signature_length The length of returned data, may be @c NULL. 2119 * @return The raw signature or @c NULL on error. 2120 * 2121 */ 2122 EAPI const void * 2123 eet_identity_signature(Eet_File *ef, 2124 int *signature_length); 2125 2126 /** 2127 * @ingroup Eet_Cipher_Group 2128 * @brief Gets the SHA1 associated with a file. Could be the one used to 2129 * sign the data or if the data where not signed, it will be the 2130 * SHA1 of the file. 2131 * 2132 * @param ef The file handle to query. 2133 * @param sha1_length The length of returned data, may be @c NULL. 2134 * @return the associated SHA1 or @c NULL on error. 2135 * 2136 * @since 1.2.0 2137 */ 2138 EAPI const void * 2139 eet_identity_sha1(Eet_File *ef, 2140 int *sha1_length); 2141 2142 /** 2143 * @ingroup Eet_Cipher_Group 2144 * @brief Displays the x509 der certificate to out. 2145 * 2146 * @param certificate the x509 certificate to print 2147 * @param der_length The length the certificate. 2148 * @param out where to print. 2149 * 2150 * @warning You need to compile signature support in EET. 2151 * @since 1.2.0 2152 */ 2153 EAPI void 2154 eet_identity_certificate_print(const unsigned char *certificate, 2155 int der_length, 2156 FILE *out); 2157 2158 /** 2159 * @defgroup Eet_Data_Group Eet Data Serialization 2160 * @ingroup Eet 2161 * 2162 * Convenience functions to serialize and parse complex data 2163 * structures to binary blobs. 2164 * 2165 * While Eet core just handles binary blobs, it is often required 2166 * to save some structured data of different types, such as 2167 * strings, integers, lists, hashes and so on. 2168 * 2169 * Eet can serialize and then parse data types given some 2170 * construction instructions. These are defined in two levels: 2171 * 2172 * - #Eet_Data_Descriptor_Class to tell generic memory handling, 2173 * such as the size of the type, how to allocate memory, strings, 2174 * lists, hashes and so on. 2175 * 2176 * - #Eet_Data_Descriptor to tell inside such type, the members and 2177 * their offsets inside the memory blob, their types and 2178 * names. These members can be simple types or other 2179 * #Eet_Data_Descriptor, allowing hierarchical types to be 2180 * defined. 2181 * 2182 * Given that C provides no introspection, this process can be 2183 * quite cumbersome, so we provide lots of macros and convenience 2184 * functions to aid creating the types. 2185 * 2186 * We make now a quick overview of some of the most commonly used elements 2187 * of this part of the library. A simple example of a configuration system 2188 * will work as a somewhat real life example that is still simple enough to 2189 * follow. 2190 * Only the relevant sections will be shown here, but you can get the full 2191 * code @ref eet-data-simple.c "here". 2192 * 2193 * Ignoring the included headers, we'll begin by defining our configuration 2194 * struct. 2195 * @dontinclude eet-data-simple.c 2196 * @skip typedef 2197 * @until } 2198 * 2199 * When using Eet, you don't think in matters of what data the program needs 2200 * to run and which you would like to store. It's all the same and if it makes 2201 * more sense to keep them together, it's perfectly fine to do so. At the time 2202 * of telling Eet how your data is comprised you can leave out the things 2203 * that are runtime only and let Eet take care of the rest for you. 2204 * 2205 * The key used to store the config follows, as well as the variable used to 2206 * store our data descriptor. 2207 * This last one is very important. It's the one thing that Eet will use to 2208 * identify your data, both at the time of writing it to the file and when 2209 * loading from it. 2210 * @skipline MY_CONF 2211 * @skipline Eet_Data_Descriptor 2212 * 2213 * Now we'll see how to create this descriptor, so Eet knows how to handle 2214 * our data later on. 2215 * Begin our function by declaring an Eet_Data_Descriptor_Class, which is 2216 * used to create the actual descriptor. This class contains the name of 2217 * our data type, its size and several functions that dictate how Eet should 2218 * handle memory to allocate the necessary bits to bring our data to life. 2219 * You, as a user, will very hardly set this class' contents directly. The 2220 * most common scenario is to use one of the provided macros that set it using 2221 * the Eina data types, so that's what we'll be doing across all our examples. 2222 * @skip static void 2223 * @until eet_data_descriptor_stream_new 2224 * 2225 * Now that we have our descriptor, we need to make it describe something. 2226 * We do so by telling it which members of our struct we want it to know about 2227 * and their types. 2228 * The eet_data_descriptor_element_add() function takes care of this, but it's 2229 * too cumbersome for normal use, so several macros are provided that make 2230 * it easier to handle. Even with them, however, code can get very repetitive 2231 * and it's not uncommon to define custom macros using them to save on typing. 2232 * @skip #define 2233 * @until } 2234 * 2235 * Now our descriptor knows about the parts of our structure that we are 2236 * interesting in saving. You can see that not all of them are there, yet Eet 2237 * will find those that need saving and do the right thing. When loading our 2238 * data, any non-described fields in the structure will be zeroed, so there's 2239 * no need to worry about garbage memory in them. 2240 * Refer to the documentation of #EET_DATA_DESCRIPTOR_ADD_BASIC to understand 2241 * what our macro does. 2242 * 2243 * We are done with our descriptor init function and it's proper to have the 2244 * relevant shutdown. Proper coding guidelines indiciate that all memory 2245 * allocated should be freed when the program ends, and since you will most 2246 * likely keep your descriptor around for the life or your application, it's 2247 * only right to free it at the end. 2248 * @skip static void 2249 * @until } 2250 * 2251 * Not listed here, but included in the full example are functions to create 2252 * a blank configuration and free it. The first one will only be used when 2253 * no file exists to load from, or nothing is found in it, but the latter is 2254 * used regardless of where our data comes from. Unless you are reading direct 2255 * data from the Eet file, you will be in charge of freeing anything loaded 2256 * from it. 2257 * 2258 * Now it's time to look at how we can load our config from some file. 2259 * Begin by opening the Eet file normally. 2260 * @skip static My_Conf_Type 2261 * @until } 2262 * 2263 * And now we need to read the data from the file and decode it using our 2264 * descriptor. Fortunately, that's all done in one single step. 2265 * @until goto 2266 * 2267 * And that's it for all Eet cares about. But since we are dealing with a 2268 * common case, as is save and load of user configurations, the next fragment 2269 * of code shows why we have a version field in our struct, and how you can 2270 * use it to load older configuration files and update them as needed. 2271 * @until } 2272 * 2273 * Finally, close the file and return the newly loaded config data. 2274 * @until } 2275 * 2276 * Saving data is just as easy. The full version of the following function 2277 * includes code to save to a temporary file first, so you can be sure not 2278 * to lose all your data in the case of a failure mid-writing. You can look 2279 * at it @ref eet-data-simple.c "here". 2280 * @skip static Eina_Bool 2281 * @until { 2282 * @skipline Eina_Bool ret 2283 * @skip eet_open 2284 * @until eet_close 2285 * @skip return 2286 * @until } 2287 * 2288 * To close, our main function, which doesn't do much. Just take some arguments 2289 * from the command line with the name of the file to load and another one 2290 * where to save again. If input file doesn't exist, a new config structure 2291 * will be created and saved to our output file. 2292 * @skip int main 2293 * @until return ret 2294 * @until } 2295 * 2296 * The following is a list of more advanced and detailed examples. 2297 * @li @ref eet_data_nested_example 2298 * @li @ref eet_data_file_descriptor 2299 * @li @ref Example_Eet_Data_File_Descriptor_02 2300 * @li @ref Example_Eet_Data_Cipher_Decipher 2301 */ 2302 2303 /** 2304 * @page eet_data_nested_example Nested structures and Eet Data Descriptors 2305 * 2306 * We've seen already a simple example of how to use Eet Data Descriptors 2307 * to handle our structures, but it didn't show how this works when you 2308 * have structures inside other structures. 2309 * 2310 * Now, there's a very simple case of this, for when you have inline structs 2311 * to keep your big structure more organized, you don't need anything else 2312 * besides what @ref eet-data-simple.c "this simple example does". 2313 * Just use something like @p some_struct.sub_struct.member when adding the 2314 * member to the descriptor and it will work. 2315 * 2316 * For example: 2317 * @code 2318 * typedef struct 2319 * { 2320 * int a_number; 2321 * char *a_string; 2322 * struct { 2323 * int other_num; 2324 * int one_more; 2325 * } sub; 2326 * } some_struct; 2327 * 2328 * void some_function() 2329 * { 2330 * ... 2331 * my_desc = eet_data_descriptor_stream_new(&eddc); 2332 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_number", 2333 * a_number, EET_T_INT); 2334 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_string", 2335 * a_string, EET_T_STRING); 2336 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.other_num", 2337 * sub.other_num, EET_T_INT); 2338 * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.one_more", 2339 * sub.one_more, EET_T_INT); 2340 * ... 2341 * } 2342 * @endcode 2343 * 2344 * But this is not what we are here for today. When we talk about nested 2345 * structures, what we really want are things like lists and hashes to be 2346 * taken into consideration automatically, and all their contents saved and 2347 * loaded just like ordinary integers and strings are. 2348 * 2349 * And of course, Eet can do that, and considering the work it saves you as a 2350 * programmer, we could say it's even easier to do than handling just integers. 2351 * 2352 * Let's begin with our example then, which is not all too different from the 2353 * simple one introduced earlier. 2354 * 2355 * We won't ignore the headers this time to show how easy it is to use Eina 2356 * data types with Eet, but we'll still skip most of the code that is not 2357 * pertinent to what we want to show now, but as usual, you can get it full 2358 * by following @ref eet-data-nested.c "this link". 2359 * 2360 * @dontinclude eet-data-nested.c 2361 * @skipline Eina.h 2362 * @skipline Eet.h 2363 * @skip typedef struct 2364 * @until } My_Conf_Subtype 2365 * 2366 * Extremely similar to our previous example. Just a new struct in there, and 2367 * a pointer to a list in the one we already had. Handling a list of subtypes 2368 * is easy on our program, but now we'll see what Eet needs to work with them 2369 * (Hint: it's easy too). 2370 * @skip _my_conf_descriptor 2371 * @until _my_conf_sub_descriptor 2372 * 2373 * Since we have two structures now, it's only natural that we'll need two 2374 * descriptors. One for each, which will be defined exactly as before. 2375 * @skip static void 2376 * @until eddc 2377 * @skip EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET 2378 * @until _my_conf_sub_descriptor 2379 * 2380 * We create our descriptors, each for one type, and as before, we are going to 2381 * use a simple macro to set their contents, to save on typing. 2382 * @skip #define 2383 * @until EET_T_UCHAR 2384 * 2385 * So far, nothing new. We have our descriptors and we know already how to 2386 * save them separately. But what we want is to link them together, and even 2387 * more so, we want our main type to hold a list of more than one of the new 2388 * sub type. So how do we do that? 2389 * 2390 * Simple enough, we tell Eet that our main descriptor will hold a list, of 2391 * which each node will point to some type described by our new descriptor. 2392 * @skip EET_DATA_DESCRIPTOR_ADD_LIST 2393 * @until _my_conf_sub_descriptor 2394 * 2395 * And that's all. We are closing the function now so as to not leave dangling 2396 * curly braces, but there's nothing more to show in this example. Only other 2397 * additions are the necessary code to free our new data, but you can see it 2398 * in the full code listing. 2399 * @until } 2400 */ 2401 2402 /** 2403 * @page eet_data_file_descriptor Advanced use of Eet Data Descriptors 2404 * 2405 * A real life example is usually the best way to see how things are used, 2406 * but they also involve a lot more code than what needs to be shown, so 2407 * instead of going that way, we'll be borrowing some pieces from one in 2408 * the following example. It's been slightly modified from the original 2409 * source to show more of the varied ways in which Eet can handle our data. 2410 * 2411 * @ref eet-data-file_descriptor_01.c "This example" shows a cache of user 2412 * accounts and messages received, and it's a bit more interactive than 2413 * previous examples. 2414 * 2415 * Let's begin by looking at the structures we'll be using. First we have 2416 * one to define the messages the user receives and one for the one he posts. 2417 * Straight forward and nothing new here. 2418 * @dontinclude eet-data-file_descriptor_01.c 2419 * @skip typedef 2420 * @until My_Post 2421 * 2422 * One more to declare the account itself. This one will contain a list of 2423 * all messages received, and the posts we make ourselves will be kept in an 2424 * array. No special reason other than to show how to use arrays with Eet. 2425 * @until My_Account 2426 * 2427 * Finally, the main structure to hold our cache of accounts. We'll be looking 2428 * for these accounts by their names, so let's keep them in a hash, using 2429 * that name as the key. 2430 * @until My_Cache 2431 * 2432 * As explained before, we need one descriptor for each struct we want Eet 2433 * to handle, but this time we also want to keep around our Eet file and its 2434 * string dictionary. You will see why in a moment. 2435 * @skip Eet_Data_Descriptor 2436 * @until _my_post_descriptor 2437 * @skip Eet_File 2438 * @until Eet_Dictionary 2439 * 2440 * The differences begin now. They aren't much, but we'll be creating our 2441 * descriptors differently. Things can be added to our cache, but we won't 2442 * be modifying the current contents, so we can consider the data read from 2443 * it to be read-only, and thus allow Eet to save time and memory by not 2444 * duplicating thins unnecessary. 2445 * @skip static void 2446 * @until _my_post_descriptor 2447 * 2448 * As the comment in the code explains, we are asking Eet to give us strings 2449 * directly from the mapped file, which avoids having to load it in memory 2450 * and data duplication. 2451 * Of course, there are things to take into account when doing things this 2452 * way, and they will be mentioned as we encounter those special cases. 2453 * 2454 * Next comes the actual description of our data, just like we did in the 2455 * previous examples. 2456 * @skip #define 2457 * @until #undef 2458 * @until #define 2459 * @until #undef 2460 * 2461 * And the account struct's description doesn't add much new, but it's worth 2462 * commenting on it. 2463 * @skip #define 2464 * @until _my_post_descriptor 2465 * 2466 * How to add a list we've seen before, but now we are also adding an array. 2467 * There's nothing really special about it, but it's important to note that 2468 * the EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY is used to add arrays of variable 2469 * length to a descriptor. That is, arrays just like the one we defined. 2470 * Since there's no way in C to know how long they are, we need to keep 2471 * track of the count ourselves and Eet needs to know how to do so as well. 2472 * That's what the @p posts_count member of our struct is for. When adding 2473 * our array member, this macro will look for another variable in the struct 2474 * named just like the array, but with @p _count attached to the end. 2475 * When saving our data, Eet will know how many elements the array contains 2476 * by looking into this count variable. When loading back from a file, this 2477 * variable will be set to the right number of elements. 2478 * 2479 * Another option for arrays is to use EET_DATA_DESCRIPTOR_ADD_ARRAY, which 2480 * takes care of fixed sized arrays. 2481 * For example, let's suppose that we want to keep track of only the last 2482 * ten posts the user sent, and we declare our account struct as follows 2483 * @code 2484 * typedef struct 2485 * { 2486 * unsigned int id; 2487 * const char *name; 2488 * Eina_List *messages; 2489 * My_Post posts[10]; 2490 * } My_Account; 2491 * @endcode 2492 * Then we would add the array to our descriptor with 2493 * @code 2494 * EET_DATA_DESCRIPTOR_ADD_ARRAY(_my_account_descriptor, My_Account, "posts", 2495 * posts, _my_post_descriptor); 2496 * @endcode 2497 * 2498 * Notice how this time we don't have a @p posts_count variable in our struct. 2499 * We could have it for the program to keep track of how many posts the 2500 * array actually contains, but Eet no longer needs it. Being defined that 2501 * way the array is already taking up all the memory needed for the ten 2502 * elements, and it is possible in C to determine how much it is in code. 2503 * When saving our data, Eet will just dump the entire memory blob into the 2504 * file, regardless of how much of it is really used. So it's important to 2505 * take into consideration this kind of things when defining your data types. 2506 * Each has its uses, its advantages and disadvantages and it's up to you 2507 * to decide which to use. 2508 * 2509 * Now, going back to our example, we have to finish adding our data to the 2510 * descriptors. We are only missing the main one for the cache, which 2511 * contains our hash of accounts. 2512 * Unless you are using your own hash functions when setting the descriptor 2513 * class, always use hashes with string type keys. 2514 * @skip #define 2515 * @until } 2516 * 2517 * If you remember, we told Eet not to duplicate memory when possible at the 2518 * time of loading back our data. But this doesn't mean everything will be 2519 * loaded straight from disk and we don't have to worry about freeing it. 2520 * Data in the Eet file is compressed and encoded, so it still needs to be 2521 * decoded and memory will be allocated to convert it back into something we 2522 * can use. We also need to take care of anything we add in the current 2523 * instance of the program. 2524 * To summarize, any string we get from Eet is likely to be a pointer to the 2525 * internal dictionary, and trying to free it will, in the best case, crash 2526 * our application right away. 2527 * 2528 * So how do we know if we have to free a string? We check if it's part of 2529 * the dictionary, and if it's not there we can be sure it's safe to get 2530 * rid of it. 2531 * @skip static void 2532 * @skip } 2533 * @skip static void 2534 * @until } 2535 * 2536 * See how this is used when adding a new message to our cache. 2537 * @skip static My_Message 2538 * @until return msg 2539 * @until free(msg) 2540 * @until } 2541 * 2542 * Skipping all the utility functions used by our program (remember you can 2543 * look at the full example @ref eet-data-file_descriptor_01.c "here") we get to 2544 * our cache loading code. Nothing out of the ordinary at first, just the 2545 * same old open file, read data using our main descriptor to decode it 2546 * into something we can use and check version of loaded data and if it doesn't 2547 * match, do something accordingly. 2548 * @skip static My_Cache 2549 * @until } 2550 * @until } 2551 * @until } 2552 * 2553 * Then comes the interesting part. Remember how we kept two more global 2554 * variables with our descriptors? One of them we already used to check if 2555 * it was right to free a string or not, but we didn't know where it came from. 2556 * Loading our data straight from the mmapped file means that we can't close 2557 * it until we are done using it, so we need to keep its handler around until 2558 * then. It also means that any changes done to the file can, and will, 2559 * invalidate all our pointers to the file backed data, so if we add something 2560 * and save the file, we need to reload our cache. 2561 * 2562 * Thus our load function checks if we had an open file, if there is it gets 2563 * closed and our variable is updated to the new handler. Then we get the 2564 * string dictionary we use to check if a string is part of it or not. 2565 * Updating any references to the cache data is up you as a programmer to 2566 * handle properly, there's nothing Eet can do in this situation. 2567 * @until } 2568 * 2569 * The save function doesn't have anything new, and all that's left after it 2570 * is the main program, which doesn't really have anything of interest within 2571 * the scope of what we are learning. 2572 */ 2573 2574 /** 2575 * @addtogroup Eet_Data_Group 2576 * @{ 2577 */ 2578 #define EET_T_UNKNOW 0 /**< Unknown data encoding type */ 2579 #define EET_T_CHAR 1 /**< Data type: char */ 2580 #define EET_T_SHORT 2 /**< Data type: short */ 2581 #define EET_T_INT 3 /**< Data type: int */ 2582 #define EET_T_LONG_LONG 4 /**< Data type: long long */ 2583 #define EET_T_FLOAT 5 /**< Data type: float */ 2584 #define EET_T_DOUBLE 6 /**< Data type: double */ 2585 #define EET_T_UCHAR 7 /**< Data type: unsigned char */ 2586 #define EET_T_USHORT 8 /**< Data type: unsigned short */ 2587 #define EET_T_UINT 9 /**< Data type: unsigned int */ 2588 #define EET_T_ULONG_LONG 10 /**< Data type: unsigned long long */ 2589 #define EET_T_STRING 11 /**< Data type: char * */ 2590 #define EET_T_INLINED_STRING 12 /**< Data type: char * (but compressed inside the resulting eet) */ 2591 #define EET_T_NULL 13 /**< Data type: (void *) (only use it if you know why) */ 2592 #define EET_T_F32P32 14 /**< Data type: fixed point 32.32 */ 2593 #define EET_T_F16P16 15 /**< Data type: fixed point 16.16 */ 2594 #define EET_T_F8P24 16 /**< Data type: fixed point 8.24 */ 2595 #define EET_T_VALUE 17 /**< Data type: pointer to Eina_Value @since 1.8 */ 2596 #define EET_T_LAST 18 /**< Last data type */ 2597 2598 #define EET_G_UNKNOWN 100 /**< Unknown group data encoding type */ 2599 #define EET_G_ARRAY 101 /**< Fixed size array group type */ 2600 #define EET_G_VAR_ARRAY 102 /**< Variable size array group type */ 2601 #define EET_G_LIST 103 /**< Linked list group type */ 2602 #define EET_G_HASH 104 /**< Hash table group type */ 2603 #define EET_G_UNION 105 /**< Union group type */ 2604 #define EET_G_VARIANT 106 /**< Selectable subtype group */ 2605 #define EET_G_UNKNOWN_NESTED 107 /**< Unknown nested group type. @since 1.8 */ 2606 #define EET_G_LAST 108 /**< Last group type */ 2607 2608 #define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */ 2609 2610 /** 2611 * @typedef Eet_Data_Descriptor 2612 * 2613 * Opaque handle that have information on a type members. 2614 * 2615 * Descriptors are created using an #Eet_Data_Descriptor_Class, and they 2616 * describe the contents of the structure that will be serialized by Eet. 2617 * Not all members need be described by it, just those that should be handled 2618 * by Eet. This way it's possible to have one structure with both data to be 2619 * saved to a file, like application configuration, and runtime information 2620 * that would be meaningless to store, but is appropriate to keep together 2621 * during the program execution. 2622 * The members are added by means of 2623 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(), 2624 * EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH() 2625 * or eet_data_descriptor_element_add(). 2626 * 2627 * @see eet_data_descriptor_stream_new() 2628 * @see eet_data_descriptor_file_new() 2629 * @see eet_data_descriptor_free() 2630 */ 2631 typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor; 2632 2633 /** 2634 * @def EET_DATA_DESCRIPTOR_CLASS_VERSION 2635 * The version of #Eet_Data_Descriptor_Class at the time of the 2636 * distribution of the sources. One should define this to its 2637 * version member so it is compatible with abi changes, or at least 2638 * will not crash with them. 2639 */ 2640 #define EET_DATA_DESCRIPTOR_CLASS_VERSION 4 2641 2642 /** 2643 * @typedef Eet_Data_Descriptor_Class 2644 * 2645 * Instructs Eet about memory management for different needs under 2646 * serialization and parse process. 2647 */ 2648 typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class; 2649 2650 /** 2651 * @typedef (*Eet_Descriptor_Hash_Foreach_Callback_Callback) 2652 * 2653 * Callback prototype for Eet_Descriptor_Hash_Foreach_Callback 2654 * @param h The hash 2655 * @param k The key 2656 * @param dt The data 2657 * @param fdt The data passed to the callback 2658 * @return An integer 2659 */ 2660 typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt); 2661 2662 /** 2663 * @typedef (*Eet_Descriptor_Mem_Alloc_Callback) 2664 * 2665 * Callback prototype for Eet_Descriptor_Mem_Alloc. 2666 * @param size Is the size of memory to alloc on call of the callback 2667 */ 2668 typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size); 2669 2670 /** 2671 * @typedef (*Eet_Descriptor_Mem_Free_Callback) 2672 * 2673 * Callback prototype for Eet_Descriptor_Mem_Alloc 2674 * @param mem Must be a pointer to free on call of the callback 2675 */ 2676 typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem); 2677 2678 /** 2679 * @typedef (*Eet_Descriptor_Str_Alloc_Callback) 2680 * 2681 * Callback prototype for Eet_Descriptor_Str_Alloc 2682 * @param str Must be the string to alloc 2683 * @return have Must be an allocated char * for the given string 2684 */ 2685 typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str); 2686 2687 /** 2688 * @typedef (*Eet_Descriptor_Str_Free_Callback) 2689 * 2690 * Callback prototype for Eet_Descriptor_Str_Free 2691 * @param str Must be an allocated string to free 2692 */ 2693 typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str); 2694 2695 /** 2696 * @typedef (*Eet_Descriptor_List_Next_Callback) 2697 * 2698 * Callback prototype for Eet_Descriptor_List_Next 2699 * @param l Must be a pointer to the list 2700 * @return Must be a pointer to the list 2701 */ 2702 typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l); 2703 2704 /** 2705 * @typedef (*Eet_Descriptor_List_Append_Callback) 2706 * 2707 * Callback prototype for Eet_Descriptor_List_Append 2708 * @param l Must be a pointer to the list 2709 * @param d The data to append to the list 2710 * @return Must be a pointer to the list 2711 */ 2712 typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d); 2713 2714 2715 /** 2716 * @typedef (*Eet_Descriptor_List_Data_Callback) 2717 * 2718 * Callback prototype for Eet_Descriptor_List_Data 2719 * @param l Must be a pointer to the list 2720 * @return Must be a pointer to the list 2721 */ 2722 typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l); 2723 2724 /** 2725 * @typedef (*Eet_Descriptor_List_Free_Callback) 2726 * 2727 * Callback prototype for Eet_Descriptor_List_Free 2728 * @param l Must be a pointer to the list to free 2729 */ 2730 typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l); 2731 2732 /** 2733 * @typedef (*Eet_Descriptor_Hash_Foreach_Callback) 2734 * 2735 * Callback for Eet_Descriptor_Hash_Foreach 2736 * @param h The hash 2737 * @param func The function callback to call on each iteration 2738 * @param fdt The data to pass to the callbac setted in param func 2739 */ 2740 typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt); 2741 2742 /** 2743 * @typedef (*Eet_Descriptor_Hash_Add_Callback) 2744 * 2745 * Callback prototype for Eet_Descriptor_Hash_Add 2746 * @param h The hash 2747 * @param k The key 2748 * @param d The data to associate with the 'k' key 2749 */ 2750 typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d); 2751 2752 /** 2753 * @typedef (*Eet_Descriptor_Hash_Free_Callback) 2754 * 2755 * Callback prototype for Eet_Descriptor_Hash_Free 2756 * @param h The hash to free 2757 */ 2758 typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h); 2759 2760 /** 2761 * @typedef (*Eet_Descriptor_Str_Alloc_Callback) 2762 * 2763 * Callback prototype for Eet_Descriptor_Str_Alloc 2764 * @param str The string to allocate 2765 * @return An allocated pointer to the string 2766 */ 2767 typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str); 2768 2769 /** 2770 * @typedef (*Eet_Descriptor_Str_Free_Callback) 2771 * 2772 * Callback prototype for Eet_Descriptor_Str_Free 2773 * @param str The string to free 2774 */ 2775 typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str); 2776 2777 2778 /** 2779 * @typedef (*Eet_Descriptor_Type_Get_Callback) 2780 * 2781 * Callback prototype for Eet_Descriptor_Type_Get 2782 * @param data Data to pass to the callback 2783 * @param unknow Eina_Bool __FIXME__ 2784 */ 2785 typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow); 2786 2787 /** 2788 * @typedef (*Eet_Descriptor_Type_Set_Callback) 2789 * 2790 * Callback prototype for Eet_Descriptor_Type_Set 2791 * @param type The type to set 2792 * @param data To pass to the callback 2793 * @param unknow Eina_Bool __FIXME__ 2794 */ 2795 typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow); 2796 2797 2798 /** 2799 * @typedef (*Eet_Descriptor_Array_Alloc_Callback) 2800 * 2801 * Callback prototype for Eet_Descriptor_Array_Alloc 2802 * @param size The size of the array 2803 */ 2804 typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size); 2805 2806 /** 2807 * @typedef (*Eet_Descriptor_Array_Free_Callback) 2808 * 2809 * Callback prototype for Eet_Descriptor_Array_Free 2810 * @param size The size of the array 2811 */ 2812 typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem); 2813 /** 2814 * @struct _Eet_Data_Descriptor_Class 2815 * 2816 * Instructs Eet about memory management for different needs under 2817 * serialization and parse process. 2818 * 2819 * The list and hash methods match the Eina API, so for a more detailed 2820 * reference on them, look at the Eina_List and Eina_Hash documentation, 2821 * respectively. 2822 * For the most part these will be used with the standard Eina functions, 2823 * so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and 2824 * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything 2825 * accordingly. 2826 */ 2827 struct _Eet_Data_Descriptor_Class 2828 { 2829 int version; /**< ABI version. Should always be set to #EET_DATA_DESCRIPTOR_CLASS_VERSION */ 2830 const char *name; /**< Name of the user data type to be serialized */ 2831 int size; /**< Size in bytes of the user data type to be serialized */ 2832 struct 2833 { 2834 Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to allocate memory (usually malloc()) */ 2835 Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free memory (usually free()) */ 2836 Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to allocate a string */ 2837 Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a string */ 2838 Eet_Descriptor_List_Next_Callback list_next; /**< how to iterate to the next element of a list. Receives and should return the list node. */ 2839 Eet_Descriptor_List_Append_Callback list_append; /**< how to append data @p d to list which head node is @p l */ 2840 Eet_Descriptor_List_Data_Callback list_data; /**< retrieves the data from node @p l */ 2841 Eet_Descriptor_List_Free_Callback list_free; /**< free all the nodes from the list which head node is @p l */ 2842 Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates over all elements in the hash @p h in no specific order */ 2843 Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new data @p d with key @p k in hash @p h */ 2844 Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all entries from the hash @p h */ 2845 Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */ 2846 Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to free a string returned by str_direct_alloc */ 2847 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. */ 2848 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 */ 2849 Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to allocate memory for array (usually malloc()) */ 2850 Eet_Descriptor_Array_Free_Callback array_free; /**< how to free memory for array (usually free()) */ 2851 } func; 2852 }; 2853 2854 /** 2855 * @} 2856 */ 2857 2858 /** 2859 * 2860 * @ingroup Eet_Data_Group 2861 * @deprecated use eet_data_descriptor_stream_new() or 2862 * eet_data_descriptor_file_new() 2863 * @brief Creates a new empty data structure descriptor. 2864 * @param name The string name of this data structure (most be a 2865 * global constant and never change). 2866 * @param size The size of the struct (in bytes). 2867 * @param func_list_next The function to get the next list node. 2868 * @param func_list_append The function to append a member to a list. 2869 * @param func_list_data The function to get the data from a list node. 2870 * @param func_list_free The function to free an entire linked list. 2871 * @param func_hash_foreach The function to iterate through all 2872 * hash table entries. 2873 * @param func_hash_add The function to add a member to a hash table. 2874 * @param func_hash_free The function to free an entire hash table. 2875 * @return A new empty data descriptor. 2876 * 2877 * This function creates a new data descriptor and returns a handle to the 2878 * new data descriptor. On creation it will be empty, containing no contents 2879 * describing anything other than the shell of the data structure. 2880 * 2881 * You add structure members to the data descriptor using the macros 2882 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and 2883 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are 2884 * adding to the description. 2885 * 2886 * Once you have described all the members of a struct you want loaded, or 2887 * saved eet can load and save those members for you, encode them into 2888 * endian-independent serialised data chunks for transmission across a 2889 * a network or more. 2890 * 2891 * The function pointers to the list and hash table functions are only 2892 * needed if you use those data types, else you can pass NULL instead. 2893 * 2894 * @since 1.0.0 2895 * 2896 */ 2897 EINA_DEPRECATED EAPI Eet_Data_Descriptor * 2898 eet_data_descriptor_new(const char *name, 2899 int size, 2900 Eet_Descriptor_List_Next_Callback func_list_next, 2901 Eet_Descriptor_List_Append_Callback func_list_append, 2902 Eet_Descriptor_List_Data_Callback func_list_data, 2903 Eet_Descriptor_List_Free_Callback func_list_free, 2904 Eet_Descriptor_Hash_Foreach_Callback func_hash_foreach, 2905 Eet_Descriptor_Hash_Add_Callback func_hash_add, 2906 Eet_Descriptor_Hash_Free_Callback func_hash_free); 2907 /* 2908 * FIXME: 2909 * 2910 * moving to this api from the old above. this will break things when the 2911 * move happens - but be warned 2912 */ 2913 EINA_DEPRECATED EAPI Eet_Data_Descriptor * 2914 eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc); 2915 EINA_DEPRECATED EAPI Eet_Data_Descriptor * 2916 eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc); 2917 2918 /** 2919 * @ingroup Eet_Data_Group 2920 * This function creates a new data descriptor and returns a handle to the 2921 * new data descriptor. On creation it will be empty, containing no contents 2922 * describing anything other than the shell of the data structure. 2923 * @param eddc The class from where to create the data descriptor. 2924 * @return A handle to the new data descriptor. 2925 * 2926 * You add structure members to the data descriptor using the macros 2927 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and 2928 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are 2929 * adding to the description. 2930 * 2931 * Once you have described all the members of a struct you want loaded or 2932 * saved, eet can load and save those members for you, encode them into 2933 * endian-independent serialised data chunks for transmission across a 2934 * network or more. 2935 * 2936 * This function specially ignores str_direct_alloc and str_direct_free. It 2937 * is useful when the eet_data you are reading doesn't have a dictionary, 2938 * like network stream or IPC. It also mean that all string will be allocated 2939 * and duplicated in memory. 2940 * 2941 * @since 1.2.3 2942 */ 2943 EAPI Eet_Data_Descriptor * 2944 eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc); 2945 2946 /** 2947 * @ingroup Eet_Data_Group 2948 * This function creates a new data descriptor and returns a handle to the 2949 * new data descriptor. On creation it will be empty, containing no contents 2950 * describing anything other than the shell of the data structure. 2951 * @param eddc The class from where to create the data descriptor. 2952 * @return A handle to the new data descriptor. 2953 * 2954 * You add structure members to the data descriptor using the macros 2955 * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and 2956 * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are 2957 * adding to the description. 2958 * 2959 * Once you have described all the members of a struct you want loaded or 2960 * saved, eet can load and save those members for you, encode them into 2961 * endian-independent serialised data chunks for transmission across a 2962 * a network or more. 2963 * 2964 * This function uses str_direct_alloc and str_direct_free. It is 2965 * useful when the eet_data you are reading come from a file and 2966 * have a dictionary. This will reduce memory use and improve the 2967 * possibility for the OS to page this string out. 2968 * However, the load speed and memory saving comes with some drawbacks to keep 2969 * in mind. If you never modify the contents of the structures loaded from 2970 * the file, all you need to remember is that closing the eet file will make 2971 * the strings go away. On the other hand, should you need to free a string, 2972 * before doing so you have to verify that it's not part of the eet dictionary. 2973 * You can do this in the following way, assuming @p ef is a valid Eet_File 2974 * and @p str is a string loaded from said file. 2975 * 2976 * @code 2977 * void eet_string_free(Eet_File *ef, const char *str) 2978 * { 2979 * Eet_Dictionary *dict = eet_dictionary_get(ef); 2980 * if (dict && eet_dictionary_string_check(dict, str)) 2981 * { 2982 * // The file contains a dictionary and the given string is a part of 2983 * // of it, so we can't free it, just return. 2984 * return; 2985 * } 2986 * // We assume eina_stringshare was used on the descriptor 2987 * eina_stringshare_del(str); 2988 * } 2989 * @endcode 2990 * 2991 * @since 1.2.3 2992 */ 2993 EAPI Eet_Data_Descriptor * 2994 eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc); 2995 2996 /** 2997 * @ingroup Eet_Data_Group 2998 * This function is an helper that set all the parameters of an 2999 * Eet_Data_Descriptor_Class correctly when you use Eina data type 3000 * with a stream. 3001 * @param eddc The Eet_Data_Descriptor_Class you want to set. 3002 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time. 3003 * @param name The name of the structure described by this class. 3004 * @param size The size of the structure described by this class. 3005 * @return @c EINA_TRUE if the structure was correctly set (The only 3006 * reason that could make it fail is if you did give wrong 3007 * parameter). 3008 * 3009 * @note Unless there's a very specific reason to use this function directly, 3010 * the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended. 3011 * 3012 * @since 1.2.3 3013 */ 3014 EAPI Eina_Bool 3015 eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, 3016 unsigned int eddc_size, 3017 const char *name, 3018 int size); 3019 3020 /** 3021 * @ingroup Eet_Data_Group 3022 * This macro is an helper that set all the parameter of an 3023 * Eet_Data_Descriptor_Class correctly when you use Eina data type 3024 * with stream. 3025 * @param clas The Eet_Data_Descriptor_Class you want to set. 3026 * @param type The type of the structure described by this class. 3027 * @return EINA_TRUE if the structure was correctly set (The only 3028 * reason that could make it fail is if you did give wrong 3029 * parameter). 3030 * 3031 * @see eet_data_descriptor_stream_new 3032 * @since 1.2.3 3033 */ 3034 #define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) \ 3035 (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type))) 3036 3037 /** 3038 * @ingroup Eet_Data_Group 3039 * This function is an helper that set all the parameter of an 3040 * Eet_Data_Descriptor_Class correctly when you use Eina data type 3041 * with a file. 3042 * @param eddc The Eet_Data_Descriptor_Class you want to set. 3043 * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time. 3044 * @param name The name of the structure described by this class. 3045 * @param size The size of the structure described by this class. 3046 * @return @c EINA_TRUE if the structure was correctly set (The only 3047 * reason that could make it fail is if you did give wrong 3048 * parameter). 3049 * 3050 * @note Unless there's a very specific reason to use this function directly, 3051 * the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended. 3052 * 3053 * @since 1.2.3 3054 */ 3055 EAPI Eina_Bool 3056 eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, 3057 unsigned int eddc_size, 3058 const char *name, 3059 int size); 3060 3061 /** 3062 * @ingroup Eet_Data_Group 3063 * This macro is an helper that set all the parameter of an 3064 * Eet_Data_Descriptor_Class correctly when you use Eina data type 3065 * with file. 3066 * @param clas The Eet_Data_Descriptor_Class you want to set. 3067 * @param type The type of the structure described by this class. 3068 * @return @c EINA_TRUE if the structure was correctly set (The only 3069 * reason that could make it fail is if you did give wrong 3070 * parameter). 3071 * 3072 * @see eet_data_descriptor_file_new 3073 * @since 1.2.3 3074 */ 3075 #define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) \ 3076 (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type))) 3077 3078 /** 3079 * @ingroup Eet_Data_Group 3080 * @brief This function frees a data descriptor when it is not needed anymore. 3081 * @param edd The data descriptor to free. 3082 * 3083 * This function takes a data descriptor handle as a parameter and frees all 3084 * data allocated for the data descriptor and the handle itself. After this 3085 * call the descriptor is no longer valid. 3086 * 3087 * @since 1.0.0 3088 */ 3089 EAPI void 3090 eet_data_descriptor_free(Eet_Data_Descriptor *edd); 3091 3092 /** 3093 * @ingroup Eet_Data_Group 3094 * @brief This function returns the name of a data descriptor. 3095 * @param edd The data descriptor to get name. 3096 * @return The name of the data descriptor. 3097 * 3098 * @since 1.8.0 3099 */ 3100 EAPI const char *eet_data_descriptor_name_get(const Eet_Data_Descriptor *edd); 3101 3102 /** 3103 * @ingroup Eet_Data_Group 3104 * @brief This function is an internal used by macros. 3105 * 3106 * This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(), 3107 * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is 3108 * complex to use by hand and should be left to be used by the macros, and 3109 * thus is not documented. 3110 * 3111 * @param edd The data descriptor handle to add element (member). 3112 * @param name The name of element to be serialized. 3113 * @param type The type of element to be serialized, like 3114 * #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a 3115 * group, list or hash. 3116 * @param group_type If element type is #EET_T_UNKNOW, then the @p 3117 * group_type will specify if it is a list (#EET_G_LIST), 3118 * array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then 3119 * the member is a subtype (pointer to another type defined by 3120 * another #Eet_Data_Descriptor). 3121 * @param offset byte offset inside the source memory to be serialized. 3122 * @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY). 3123 * @param counter_name variable that defines the name of number of elements. 3124 * @param subtype If contains a subtype, then its data descriptor. 3125 * 3126 * @since 1.0.0 3127 */ 3128 EAPI void 3129 eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, 3130 const char *name, 3131 int type, 3132 int group_type, 3133 int offset, 3134 /* int count_offset, */ 3135 int count, 3136 const char *counter_name, 3137 Eet_Data_Descriptor *subtype); 3138 3139 /** 3140 * @ingroup Eet_Data_Group 3141 * @brief Reads a data structure from an eet file and decodes it. 3142 * @param ef The eet file handle to read from. 3143 * @param edd The data descriptor handle to use when decoding. 3144 * @param name The key the data is stored under in the eet file. 3145 * @return A pointer to the decoded data structure. 3146 * 3147 * This function decodes a data structure stored in an eet file, returning 3148 * a pointer to it if it decoded successfully, or NULL on failure. This 3149 * can save a programmer dozens of hours of work in writing configuration 3150 * file parsing and writing code, as eet does all that work for the program 3151 * and presents a program-friendly data structure, just as the programmer 3152 * likes. Eet can handle members being added or deleted from the data in 3153 * storage and safely zero-fills unfilled members if they were not found 3154 * in the data. It checks sizes and headers whenever it reads data, allowing 3155 * the programmer to not worry about corrupt data. 3156 * 3157 * Once a data structure has been described by the programmer with the 3158 * fields they wish to save or load, storing or retrieving a data structure 3159 * from an eet file, or from a chunk of memory is as simple as a single 3160 * function call. 3161 * 3162 * @see eet_data_read_cipher() 3163 * 3164 * @since 1.0.0 3165 */ 3166 EAPI void * 3167 eet_data_read(Eet_File *ef, 3168 Eet_Data_Descriptor *edd, 3169 const char *name); 3170 3171 /** 3172 * @ingroup Eet_Data_Group 3173 * @brief Writes a data structure from memory and store in an eet file. 3174 * @param ef The eet file handle to write to. 3175 * @param edd The data descriptor to use when encoding. 3176 * @param name The key to store the data under in the eet file. 3177 * @param data A pointer to the data structure to save and encode. 3178 * @param compress Compression flags for storage. 3179 * @return bytes Written on successful write, @c 0 on failure. 3180 * 3181 * This function is the reverse of eet_data_read(), saving a data structure 3182 * to an eet file. The file must have been opening in write mode and the data 3183 * will be kept in memory until the file is either closed or eet_sync() is 3184 * called to flush any unwritten changes. 3185 * 3186 * @see eet_data_write_cipher() 3187 * 3188 * @since 1.0.0 3189 */ 3190 EAPI int 3191 eet_data_write(Eet_File *ef, 3192 Eet_Data_Descriptor *edd, 3193 const char *name, 3194 const void *data, 3195 int compress); 3196 3197 /** 3198 * @typedef Eet_Data_Descriptor_Class 3199 * 3200 * Callback protoype for Eet_Dump 3201 * 3202 * @param data To passe to the callback 3203 * @param str The string to dump 3204 * 3205 */ 3206 typedef void (*Eet_Dump_Callback)(void *data, const char *str); 3207 3208 /** 3209 * @ingroup Eet_Data_Group 3210 * @brief Dumps an eet encoded data structure into ascii text 3211 * @param data_in The pointer to the data to decode into a struct. 3212 * @param size_in The size of the data pointed to in bytes. 3213 * @param dumpfunc The function to call passed a string when new 3214 * data is converted to text 3215 * @param dumpdata The data to pass to the @p dumpfunc callback. 3216 * @return @c 1 on success, @c 0 on failure 3217 * 3218 * This function will take a chunk of data encoded by 3219 * eet_data_descriptor_encode() and convert it into human readable 3220 * ascii text. It does this by calling the @p dumpfunc callback 3221 * for all new text that is generated. This callback should append 3222 * to any existing text buffer and will be passed the pointer @p 3223 * dumpdata as a parameter as well as a string with new text to be 3224 * appended. 3225 * 3226 * Example: 3227 * 3228 * @code 3229 * void output(void *data, const char *string) 3230 * { 3231 * printf("%s", string); 3232 * } 3233 * 3234 * void dump(const char *file) 3235 * { 3236 * FILE *f; 3237 * int len; 3238 * void *data; 3239 * 3240 * f = fopen(file, "rb"); 3241 * fseek(f, 0, SEEK_END); 3242 * len = ftell(f); 3243 * rewind(f); 3244 * data = malloc(len); 3245 * fread(data, len, 1, f); 3246 * fclose(f); 3247 * eet_data_text_dump(data, len, output, NULL); 3248 * } 3249 * @endcode 3250 * 3251 * @see eet_data_text_dump_cipher() 3252 * 3253 * @since 1.0.0 3254 */ 3255 EAPI int 3256 eet_data_text_dump(const void *data_in, 3257 int size_in, 3258 Eet_Dump_Callback dumpfunc, 3259 void *dumpdata) EINA_ARG_NONNULL(3); 3260 3261 /** 3262 * @ingroup Eet_Data_Group 3263 * @brief Takes an ascii encoding from eet_data_text_dump() and re-encode in binary. 3264 * @param text The pointer to the string data to parse and encode. 3265 * @param textlen The size of the string in bytes (not including 0 3266 * byte terminator). 3267 * @param size_ret This gets filled in with the encoded data blob 3268 * size in bytes. 3269 * @return The encoded data on success, NULL on failure. 3270 * 3271 * This function will parse the string pointed to by @p text and return 3272 * an encoded data lump the same way eet_data_descriptor_encode() takes an 3273 * in-memory data struct and encodes into a binary blob. @p text is a normal 3274 * C string. 3275 * 3276 * @see eet_data_text_undump_cipher() 3277 * 3278 * @since 1.0.0 3279 */ 3280 EAPI void * 3281 eet_data_text_undump(const char *text, 3282 int textlen, 3283 int *size_ret) EINA_ARG_NONNULL(3); 3284 3285 /** 3286 * @ingroup Eet_Data_Group 3287 * @brief Dumps an eet encoded data structure from an eet file into ascii text. 3288 * @param ef A valid eet file handle. 3289 * @param name Name of the entry. eg: "/base/file_i_want". 3290 * @param dumpfunc The function to call passed a string when new 3291 * data is converted to text 3292 * @param dumpdata The data to pass to the @p dumpfunc callback. 3293 * @return @c 1 on success, @c 0 on failure 3294 * 3295 * This function will take an open and valid eet file from 3296 * eet_open() request the data encoded by 3297 * eet_data_descriptor_encode() corresponding to the key @p name 3298 * and convert it into human readable ascii text. It does this by 3299 * calling the @p dumpfunc callback for all new text that is 3300 * generated. This callback should append to any existing text 3301 * buffer and will be passed the pointer @p dumpdata as a parameter 3302 * as well as a string with new text to be appended. 3303 * 3304 * @see eet_data_dump_cipher() 3305 * 3306 * @since 1.0.0 3307 */ 3308 EAPI int 3309 eet_data_dump(Eet_File *ef, 3310 const char *name, 3311 Eet_Dump_Callback dumpfunc, 3312 void *dumpdata) EINA_ARG_NONNULL(3); 3313 3314 /** 3315 * @ingroup Eet_Data_Group 3316 * @brief Takes an ascii encoding from eet_data_dump() and re-encode in binary. 3317 * @param ef A valid eet file handle. 3318 * @param name Name of the entry. eg: "/base/file_i_want". 3319 * @param text The pointer to the string data to parse and encode. 3320 * @param textlen The size of the string in bytes (not including 0 3321 * byte terminator). 3322 * @param compress Compression flags (1 == compress, 0 = don't compress). 3323 * @return @c 1 on success, @c 0 on failure 3324 * 3325 * This function will parse the string pointed to by @p text, 3326 * encode it the same way eet_data_descriptor_encode() takes an 3327 * in-memory data struct and encodes into a binary blob. 3328 * 3329 * The data (optionally compressed) will be in ram, pending a flush to 3330 * disk (it will stay in ram till the eet file handle is closed though). 3331 * 3332 * @see eet_data_undump_cipher() 3333 * 3334 * @since 1.0.0 3335 */ 3336 EAPI int 3337 eet_data_undump(Eet_File *ef, 3338 const char *name, 3339 const char *text, 3340 int textlen, 3341 int compress); 3342 3343 /** 3344 * @ingroup Eet_Data_Group 3345 * @brief Decodes a data structure from an arbitrary location in memory. 3346 * @param edd The data descriptor to use when decoding. 3347 * @param data_in The pointer to the data to decode into a struct. 3348 * @param size_in The size of the data pointed to in bytes. 3349 * @return NULL on failure, or a valid decoded struct pointer on success. 3350 * 3351 * This function will decode a data structure that has been encoded using 3352 * eet_data_descriptor_encode(), and return a data structure with all its 3353 * elements filled out, if successful, or NULL on failure. 3354 * 3355 * The data to be decoded is stored at the memory pointed to by @p data_in, 3356 * and is described by the descriptor pointed to by @p edd. The data size is 3357 * passed in as the value to @p size_in, and must be greater than 0 to 3358 * succeed. 3359 * 3360 * This function is useful for decoding data structures delivered to the 3361 * application by means other than an eet file, such as an IPC or socket 3362 * connection, raw files, shared memory etc. 3363 * 3364 * Please see eet_data_read() for more information. 3365 * 3366 * @see eet_data_descriptor_decode_cipher() 3367 * 3368 * @since 1.0.0 3369 */ 3370 EAPI void * 3371 eet_data_descriptor_decode(Eet_Data_Descriptor *edd, 3372 const void *data_in, 3373 int size_in); 3374 3375 /** 3376 * @ingroup Eet_Data_Group 3377 * @brief Encodes a dsata struct to memory and return that encoded data. 3378 * @param edd The data descriptor to use when encoding. 3379 * @param data_in The pointer to the struct to encode into data. 3380 * @param size_ret pointer to the an int to be filled with the decoded size. 3381 * @return NULL on failure, or a valid encoded data chunk on success. 3382 * 3383 * This function takes a data structure in memory and encodes it into a 3384 * serialised chunk of data that can be decoded again by 3385 * eet_data_descriptor_decode(). This is useful for being able to transmit 3386 * data structures across sockets, pipes, IPC or shared file mechanisms, 3387 * without having to worry about memory space, machine type, endianness etc. 3388 * 3389 * The parameter @p edd must point to a valid data descriptor, and 3390 * @p data_in must point to the right data structure to encode. If not, the 3391 * encoding may fail. 3392 * 3393 * On success a non NULL valid pointer is returned and what @p size_ret 3394 * points to is set to the size of this decoded data, in bytes. When the 3395 * encoded data is no longer needed, call free() on it. On failure NULL is 3396 * returned and what @p size_ret points to is set to 0. 3397 * 3398 * Please see eet_data_write() for more information. 3399 * 3400 * @see eet_data_descriptor_encode_cipher() 3401 * 3402 * @since 1.0.0 3403 */ 3404 EAPI void * 3405 eet_data_descriptor_encode(Eet_Data_Descriptor *edd, 3406 const void *data_in, 3407 int *size_ret); 3408 3409 /** 3410 * @ingroup Eet_Data_Group 3411 * @brief Adds a basic data element to a data descriptor. 3412 * @param edd The data descriptor to add the type to. 3413 * @param struct_type The type of the struct. 3414 * @param name The string name to use to encode/decode this member 3415 * (must be a constant global and never change). 3416 * @param member The struct member itself to be encoded. 3417 * @param type The type of the member to encode. 3418 * 3419 * This macro is a convenience macro provided to add a member to 3420 * the data descriptor @p edd. The type of the structure is 3421 * provided as the @p struct_type parameter (for example: struct 3422 * my_struct). The @p name parameter defines a string that will be 3423 * used to uniquely name that member of the struct (it is suggested 3424 * to use the struct member itself). The @p member parameter is 3425 * the actual struct member itself (for example: values), and @p type is the 3426 * basic data type of the member which must be one of: EET_T_CHAR, EET_T_SHORT, 3427 * EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR, 3428 * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING. 3429 * 3430 * @since 1.0.0 3431 */ 3432 #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \ 3433 do { \ 3434 struct_type ___ett; \ 3435 eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \ 3436 (char *)(& (___ett.member)) - \ 3437 (char *)(& (___ett)), \ 3438 0, /* 0, */ NULL, NULL); \ 3439 } while(0) 3440 3441 /** 3442 * @ingroup Eet_Data_Group 3443 * @brief Adds a sub-element type to a data descriptor. 3444 * @param edd The data descriptor to add the type to. 3445 * @param struct_type The type of the struct. 3446 * @param name The string name to use to encode/decode this member 3447 * (must be a constant global and never change). 3448 * @param member The struct member itself to be encoded. 3449 * @param subtype The type of sub-type struct to add. 3450 * 3451 * This macro lets you easily add a sub-type (a struct that's pointed to 3452 * by this one). All the parameters are the same as for 3453 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception. 3454 * This must be the data descriptor of the struct that is pointed to by 3455 * this element. 3456 * 3457 * @since 1.0.0 3458 */ 3459 #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \ 3460 do { \ 3461 struct_type ___ett; \ 3462 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \ 3463 (char *)(& (___ett.member)) - \ 3464 (char *)(& (___ett)), \ 3465 0, /* 0, */ NULL, subtype); \ 3466 } while (0) 3467 3468 /** 3469 * @ingroup Eet_Data_Group 3470 * @brief Adds a nested sub-element type to a data descriptor. 3471 * @param edd The data descriptor to add the type to. 3472 * @param struct_type The type of the struct. 3473 * @param name The string name to use to encode/decode this member 3474 * (must be a constant global and never change). 3475 * @param member The struct member itself to be encoded. 3476 * @param subtype The type of sub-type struct to add. 3477 * 3478 * This macro lets you easily add a sub-type: a struct that is nested into 3479 * this one. If your data is pointed by this element instead of being nested, 3480 * you should use EET_DATA_DESCRIPTOR_ADD_SUB(). 3481 * All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_SUB(). 3482 * 3483 * @since 1.8.0 3484 */ 3485 #define EET_DATA_DESCRIPTOR_ADD_SUB_NESTED(edd, struct_type, name, member, subtype) \ 3486 do { \ 3487 struct_type ___ett; \ 3488 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN_NESTED, \ 3489 (char *)(& (___ett.member)) - \ 3490 (char *)(& (___ett)), \ 3491 0, /* 0, */ NULL, subtype); \ 3492 } while (0) 3493 3494 /** 3495 * @ingroup Eet_Data_Group 3496 * @brief Adds a linked list type to a data descriptor. 3497 * @param edd The data descriptor to add the type to. 3498 * @param struct_type The type of the struct. 3499 * @param name The string name to use to encode/decode this member 3500 * (must be a constant global and never change). 3501 * @param member The struct member itself to be encoded. 3502 * @param subtype The type of linked list member to add. 3503 * 3504 * This macro lets you easily add a linked list of other data types. All the 3505 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the 3506 * @p subtype being the exception. This must be the data descriptor of the 3507 * element that is in each member of the linked list to be stored. 3508 * 3509 * @since 1.0.0 3510 */ 3511 #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \ 3512 do { \ 3513 struct_type ___ett; \ 3514 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \ 3515 (char *)(& (___ett.member)) - \ 3516 (char *)(& (___ett)), \ 3517 0, /* 0, */ NULL, subtype); \ 3518 } while (0) 3519 3520 /** 3521 * @ingroup Eet_Data_Group 3522 * @brief Adds a linked list of string to a data descriptor. 3523 * @param edd The data descriptor to add the type to. 3524 * @param struct_type The type of the struct. 3525 * @param name The string name to use to encode/decode this member 3526 * (must be a constant global and never change). 3527 * @param member The struct member itself to be encoded. 3528 * 3529 * This macro lets you easily add a linked list of char *. All the 3530 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). 3531 * 3532 * @since 1.5.0 3533 */ 3534 #define EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member) \ 3535 do { \ 3536 struct_type ___ett; \ 3537 eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_LIST, \ 3538 (char *)(& (___ett.member)) - \ 3539 (char *)(& (___ett)), \ 3540 0, /* 0, */ NULL, NULL); \ 3541 } while (0) 3542 3543 /** 3544 * @ingroup Eet_Data_Group 3545 * @brief Adds a linked list of unsigned integers to a data descriptor. 3546 * @param edd The data descriptor to add the type to. 3547 * @param struct_type The type of the struct. 3548 * @param name The string name to use to encode/decode this member 3549 * (must be a constant global and never change). 3550 * @param member The struct member itself to be encoded. 3551 * 3552 * This macro lets you easily add a linked list of unsigned int. All the 3553 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). 3554 * 3555 * @since 1.24.0 3556 */ 3557 #define EET_DATA_DESCRIPTOR_ADD_LIST_UINT(edd, struct_type, name, member) \ 3558 do { \ 3559 struct_type ___ett; \ 3560 eet_data_descriptor_element_add(edd, name, EET_T_UINT, EET_G_LIST, \ 3561 (char *)(& (___ett.member)) - \ 3562 (char *)(& (___ett)), \ 3563 0, /* 0, */ NULL, NULL); \ 3564 } while (0) 3565 3566 /** 3567 * @ingroup Eet_Data_Group 3568 * @brief Adds a hash type to a data descriptor. 3569 * @param edd The data descriptor to add the type to. 3570 * @param struct_type The type of the struct. 3571 * @param name The string name to use to encode/decode this member 3572 * (must be a constant global and never change). 3573 * @param member The struct member itself to be encoded. 3574 * @param subtype The type of hash member to add. 3575 * 3576 * This macro lets you easily add a hash of other data types. All the 3577 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the 3578 * @p subtype being the exception. This must be the data descriptor of the 3579 * element that is in each member of the hash to be stored. 3580 * The hash keys must be strings. 3581 * 3582 * @since 1.0.0 3583 */ 3584 #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \ 3585 do { \ 3586 struct_type ___ett; \ 3587 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \ 3588 (char *)(& (___ett.member)) - \ 3589 (char *)(& (___ett)), \ 3590 0, /* 0, */ NULL, subtype); \ 3591 } while (0) 3592 3593 /** 3594 * @ingroup Eet_Data_Group 3595 * @brief Adds a hash of string to a data descriptor. 3596 * @param edd The data descriptor to add the type to. 3597 * @param struct_type The type of the struct. 3598 * @param name The string name to use to encode/decode this member 3599 * (must be a constant global and never change). 3600 * @param member The struct member itself to be encoded. 3601 * 3602 * This macro lets you easily add a hash of string elements. All the 3603 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH(). 3604 * 3605 * @since 1.3.4 3606 */ 3607 #define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \ 3608 do { \ 3609 struct_type ___ett; \ 3610 eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH, \ 3611 (char *)(& (___ett.member)) - \ 3612 (char *)(& (___ett)), \ 3613 0, /* 0, */ NULL, NULL); \ 3614 } while (0) 3615 3616 /** 3617 * @ingroup Eet_Data_Group 3618 * @brief Adds a hash of generic value storage to a data descriptor. 3619 * @param edd The data descriptor to add the type to. 3620 * @param struct_type The type of the struct. 3621 * @param name The string name to use to encode/decode this member 3622 * (must be a constant global and never change). 3623 * @param member The struct member itself to be encoded. 3624 * 3625 * This macro lets you easily add a hash of value elements. All the 3626 * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH(). 3627 * 3628 * @since 1.18 3629 */ 3630 #define EET_DATA_DESCRIPTOR_ADD_HASH_VALUE(edd, struct_type, name, member) \ 3631 do { \ 3632 struct_type ___ett; \ 3633 eet_data_descriptor_element_add(edd, name, EET_T_VALUE, EET_G_HASH, \ 3634 (char *)(& (___ett.member)) - \ 3635 (char *)(& (___ett)), \ 3636 0, /* 0, */ NULL, NULL); \ 3637 } while (0) 3638 3639 /** 3640 * @ingroup Eet_Data_Group 3641 * @brief Adds an array of basic data elements to a data descriptor. 3642 * @param edd The data descriptor to add the type to. 3643 * @param struct_type The type of the struct. 3644 * @param name The string name to use to encode/decode this member 3645 * (must be a constant global and never change). 3646 * @param member The struct member itself to be encoded. 3647 * @param type The type of the member to encode. 3648 * 3649 * This macro lets you easily add a fixed size array of basic data 3650 * types. All the parameters are the same as for 3651 * EET_DATA_DESCRIPTOR_ADD_BASIC(). 3652 * The array must be defined with a fixed size in the declaration of the 3653 * struct containing it. 3654 * 3655 * @since 1.5.0 3656 */ 3657 #define EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member, type) \ 3658 do { \ 3659 struct_type ___ett; \ 3660 eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY, \ 3661 (char *)(& (___ett.member)) - \ 3662 (char *)(& (___ett)), \ 3663 sizeof(___ett.member) / \ 3664 sizeof(___ett.member[0]), \ 3665 NULL, NULL); \ 3666 } while(0) 3667 3668 /** 3669 * @ingroup Eet_Data_Group 3670 * @brief Adds a variable array of basic data elements to a data descriptor. 3671 * @param edd The data descriptor to add the type to. 3672 * @param struct_type The type of the struct. 3673 * @param name The string name to use to encode/decode this member 3674 * (must be a constant global and never change). 3675 * @param member The struct member itself to be encoded. 3676 * @param type The type of the member to encode. 3677 * 3678 * This macro lets you easily add a variable size array of basic data 3679 * types. All the parameters are the same as for 3680 * EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have 3681 * a struct member (of type EET_T_INT) called member_count (note the 3682 * _count appended to the member) that holds the number of items in 3683 * the array. This array will be allocated separately to the struct it 3684 * is in. 3685 * 3686 * @since 1.6.0 3687 */ 3688 #define EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, member, type) \ 3689 do { \ 3690 struct_type ___ett; \ 3691 eet_data_descriptor_element_add(edd, name, type, EET_G_VAR_ARRAY, \ 3692 (char *)(& (___ett.member)) - \ 3693 (char *)(& (___ett)), \ 3694 (char *)(& (___ett.member ## _count)) - \ 3695 (char *)(& (___ett)), \ 3696 NULL, \ 3697 NULL); \ 3698 } while(0) 3699 3700 /** 3701 * @ingroup Eet_Data_Group 3702 * @brief Adds a fixed size array type to a data descriptor. 3703 * @param edd The data descriptor to add the type to. 3704 * @param struct_type The type of the struct. 3705 * @param name The string name to use to encode/decode this member 3706 * (must be a constant global and never change). 3707 * @param member The struct member itself to be encoded. 3708 * @param subtype The type of hash member to add. 3709 * 3710 * This macro lets you easily add a fixed size array of other data 3711 * types. All the parameters are the same as for 3712 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the 3713 * exception. This must be the data descriptor of the element that 3714 * is in each member of the array to be stored. 3715 * The array must be defined with a fixed size in the declaration of the 3716 * struct containing it. 3717 * 3718 * @since 1.0.2 3719 */ 3720 #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \ 3721 do { \ 3722 struct_type ___ett; \ 3723 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \ 3724 (char *)(& (___ett.member)) - \ 3725 (char *)(& (___ett)), \ 3726 /* 0, */ sizeof(___ett.member) / \ 3727 sizeof(___ett.member[0]), NULL, subtype); \ 3728 } while (0) 3729 3730 /** 3731 * @ingroup Eet_Data_Group 3732 * @brief Adds a variable size array type to a data descriptor. 3733 * @param edd The data descriptor to add the type to. 3734 * @param struct_type The type of the struct. 3735 * @param name The string name to use to encode/decode this member 3736 * (must be a constant global and never change). 3737 * @param member The struct member itself to be encoded. 3738 * @param subtype The type of hash member to add. 3739 * 3740 * This macro lets you easily add a variable size array of other data 3741 * types. All the parameters are the same as for 3742 * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the 3743 * exception. This must be the data descriptor of the element that 3744 * is in each member of the array to be stored. This assumes you have 3745 * a struct member (of type EET_T_INT) called member_count (note the 3746 * _count appended to the member) that holds the number of items in 3747 * the array. This array will be allocated separately to the struct it 3748 * is in. 3749 * 3750 * @since 1.0.2 3751 */ 3752 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \ 3753 do { \ 3754 struct_type ___ett; \ 3755 eet_data_descriptor_element_add(edd, \ 3756 name, \ 3757 EET_T_UNKNOW, \ 3758 EET_G_VAR_ARRAY, \ 3759 (char *)(& (___ett.member)) - \ 3760 (char *)(& (___ett)), \ 3761 (char *)(& (___ett.member ## _count)) - \ 3762 (char *)(& (___ett)), \ 3763 /* 0, */ NULL, \ 3764 subtype); \ 3765 } while (0) 3766 3767 /** 3768 * @ingroup Eet_Data_Group 3769 * @brief Adds a variable size array type to a data descriptor. 3770 * @param edd The data descriptor to add the type to. 3771 * @param struct_type The type of the struct. 3772 * @param name The string name to use to encode/decode this member 3773 * (must be a constant global and never change). 3774 * @param member The struct member itself to be encoded. 3775 * 3776 * This macro lets you easily add a variable size array of strings. All 3777 * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). 3778 * 3779 * @note The strings in this array will be loaded as a single blob of memory. 3780 * 3781 * @since 1.4.0 3782 */ 3783 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member) \ 3784 do { \ 3785 struct_type ___ett; \ 3786 eet_data_descriptor_element_add(edd, \ 3787 name, \ 3788 EET_T_STRING, \ 3789 EET_G_VAR_ARRAY, \ 3790 (char *)(& (___ett.member)) - \ 3791 (char *)(& (___ett)), \ 3792 (char *)(& (___ett.member ## _count)) - \ 3793 (char *)(& (___ett)), \ 3794 /* 0, */ NULL, \ 3795 NULL); \ 3796 } while (0) 3797 3798 /** 3799 * @ingroup Eet_Data_Group 3800 * @brief Adds an union type to a data descriptor. 3801 * @param edd The data descriptor to add the type to. 3802 * @param struct_type The type of the struct. 3803 * @param name The string name to use to encode/decode this member 3804 * (must be a constant global and never change). 3805 * @param member The struct member itself to be encoded. 3806 * @param type_member The member that give hints on what is in the union. 3807 * @param unified_type Describe all possible type the union could handle. 3808 * 3809 * This macro lets you easily add an union with a member that specify what is inside. 3810 * The @p unified_type is an Eet_Data_Descriptor, but only the entry that match the name 3811 * returned by type_get will be used for each serialized data. The type_get and type_set 3812 * callback of unified_type should be defined. 3813 * 3814 * @since 1.2.4 3815 * @see Eet_Data_Descriptor_Class 3816 */ 3817 #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type) \ 3818 do { \ 3819 struct_type ___ett; \ 3820 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, \ 3821 (char *)(& (___ett.member)) - \ 3822 (char *)(& (___ett)), \ 3823 (char *)(& (___ett.type_member)) - \ 3824 (char *)(& (___ett)), \ 3825 NULL, unified_type); \ 3826 } while (0) 3827 3828 /** 3829 * @ingroup Eet_Data_Group 3830 * @brief Adds a automatically selectable type to a data descriptor. 3831 * @param edd The data descriptor to add the type to. 3832 * @param struct_type The type of the struct. 3833 * @param name The string name to use to encode/decode this member 3834 * (must be a constant global and never change). 3835 * @param member The struct member itself to be encoded. 3836 * @param type_member The member that give hints on what is in the union. 3837 * @param unified_type Describe all possible type the union could handle. 3838 * 3839 * This macro lets you easily define what the content of @p member points to depending of 3840 * the content of @p type_member. The type_get and type_set callback of unified_type should 3841 * be defined. If the the type is not know at the time of restoring it, eet will still call 3842 * type_set of @p unified_type but the pointer will be set to a serialized binary representation 3843 * of what eet know. This make it possible, to save this pointer again by just returning the string 3844 * given previously and telling it by setting unknow to EINA_TRUE. 3845 * 3846 * @since 1.2.4 3847 * @see Eet_Data_Descriptor_Class 3848 */ 3849 #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type) \ 3850 do { \ 3851 struct_type ___ett; \ 3852 eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIANT, \ 3853 (char *)(& (___ett.member)) - \ 3854 (char *)(& (___ett)), \ 3855 (char *)(& (___ett.type_member)) - \ 3856 (char *)(& (___ett)), \ 3857 NULL, unified_type); \ 3858 } while (0) 3859 3860 /** 3861 * @ingroup Eet_Data_Group 3862 * @brief Adds a mapping to a data descriptor that will be used by union, variant or inherited type. 3863 * @param unified_type The data descriptor to add the mapping to. 3864 * @param name The string name to get/set type. 3865 * @param subtype The matching data descriptor. 3866 * 3867 * @since 1.2.4 3868 * @see Eet_Data_Descriptor_Class 3869 */ 3870 #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \ 3871 eet_data_descriptor_element_add(unified_type, \ 3872 name, \ 3873 EET_T_UNKNOW, \ 3874 EET_G_UNKNOWN, \ 3875 0, \ 3876 0, \ 3877 NULL, \ 3878 subtype) 3879 3880 /** 3881 * @ingroup Eet_Data_Group 3882 * @brief Adds a mapping of a basic type to a data descriptor that will be used by a union type. 3883 * @param unified_type The data descriptor to add the mapping to. 3884 * @param name The string name to get/set type. 3885 * @param basic_type The matching basic type. 3886 * 3887 * @since 1.8 3888 * @see Eet_Data_Descriptor_Class 3889 */ 3890 #define EET_DATA_DESCRIPTOR_ADD_MAPPING_BASIC(unified_type, name, basic_type) \ 3891 eet_data_descriptor_element_add(unified_type, \ 3892 name, \ 3893 basic_type, \ 3894 EET_G_UNKNOWN, \ 3895 0, \ 3896 0, \ 3897 NULL, \ 3898 NULL) 3899 /** 3900 * @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers 3901 * @ingroup Eet_Data_Group 3902 * 3903 * Most of the @ref Eet_Data_Group have alternative versions that 3904 * accounts for ciphers to protect their content. 3905 * 3906 * @see @ref Eet_Cipher_Group 3907 * 3908 */ 3909 3910 /** 3911 * @ingroup Eet_Data_Cipher_Group 3912 * @brief Reads a data structure from an eet file and decodes it using a cipher. 3913 * @param ef The eet file handle to read from. 3914 * @param edd The data descriptor handle to use when decoding. 3915 * @param name The key the data is stored under in the eet file. 3916 * @param cipher_key The key to use as cipher. 3917 * @return A pointer to the decoded data structure. 3918 * 3919 * This function decodes a data structure stored in an eet file, returning 3920 * a pointer to it if it decoded successfully, or NULL on failure. This 3921 * can save a programmer dozens of hours of work in writing configuration 3922 * file parsing and writing code, as eet does all that work for the program 3923 * and presents a program-friendly data structure, just as the programmer 3924 * likes. Eet can handle members being added or deleted from the data in 3925 * storage and safely zero-fills unfilled members if they were not found 3926 * in the data. It checks sizes and headers whenever it reads data, allowing 3927 * the programmer to not worry about corrupt data. 3928 * 3929 * Once a data structure has been described by the programmer with the 3930 * fields they wish to save or load, storing or retrieving a data structure 3931 * from an eet file, or from a chunk of memory is as simple as a single 3932 * function call. 3933 * 3934 * @see eet_data_read() 3935 * 3936 * @since 1.0.0 3937 */ 3938 EAPI void * 3939 eet_data_read_cipher(Eet_File *ef, 3940 Eet_Data_Descriptor *edd, 3941 const char *name, 3942 const char *cipher_key); 3943 3944 /** 3945 * @ingroup Eet_Data_Cipher_Group 3946 * @brief Reads a data structure from an eet file and decodes it into a buffer using a cipher. 3947 * @param ef The eet file handle to read from. 3948 * @param edd The data descriptor handle to use when decoding. 3949 * @param name The key the data is stored under in the eet file. 3950 * @param cipher_key The key to use as cipher. 3951 * @param buffer Buffer. 3952 * @param buffer_size The buffer size. 3953 * @return A pointer to buffer if successful, and NULL on error. 3954 * 3955 * This function decodes a data structure stored in an eet file, returning 3956 * a pointer to it if it decoded successfully, or NULL on failure. This 3957 * can save a programmer dozens of hours of work in writing configuration 3958 * file parsing and writing code, as eet does all that work for the program 3959 * and presents a program-friendly data structure, just as the programmer 3960 * likes. Eet can handle members being added or deleted from the data in 3961 * storage and safely zero-fills unfilled members if they were not found 3962 * in the data. It checks sizes and headers whenever it reads data, allowing 3963 * the programmer to not worry about corrupt data. 3964 * 3965 * Once a data structure has been described by the programmer with the 3966 * fields they wish to save or load, storing or retrieving a data structure 3967 * from an eet file, or from a chunk of memory is as simple as a single 3968 * function call. 3969 * 3970 * @see eet_data_read_cipher() 3971 * 3972 * @since 1.10.0 3973 */ 3974 EAPI void * 3975 eet_data_read_cipher_buffer(Eet_File *ef, 3976 Eet_Data_Descriptor *edd, 3977 const char *name, 3978 const char *cipher_key, 3979 char *buffer, 3980 int buffer_size); 3981 3982 /** 3983 * @ingroup Eet_Data_Cipher_Group 3984 * @brief Reads a data structure from an eet extended attribute and decodes it using a cipher. 3985 * @param filename The file to extract the extended attribute from. 3986 * @param attribute The attribute to get the data from. 3987 * @param edd The data descriptor handle to use when decoding. 3988 * @param cipher_key The key to use as cipher. 3989 * @return A pointer to the decoded data structure. 3990 * 3991 * This function decodes a data structure stored in an eet extended attribute, 3992 * returning a pointer to it if it decoded successfully, or NULL on failure. 3993 * Eet can handle members being added or deleted from the data in 3994 * storage and safely zero-fills unfilled members if they were not found 3995 * in the data. It checks sizes and headers whenever it reads data, allowing 3996 * the programmer to not worry about corrupt data. 3997 * 3998 * Once a data structure has been described by the programmer with the 3999 * fields they wish to save or load, storing or retrieving a data structure 4000 * from an eet file, from a chunk of memory or from an extended attribute 4001 * is as simple as a single function call. 4002 * 4003 * @since 1.5.0 4004 */ 4005 EAPI void * 4006 eet_data_xattr_cipher_get(const char *filename, 4007 const char *attribute, 4008 Eet_Data_Descriptor *edd, 4009 const char *cipher_key); 4010 4011 /** 4012 * @ingroup Eet_Data_Cipher_Group 4013 * @brief Writes a data structure from memory and store in an eet file 4014 * using a cipher. 4015 * @param ef The eet file handle to write to. 4016 * @param edd The data descriptor to use when encoding. 4017 * @param name The key to store the data under in the eet file. 4018 * @param cipher_key The key to use as cipher. 4019 * @param data A pointer to the data structure to save and encode. 4020 * @param compress Compression flags for storage. 4021 * @return bytes written on successful write, 0 on failure. 4022 * 4023 * This function is the reverse of eet_data_read_cipher(), saving a data structure 4024 * to an eet file. 4025 * 4026 * @since 1.0.0 4027 */ 4028 EAPI int 4029 eet_data_write_cipher(Eet_File *ef, 4030 Eet_Data_Descriptor *edd, 4031 const char *name, 4032 const char *cipher_key, 4033 const void *data, 4034 int compress); 4035 4036 /** 4037 * @ingroup Eet_Data_Cipher_Group 4038 * @brief Writes a data structure from memory and store in an eet extended attribute 4039 * using a cipher. 4040 * @param filename The file to write the extended attribute to. 4041 * @param attribute The attribute to store the data to. 4042 * @param edd The data descriptor to use when encoding. 4043 * @param cipher_key The key to use as cipher. 4044 * @param data A pointer to the data structure to save and encode. 4045 * @param flags The policy to use when setting the data. 4046 * @return EINA_TRUE on success, EINA_FALSE on failure. 4047 * 4048 * This function is the reverse of eet_data_xattr_cipher_get(), saving a data structure 4049 * to an eet extended attribute. 4050 * 4051 * @since 1.5.0 4052 */ 4053 EAPI Eina_Bool 4054 eet_data_xattr_cipher_set(const char *filename, 4055 const char *attribute, 4056 Eet_Data_Descriptor *edd, 4057 const char *cipher_key, 4058 const void *data, 4059 Eina_Xattr_Flags flags); 4060 4061 /** 4062 * @ingroup Eet_Data_Cipher_Group 4063 * @brief Dumps an eet encoded data structure into ascii text using a cipher. 4064 * @param data_in The pointer to the data to decode into a struct. 4065 * @param cipher_key The key to use as cipher. 4066 * @param size_in The size of the data pointed to in bytes. 4067 * @param dumpfunc The function to call passed a string when new 4068 * data is converted to text 4069 * @param dumpdata The data to pass to the @p dumpfunc callback. 4070 * @return @c 1 on success, @c 0 on failure 4071 * 4072 * This function will take a chunk of data encoded by 4073 * eet_data_descriptor_encode() and convert it into human readable 4074 * ascii text. It does this by calling the @p dumpfunc callback 4075 * for all new text that is generated. This callback should append 4076 * to any existing text buffer and will be passed the pointer @p 4077 * dumpdata as a parameter as well as a string with new text to be 4078 * appended. 4079 * 4080 * Example: 4081 * 4082 * @code 4083 * void output(void *data, const char *string) 4084 * { 4085 * printf("%s", string); 4086 * } 4087 * 4088 * void dump(const char *file) 4089 * { 4090 * FILE *f; 4091 * int len; 4092 * void *data; 4093 * 4094 * f = fopen(file, "rb"); 4095 * fseek(f, 0, SEEK_END); 4096 * len = ftell(f); 4097 * rewind(f); 4098 * data = malloc(len); 4099 * fread(data, len, 1, f); 4100 * fclose(f); 4101 * eet_data_text_dump_cipher(data, cipher_key, len, output, NULL); 4102 * } 4103 * @endcode 4104 * 4105 * @see eet_data_text_dump() 4106 * 4107 * @since 1.0.0 4108 */ 4109 EAPI int 4110 eet_data_text_dump_cipher(const void *data_in, 4111 const char *cipher_key, 4112 int size_in, 4113 Eet_Dump_Callback dumpfunc, 4114 void *dumpdata) EINA_ARG_NONNULL(4); 4115 4116 /** 4117 * @ingroup Eet_Data_Cipher_Group 4118 * @brief Takes an ascii encoding from eet_data_text_dump() and re-encode 4119 * in binary using a cipher. 4120 * @param text The pointer to the string data to parse and encode. 4121 * @param cipher_key The key to use as cipher. 4122 * @param textlen The size of the string in bytes (not including 0 4123 * byte terminator). 4124 * @param size_ret This gets filled in with the encoded data blob 4125 * size in bytes. 4126 * @return The encoded data on success, NULL on failure. 4127 * 4128 * This function will parse the string pointed to by @p text and return 4129 * an encoded data lump the same way eet_data_descriptor_encode() takes an 4130 * in-memory data struct and encodes into a binary blob. @p text is a normal 4131 * C string. 4132 * 4133 * @see eet_data_text_undump() 4134 * 4135 * @since 1.0.0 4136 */ 4137 EAPI void * 4138 eet_data_text_undump_cipher(const char *text, 4139 const char *cipher_key, 4140 int textlen, 4141 int *size_ret) EINA_ARG_NONNULL(4); 4142 4143 /** 4144 * @ingroup Eet_Data_Cipher_Group 4145 * @brief Dumps an eet encoded data structure from an eet file into ascii 4146 * text using a cipher. 4147 * @param ef A valid eet file handle. 4148 * @param name Name of the entry. eg: "/base/file_i_want". 4149 * @param cipher_key The key to use as cipher. 4150 * @param dumpfunc The function to call passed a string when new 4151 * data is converted to text 4152 * @param dumpdata The data to pass to the @p dumpfunc callback. 4153 * @return @c 1 on success, @c 0 on failure 4154 * 4155 * This function will take an open and valid eet file from 4156 * eet_open() request the data encoded by 4157 * eet_data_descriptor_encode() corresponding to the key @p name 4158 * and convert it into human readable ascii text. It does this by 4159 * calling the @p dumpfunc callback for all new text that is 4160 * generated. This callback should append to any existing text 4161 * buffer and will be passed the pointer @p dumpdata as a parameter 4162 * as well as a string with new text to be appended. 4163 * 4164 * @see eet_data_dump() 4165 * 4166 * @since 1.0.0 4167 */ 4168 EAPI int 4169 eet_data_dump_cipher(Eet_File *ef, 4170 const char *name, 4171 const char *cipher_key, 4172 Eet_Dump_Callback dumpfunc, 4173 void *dumpdata) EINA_ARG_NONNULL(4); 4174 4175 /** 4176 * @ingroup Eet_Data_Cipher_Group 4177 * @brief Takes an ascii encoding from eet_data_dump() and re-encode in 4178 * binary using a cipher. 4179 * @param ef A valid eet file handle. 4180 * @param name Name of the entry. eg: "/base/file_i_want". 4181 * @param cipher_key The key to use as cipher. 4182 * @param text The pointer to the string data to parse and encode. 4183 * @param textlen The size of the string in bytes (not including 0 4184 * byte terminator). 4185 * @param compress Compression flags (1 == compress, 0 = don't compress). 4186 * @return @c 1 on success, @c 0 on failure 4187 * 4188 * This function will parse the string pointed to by @p text, 4189 * encode it the same way eet_data_descriptor_encode() takes an 4190 * in-memory data struct and encodes into a binary blob. 4191 * 4192 * The data (optionally compressed) will be in ram, pending a flush to 4193 * disk (it will stay in ram till the eet file handle is closed though). 4194 * 4195 * @see eet_data_undump() 4196 * 4197 * @since 1.0.0 4198 */ 4199 EAPI int 4200 eet_data_undump_cipher(Eet_File *ef, 4201 const char *name, 4202 const char *cipher_key, 4203 const char *text, 4204 int textlen, 4205 int compress); 4206 4207 /** 4208 * @ingroup Eet_Data_Cipher_Group 4209 * @brief Decodes a data structure from an arbitrary location in memory 4210 * using a cipher. 4211 * @param edd The data descriptor to use when decoding. 4212 * @param data_in The pointer to the data to decode into a struct. 4213 * @param cipher_key The key to use as cipher. 4214 * @param size_in The size of the data pointed to in bytes. 4215 * @return NULL on failure, or a valid decoded struct pointer on success. 4216 * 4217 * This function will decode a data structure that has been encoded using 4218 * eet_data_descriptor_encode(), and return a data structure with all its 4219 * elements filled out, if successful, or NULL on failure. 4220 * 4221 * The data to be decoded is stored at the memory pointed to by @p data_in, 4222 * and is described by the descriptor pointed to by @p edd. The data size is 4223 * passed in as the value to @p size_in, and must be greater than 0 to 4224 * succeed. 4225 * 4226 * This function is useful for decoding data structures delivered to the 4227 * application by means other than an eet file, such as an IPC or socket 4228 * connection, raw files, shared memory etc. 4229 * 4230 * Please see eet_data_read() for more information. 4231 * 4232 * @see eet_data_descriptor_decode() 4233 * 4234 * @since 1.0.0 4235 */ 4236 EAPI void * 4237 eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd, 4238 const void *data_in, 4239 const char *cipher_key, 4240 int size_in); 4241 4242 /** 4243 * @ingroup Eet_Data_Cipher_Group 4244 * @brief Encodes a data struct to memory and return that encoded data 4245 * using a cipher. 4246 * @param edd The data descriptor to use when encoding. 4247 * @param data_in The pointer to the struct to encode into data. 4248 * @param cipher_key The key to use as cipher. 4249 * @param size_ret pointer to the an int to be filled with the decoded size. 4250 * @return NULL on failure, or a valid encoded data chunk on success. 4251 * 4252 * This function takes a data structure in memory and encodes it into a 4253 * serialised chunk of data that can be decoded again by 4254 * eet_data_descriptor_decode(). This is useful for being able to transmit 4255 * data structures across sockets, pipes, IPC or shared file mechanisms, 4256 * without having to worry about memory space, machine type, endianness etc. 4257 * 4258 * The parameter @p edd must point to a valid data descriptor, and 4259 * @p data_in must point to the right data structure to encode. If not, the 4260 * encoding may fail. 4261 * 4262 * On success a non NULL valid pointer is returned and what @p size_ret 4263 * points to is set to the size of this decoded data, in bytes. When the 4264 * encoded data is no longer needed, call free() on it. On failure NULL is 4265 * returned and what @p size_ret points to is set to 0. 4266 * 4267 * Please see eet_data_write() for more information. 4268 * 4269 * @see eet_data_descriptor_encode() 4270 * 4271 * @since 1.0.0 4272 */ 4273 EAPI void * 4274 eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd, 4275 const void *data_in, 4276 const char *cipher_key, 4277 int *size_ret); 4278 4279 /** 4280 * @defgroup Eet_Node_Group Low-level Serialization Structures. 4281 * @ingroup Eet 4282 * 4283 * Functions that create, destroy and manipulate serialization nodes 4284 * used by @ref Eet_Data_Group. 4285 * 4286 * @{ 4287 */ 4288 4289 /** 4290 * @typedef Eet_Node 4291 * Opaque handle to manage serialization node. 4292 */ 4293 typedef struct _Eet_Node Eet_Node; 4294 4295 /** 4296 * @typedef Eet_Node_Data 4297 * Contains an union that can fit any kind of node. 4298 */ 4299 typedef struct _Eet_Node_Data Eet_Node_Data; 4300 4301 /** 4302 * @struct _Eet_Node_Data 4303 * Contains an union that can fit any kind of node. 4304 */ 4305 struct _Eet_Node_Data 4306 { 4307 union { 4308 char c; 4309 short s; 4310 int i; 4311 long long l; 4312 float f; 4313 double d; 4314 unsigned char uc; 4315 unsigned short us; 4316 unsigned int ui; 4317 unsigned long long ul; 4318 const char *str; 4319 } value; 4320 }; 4321 4322 /** 4323 * @} 4324 */ 4325 4326 /** 4327 * @ingroup Eet_Node_Group 4328 * @brief Creates a new character node. 4329 * @param name Name of the node. 4330 * @param c Character value. 4331 * @return A new character node. 4332 */ 4333 EAPI Eet_Node * 4334 eet_node_char_new(const char *name, 4335 char c); 4336 4337 /** 4338 * @ingroup Eet_Node_Group 4339 * @brief Creates a new short node. 4340 * @param name Name of the node. 4341 * @param s Short value. 4342 * @return A new short node. 4343 */ 4344 EAPI Eet_Node * 4345 eet_node_short_new(const char *name, 4346 short s); 4347 4348 /** 4349 * @ingroup Eet_Node_Group 4350 * @brief Creates a new integer node. 4351 * @param name Name of the node. 4352 * @param i Integer value. 4353 * @return A new integer node. 4354 */ 4355 EAPI Eet_Node * 4356 eet_node_int_new(const char *name, 4357 int i); 4358 4359 /** 4360 * @ingroup Eet_Node_Group 4361 * @brief Creates a new long long integer node. 4362 * @param name Name of the node. 4363 * @param l Long long integer value. 4364 * @return A new long long integer node. 4365 */ 4366 EAPI Eet_Node * 4367 eet_node_long_long_new(const char *name, 4368 long long l); 4369 4370 /** 4371 * @ingroup Eet_Node_Group 4372 * @brief Creates a new float node. 4373 * @param name Name of the node. 4374 * @param f Float value. 4375 * @return A new float node. 4376 */ 4377 EAPI Eet_Node * 4378 eet_node_float_new(const char *name, 4379 float f); 4380 4381 /** 4382 * @ingroup Eet_Node_Group 4383 * @brief Creates a new double node. 4384 * @param name Name of the node. 4385 * @param d Double value. 4386 * @return A new double node. 4387 */ 4388 EAPI Eet_Node * 4389 eet_node_double_new(const char *name, 4390 double d); 4391 4392 /** 4393 * @ingroup Eet_Node_Group 4394 * @brief Creates a new unsigned character node. 4395 * @param name Name of the node. 4396 * @param uc Unsigned char value. 4397 * @return A new unsigned char node. 4398 */ 4399 EAPI Eet_Node * 4400 eet_node_unsigned_char_new(const char *name, 4401 unsigned char uc); 4402 4403 /** 4404 * @ingroup Eet_Node_Group 4405 * @brief Creates a new unsigned short node. 4406 * @param name Name of the node. 4407 * @param us Unsigned short value. 4408 * @return A new unsigned short node. 4409 */ 4410 EAPI Eet_Node * 4411 eet_node_unsigned_short_new(const char *name, 4412 unsigned short us); 4413 4414 /** 4415 * @ingroup Eet_Node_Group 4416 * @brief Creates a new unsigned integer node. 4417 * @param name Name of the node. 4418 * @param ui Unsigned integer value. 4419 * @return A new unsigned integer node. 4420 */ 4421 EAPI Eet_Node * 4422 eet_node_unsigned_int_new(const char *name, 4423 unsigned int ui); 4424 4425 /** 4426 * @ingroup Eet_Node_Group 4427 * @brief Creates a new unsigned long long integer node. 4428 * @param name Name of the node. 4429 * @param l Unsigned long long integer value. 4430 * @return A new unsigned long long integer node. 4431 */ 4432 EAPI Eet_Node * 4433 eet_node_unsigned_long_long_new(const char *name, 4434 unsigned long long l); 4435 4436 /** 4437 * @ingroup Eet_Node_Group 4438 * @brief Creates a new string node. 4439 * @param name Name of the node. 4440 * @param str String value. 4441 * @return A new string node. 4442 */ 4443 EAPI Eet_Node * 4444 eet_node_string_new(const char *name, 4445 const char *str); 4446 4447 /** 4448 * @ingroup Eet_Node_Group 4449 * @brief Creates a new inlined string node. 4450 * @param name Name of the node. 4451 * @param str String value. 4452 * @return A new inlined string node. 4453 */ 4454 EAPI Eet_Node * 4455 eet_node_inlined_string_new(const char *name, 4456 const char *str); 4457 4458 /** 4459 * @ingroup Eet_Node_Group 4460 * @brief Creates a new empty node. 4461 * @param name Name of the node. 4462 * @return A new empty node. 4463 */ 4464 EAPI Eet_Node * 4465 eet_node_null_new(const char *name); 4466 4467 /** 4468 * @ingroup Eet_Node_Group 4469 * @brief Creates a new list node. 4470 * @param name Name of the node. 4471 * @param nodes List of nodes. 4472 * @return A new list node. 4473 */ 4474 EAPI Eet_Node * 4475 eet_node_list_new(const char *name, 4476 Eina_List *nodes); 4477 4478 /** 4479 * @ingroup Eet_Node_Group 4480 * @brief Creates a new array node. 4481 * @param name Name of the node. 4482 * @param count Number of nodes 4483 * @param nodes List of nodes. 4484 * @return A new array node. 4485 */ 4486 EAPI Eet_Node * 4487 eet_node_array_new(const char *name, 4488 int count, 4489 Eina_List *nodes); 4490 4491 /** 4492 * @ingroup Eet_Node_Group 4493 * @brief Creates a new variable array node. 4494 * @param name Name of the node. 4495 * @param nodes List of nodes. 4496 * @return A new variable array node. 4497 */ 4498 EAPI Eet_Node * 4499 eet_node_var_array_new(const char *name, 4500 Eina_List *nodes); 4501 4502 /** 4503 * TODO FIX ME 4504 * @ingroup Eet_Node_Group 4505 */ 4506 /** 4507 * @ingroup Eet_Node_Group 4508 * @brief Creates a new hash node. 4509 * @param name Name of the node. 4510 * @param key Key of the node. 4511 * @param node The node. 4512 * @return A new hash node. 4513 */ 4514 EAPI Eet_Node * 4515 eet_node_hash_new(const char *name, 4516 const char *key, 4517 Eet_Node *node); 4518 4519 /** 4520 * @ingroup Eet_Node_Group 4521 * @brief Creates a new struct node. 4522 * @param name Name of the node. 4523 * @param nodes List of nodes. 4524 * @return A new struct node. 4525 */ 4526 EAPI Eet_Node * 4527 eet_node_struct_new(const char *name, 4528 Eina_List *nodes); 4529 4530 /** 4531 * TODO FIX ME 4532 * @ingroup Eet_Node_Group 4533 */ 4534 /** 4535 * @ingroup Eet_Node_Group 4536 * @brief Creates a new struct child node. 4537 * @param parent The name of parent node. 4538 * @param child The child node. 4539 * @return A new struct child node. 4540 */ 4541 EAPI Eet_Node * 4542 eet_node_struct_child_new(const char *parent, 4543 Eet_Node *child); 4544 4545 /** 4546 * @ingroup Eet_Node_Group 4547 * @brief Gets a node's child nodes. 4548 * @param node The node 4549 * @return The first child node which contains a pointer to the 4550 * next child node and the parent. 4551 * @since 1.5 4552 */ 4553 EAPI Eet_Node * 4554 eet_node_children_get(Eet_Node *node); 4555 4556 /** 4557 * @ingroup Eet_Node_Group 4558 * @brief Gets the next node in a list of nodes. 4559 * @param node The node 4560 * @return A node which contains a pointer to the 4561 * next child node and the parent. 4562 * @since 1.5 4563 */ 4564 EAPI Eet_Node * 4565 eet_node_next_get(Eet_Node *node); 4566 4567 /** 4568 * @ingroup Eet_Node_Group 4569 * @brief Gets the parent node of a node. 4570 * @param node The node 4571 * @return The parent node of @p node 4572 * @since 1.5 4573 */ 4574 EAPI Eet_Node * 4575 eet_node_parent_get(Eet_Node *node); 4576 4577 /** 4578 * @ingroup Eet_Node_Group 4579 * @brief Appends a "list" node TODO FIX ME. 4580 * @param parent The parent node. 4581 * @param name The name of new node. 4582 * @param child The child node. 4583 */ 4584 EAPI void 4585 eet_node_list_append(Eet_Node *parent, 4586 const char *name, 4587 Eet_Node *child); 4588 4589 /** 4590 * TODO FIX ME 4591 * @ingroup Eet_Node_Group 4592 * @brief Appends a struct node. 4593 * @param parent The parent node. 4594 * @param name The name of new node. 4595 * @param child The child node. 4596 */ 4597 EAPI void 4598 eet_node_struct_append(Eet_Node *parent, 4599 const char *name, 4600 Eet_Node *child); 4601 4602 /** 4603 * TODO FIX ME 4604 * @ingroup Eet_Node_Group 4605 * @brief Adds a hash node. 4606 * @param parent The parent node. 4607 * @param name Name of the node. 4608 * @param key Key of the node. 4609 * @param child The child node. 4610 */ 4611 EAPI void 4612 eet_node_hash_add(Eet_Node *parent, 4613 const char *name, 4614 const char *key, 4615 Eet_Node *child); 4616 4617 /** 4618 * TODO FIX ME 4619 * @ingroup Eet_Node_Group 4620 * @brief Dumps a node from an eet encoded data structure into ascii text. 4621 * @param n The node. 4622 * @param dumplevel The dump level. 4623 * @param dumpfunc dumpfunc The function to call passed a string when new 4624 * data is converted to text. 4625 * @param dumpdata The data to pass to the @p dumpfunc callback. 4626 */ 4627 EAPI void 4628 eet_node_dump(Eet_Node *n, 4629 int dumplevel, 4630 Eet_Dump_Callback dumpfunc, 4631 void *dumpdata); 4632 4633 /** 4634 * @ingroup Eet_Node_Group 4635 * @brief Returns the type of a node. 4636 * @param node The node 4637 * @return The node's type (EET_T_$TYPE) 4638 * @since 1.5 4639 */ 4640 EAPI int 4641 eet_node_type_get(Eet_Node *node); 4642 4643 /** 4644 * @ingroup Eet_Node_Group 4645 * @brief Returns the node's data. 4646 * @param node The node 4647 * @return The data contained in the node 4648 * @since 1.5 4649 */ 4650 EAPI Eet_Node_Data * 4651 eet_node_value_get(Eet_Node *node); 4652 4653 /** 4654 * TODO FIX ME 4655 * @ingroup Eet_Node_Group 4656 * @brief Deletes the given node. 4657 * @param n The node. 4658 */ 4659 EAPI void 4660 eet_node_del(Eet_Node *n); 4661 4662 /** 4663 * TODO FIX ME 4664 * @ingroup Eet_Node_Group 4665 * @brief Encodes node data using a cipher. 4666 * @param node The node. 4667 * @param cipher_key The key to use as cipher. 4668 * @param size_ret Number of bytes read from entry and returned. 4669 */ 4670 EAPI void * 4671 eet_data_node_encode_cipher(Eet_Node *node, 4672 const char *cipher_key, 4673 int *size_ret); 4674 4675 /** 4676 * TODO FIX ME 4677 * @ingroup Eet_Node_Group 4678 * @brief Decodes node data using a cipher. 4679 * @param data_in The pointer to the data to decode into a struct. 4680 * @param cipher_key The key to use as cipher. 4681 * @param size_in The size of the data pointed to in bytes. 4682 * @return The decoded node. 4683 */ 4684 EAPI Eet_Node * 4685 eet_data_node_decode_cipher(const void *data_in, 4686 const char *cipher_key, 4687 int size_in); 4688 4689 /** 4690 * TODO FIX ME 4691 * @ingroup Eet_Node_Group 4692 * @brief Reads a node data from an eet file and decodes it using a cipher. 4693 * @param ef The eet file handle to read from. 4694 * @param name The key the data is stored under in the eet file. 4695 * @param cipher_key The key to use as cipher. 4696 * @return A node to the decoded data structure. 4697 */ 4698 EAPI Eet_Node * 4699 eet_data_node_read_cipher(Eet_File *ef, 4700 const char *name, 4701 const char *cipher_key); 4702 4703 /** 4704 * TODO FIX ME 4705 * @ingroup Eet_Node_Group 4706 * @brief Writes node data to the named key in an eet file using a cipher. 4707 * @param ef The eet file handle to write to. 4708 * @param name The key to store the data under in the eet file. 4709 * @param cipher_key The key to use as cipher. 4710 * @param node The node. 4711 * @param compress Compression flags for storage. 4712 * @return bytes written on successful write, 0 on failure. 4713 */ 4714 EAPI int 4715 eet_data_node_write_cipher(Eet_File *ef, 4716 const char *name, 4717 const char *cipher_key, 4718 Eet_Node *node, 4719 int compress); 4720 4721 /* EXPERIMENTAL: THIS API MAY CHANGE IN THE FUTURE, USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING. */ 4722 4723 /** 4724 * @typedef Eet_Node_Walk 4725 * Describes how to walk trees of #Eet_Node. 4726 */ 4727 typedef struct _Eet_Node_Walk Eet_Node_Walk; 4728 4729 /** 4730 * @typedef (*Eet_Node_Walk_Struct_Alloc_Callback) 4731 * 4732 * Callback prototype for Eet_Node_Walk_Struct_Alloc 4733 * @param type The allocation type 4734 * @param user_data The data passed by the user to the callback 4735 */ 4736 typedef void * (*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void *user_data); 4737 4738 /** 4739 * @typedef (*Eet_Node_Walk_Struct_Add_Callback) 4740 * 4741 * Callback prototype for Eet_Node_Walk_Struct_Add 4742 * @param parent The parent node 4743 * @param name The name for the new node 4744 * @param child The child node 4745 * @param user_data The data passed by the user to the callback 4746 */ 4747 typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char *name, void *child, void *user_data); 4748 4749 /** 4750 * @typedef (*Eet_Node_Walk_Array_Callback) 4751 * 4752 * Callback prototype for Eet_Node_Walk_Array 4753 * @param variable @c EINA_TRUE or @c EINA_FALSE 4754 * @param name A name 4755 * @param count A counter 4756 * @param user_data The data passed by the user to the callback 4757 */ 4758 typedef void * (*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const char *name, int count, void *user_data); 4759 4760 typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void *child, void *user_data); 4761 typedef void * (*Eet_Node_Walk_List_Callback)(const char *name, void *user_data); 4762 typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, void *user_data); 4763 typedef void * (*Eet_Node_Walk_Hash_Callback)(void *parent, const char *name, const char *key, void *value, void *user_data); 4764 typedef void * (*Eet_Node_Walk_Simple_Callback)(int type, Eet_Node_Data *data, void *user_data); 4765 4766 /** 4767 * @struct _Eet_Node_Walk 4768 * Describes how to walk trees of #Eet_Node. 4769 */ 4770 struct _Eet_Node_Walk 4771 { 4772 Eet_Node_Walk_Struct_Alloc_Callback struct_alloc; 4773 Eet_Node_Walk_Struct_Add_Callback struct_add; 4774 Eet_Node_Walk_Array_Callback array; 4775 Eet_Node_Walk_Insert_Callback insert; 4776 Eet_Node_Walk_List_Callback list; 4777 Eet_Node_Walk_Append_Callback append; 4778 Eet_Node_Walk_Hash_Callback hash; 4779 Eet_Node_Walk_Simple_Callback simple; 4780 }; 4781 4782 /** 4783 * @ingroup Eet_Node_Group 4784 * Walks trees of #Eet_Node 4785 */ 4786 EAPI void * 4787 eet_node_walk(void *parent, 4788 const char *name, 4789 Eet_Node *root, 4790 Eet_Node_Walk *cb, 4791 void *user_data); 4792 4793 /*******/ 4794 4795 /** 4796 * @defgroup Eet_Connection_Group Helper function to use eet over a network link 4797 * @ingroup Eet 4798 * 4799 * Function that reconstruct and prepare packet of @ref Eet_Data_Group to be send. 4800 * 4801 */ 4802 4803 /** 4804 * @ingroup Eet_Connection_Group 4805 * @typedef Eet_Connection 4806 * Opaque handle to track paquet for a specific connection. 4807 * 4808 */ 4809 typedef struct _Eet_Connection Eet_Connection; 4810 4811 /** 4812 * @ingroup Eet_Connection_Group 4813 * @typedef Eet_Read_Cb 4814 * Called back when an @ref Eet_Data_Group has been received completely and could be used. 4815 * 4816 */ 4817 typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *user_data); 4818 4819 /** 4820 * @ingroup Eet_Connection_Group 4821 * @typedef Eet_Write_Cb 4822 * Called back when a packet containing @ref Eet_Data_Group data is ready to be send. 4823 * 4824 */ 4825 typedef Eina_Bool Eet_Write_Cb (const void *data, size_t size, void *user_data); 4826 4827 /** 4828 * @ingroup Eet_Connection_Group 4829 * @brief Instanciates a new connection to track. 4830 * @param eet_read_cb Function to call when one Eet_Data packet has been fully assemble. 4831 * @param eet_write_cb Function to call when one Eet_Data packet is ready to be send over the wire. 4832 * @param user_data Pointer provided to both functions to be used as a context handler. 4833 * @return @c NULL on failure, or a valid Eet_Connection handler. 4834 * 4835 * For every connection to track you will need a separate Eet_Connection provider. 4836 * 4837 * @since 1.2.4 4838 */ 4839 EAPI Eet_Connection * 4840 eet_connection_new(Eet_Read_Cb *eet_read_cb, 4841 Eet_Write_Cb *eet_write_cb, 4842 const void *user_data); 4843 4844 /** 4845 * @ingroup Eet_Connection_Group 4846 * @brief Processes a raw packet received over the link. 4847 * @param conn Connection handler to track. 4848 * @param data Raw data packet. 4849 * @param size The size of that packet. 4850 * @return @c 0 on complete success, any other value indicate where in the stream it got wrong (It could be before that packet). 4851 * 4852 * Every time you receive a packet related to your connection, you should pass 4853 * it to that function so that it could process and assemble packet has you 4854 * receive it. It will automatically call Eet_Read_Cb when one is fully received. 4855 * 4856 * @since 1.2.4 4857 */ 4858 EAPI int 4859 eet_connection_received(Eet_Connection *conn, 4860 const void *data, 4861 size_t size); 4862 4863 /** 4864 * @ingroup Eet_Connection_Group 4865 * @brief Tells if the Eet_Connection as received some partial data. 4866 * @param conn Connection handler to request. 4867 * @return @c EINA_TRUE if there is some data pending inside, @c EINA_FALSE otherwise. 4868 * 4869 * Eet_Connection buffer data until the received data can be unserialized correctly. This 4870 * function let you know if there is some data inside that buffer waiting for more data to 4871 * be received before being processed. 4872 * 4873 * @since 1.7 4874 */ 4875 EAPI Eina_Bool eet_connection_empty(Eet_Connection *conn); 4876 4877 /** 4878 * @ingroup Eet_Connection_Group 4879 * @brief Converts a complex structure and prepare it to be send. 4880 * @param conn Connection handler to track. 4881 * @param edd The data descriptor to use when encoding. 4882 * @param data_in The pointer to the struct to encode into data. 4883 * @param cipher_key The key to use as cipher. 4884 * @return @c EINA_TRUE if the data where correctly send, @c EINA_FALSE if they don't. 4885 * 4886 * This function serialize data_in with edd, assemble the packet and call 4887 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated 4888 * and will vanish just after the return of the callback. 4889 * 4890 * @see eet_data_descriptor_encode_cipher 4891 * 4892 * @since 1.2.4 4893 */ 4894 EAPI Eina_Bool 4895 eet_connection_send(Eet_Connection *conn, 4896 Eet_Data_Descriptor *edd, 4897 const void *data_in, 4898 const char *cipher_key); 4899 4900 /** 4901 * @ingroup Eet_Connection_Group 4902 * @brief Converts a Eet_Node tree and prepare it to be send. 4903 * @param conn Connection handler to track. 4904 * @param node The data tree to use when encoding. 4905 * @param cipher_key The key to use as cipher. 4906 * @return @c EINA_TRUE if the data where correctly send, @c EINA_FALSE if they don't. 4907 * 4908 * This function serialize node, assemble the packet and call 4909 * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated 4910 * and will vanish just after the return of the callback. 4911 * 4912 * @see eet_data_node_encode_cipher 4913 * 4914 * @since 1.2.4 4915 */ 4916 EAPI Eina_Bool 4917 eet_connection_node_send(Eet_Connection *conn, 4918 Eet_Node *node, 4919 const char *cipher_key); 4920 4921 /** 4922 * @ingroup Eet_Connection_Group 4923 * @brief Closes a connection and lost its track. 4924 * @param conn Connection handler to close. 4925 * @param on_going Signal if a partial packet wasn't completed. 4926 * @return the user_data passed to both callback. 4927 * 4928 * @since 1.2.4 4929 */ 4930 EAPI void * 4931 eet_connection_close(Eet_Connection *conn, 4932 Eina_Bool *on_going); 4933 4934 /***************************************************************************/ 4935 #ifdef __cplusplus 4936 } 4937 #endif /* ifdef __cplusplus */ 4938 4939 #undef EAPI 4940 #define EAPI 4941 4942 #endif /* ifndef _EET_H */ 4943