src/lib/Eet.h

   1 #ifndef _EET_H
   2 #define _EET_H
   3
   4 #include <stdlib.h>
   5 #include <stdio.h>
   6
   7 #ifdef EAPI
   8 # undef EAPI
   9 #endif
  10
  11 #ifdef _WIN32
  12 # ifdef EFL_EET_BUILD
  13 #  ifdef DLL_EXPORT
  14 #   define EAPI __declspec(dllexport)
  15 #  else
  16 #   define EAPI
  17 #  endif /* ! DLL_EXPORT */
  18 # else
  19 #  define EAPI __declspec(dllimport)
  20 # endif /* ! EFL_EET_BUILD */
  21 #else
  22 # ifdef __GNUC__
  23 #  if __GNUC__ >= 4
  24 #   define EAPI __attribute__ ((visibility("default")))
  25 #  else
  26 #   define EAPI
  27 #  endif
  28 # else
  29 #  define EAPI
  30 # endif
  31 #endif /* ! _WIN32 */
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * @file Eet.h
  39  * @brief The file that provides the eet functions.
  40  *
  41  * This header provides the Eet management functions.
  42  *
  43  */
  44
  45 /***************************************************************************/
  46
  47 #define EET_T_UNKNOW            0 /**< Unknown data encoding type */
  48 #define EET_T_CHAR              1 /**< Data type: char */
  49 #define EET_T_SHORT             2 /**< Data type: short */
  50 #define EET_T_INT               3 /**< Data type: int */
  51 #define EET_T_LONG_LONG         4 /**< Data type: long long */
  52 #define EET_T_FLOAT             5 /**< Data type: float */
  53 #define EET_T_DOUBLE            6 /**< Data type: double */
  54 #define EET_T_UCHAR             7 /**< Data type: unsigned char */
  55 #define EET_T_USHORT            8 /**< Data type: unsigned short */
  56 #define EET_T_UINT              9 /**< Data type: unsigned int */
  57 #define EET_T_ULONG_LONG        10 /**< Data type: unsigned long long */
  58 #define EET_T_STRING            11 /**< Data type: char * */
  59 #define EET_T_INLINED_STRING    12 /**< Data type: char * (but compressed inside the resulting eet) */
  60 #define EET_T_NULL              13 /**< Data type: (void *) (only use it if you know why) */
  61 #define EET_T_LAST              14 /**< Last data type */
  62
  63 #define EET_G_UNKNOWN    100 /**< Unknown group data encoding type */
  64 #define EET_G_ARRAY      101 /**< Fixed size array group type */
  65 #define EET_G_VAR_ARRAY  102 /**< Variable size array group type */
  66 #define EET_G_LIST       103 /**< Linked list group type */
  67 #define EET_G_HASH       104 /**< Hash table group type */
  68 #define EET_G_LAST       105 /**< Last group type */
  69
  70 /***************************************************************************/
  71
  72    typedef enum _Eet_File_Mode
  73      {
  74         EET_FILE_MODE_INVALID = -1,
  75         EET_FILE_MODE_READ,
  76         EET_FILE_MODE_WRITE,
  77         EET_FILE_MODE_READ_WRITE
  78      } Eet_File_Mode;
  79
  80    typedef enum _Eet_Error
  81      {
  82         EET_ERROR_NONE,
  83         EET_ERROR_BAD_OBJECT,
  84         EET_ERROR_EMPTY,
  85         EET_ERROR_NOT_WRITABLE,
  86         EET_ERROR_OUT_OF_MEMORY,
  87         EET_ERROR_WRITE_ERROR,
  88         EET_ERROR_WRITE_ERROR_FILE_TOO_BIG,
  89         EET_ERROR_WRITE_ERROR_IO_ERROR,
  90         EET_ERROR_WRITE_ERROR_OUT_OF_SPACE,
  91         EET_ERROR_WRITE_ERROR_FILE_CLOSED,
  92         EET_ERROR_MMAP_FAILED,
  93         EET_ERROR_X509_ENCODING_FAILED,
  94         EET_ERROR_SIGNATURE_FAILED,
  95         EET_ERROR_INVALID_SIGNATURE,
  96         EET_ERROR_NOT_SIGNED,
  97         EET_ERROR_NOT_IMPLEMENTED,
  98         EET_ERROR_PRNG_NOT_SEEDED,
  99         EET_ERROR_ENCRYPT_FAILED,
 100         EET_ERROR_DECRYPT_FAILED
 101      } Eet_Error;
 102
 103    typedef struct _Eet_File                  Eet_File;
 104    typedef struct _Eet_Dictionary            Eet_Dictionary;
 105    typedef struct _Eet_Data_Descriptor       Eet_Data_Descriptor;
 106    typedef struct _Eet_Key                   Eet_Key;
 107
 108    typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
 109
 110 #define EET_DATA_DESCRIPTOR_CLASS_VERSION 2
 111    struct _Eet_Data_Descriptor_Class
 112      {
 113         int         version;
 114         const char *name;
 115         int         size;
 116         struct {
 117            void   *(*mem_alloc) (size_t size);
 118            void    (*mem_free) (void *mem);
 119            char   *(*str_alloc) (const char *str);
 120            void    (*str_free) (const char *str);
 121            void   *(*list_next) (void *l);
 122            void   *(*list_append) (void *l, void *d);
 123            void   *(*list_data) (void *l);
 124            void   *(*list_free) (void *l);
 125            void    (*hash_foreach) (void *h, int (*func) (void *h, const char *k, void *dt, void *fdt), void *fdt);
 126            void   *(*hash_add) (void *h, const char *k, void *d);
 127            void    (*hash_free) (void *h);
 128            char   *(*str_direct_alloc) (const char *str);
 129            void    (*str_direct_free) (const char *str);
 130         } func;
 131      };
 132
 133 /***************************************************************************/
 134
 135    /**
 136     * Initialize the EET library.
 137     *
 138     * @return The new init count.
 139     *
 140     * @since 1.0.0
 141     */
 142    EAPI int eet_init(void);
 143
 144    /**
 145     * Shut down the EET library.
 146     *
 147     * @return The new init count.
 148     *
 149     * @since 1.0.0
 150     */
 151    EAPI int eet_shutdown(void);
 152
 153    /**
 154     * Clear eet cache
 155     *
 156     * Eet didn't free items by default. If you are under memory presure, just
 157     * call this function to recall all memory that are not yet referenced anymore.
 158     * The cache take care of modification on disk.
 159     *
 160     * @since 1.0.0
 161     */
 162    EAPI void eet_clearcache(void);
 163
 164    /**
 165     * Open an eet file on disk, and returns a handle to it.
 166     * @param file The file path to the eet file. eg: "/tmp/file.eet".
 167     * @param mode The mode for opening. Either EET_FILE_MODE_READ, EET_FILE_MODE_WRITE or EET_FILE_MODE_READ_WRITE.
 168     * @return An opened eet file handle.
 169     *
 170     * This function will open an exiting eet file for reading, and build
 171     * the directory table in memory and return a handle to the file, if it
 172     * exists and can be read, and no memory errors occur on the way, otherwise
 173     * NULL will be returned.
 174     *
 175     * It will also open an eet file for writing. This will, if successful,
 176     * delete the original file and replace it with a new empty file, till
 177     * the eet file handle is closed or flushed. If it cannot be opened for
 178     * writing or a memory error occurs, NULL is returned.
 179     *
 180     * You can also open the file for read/write. If you then write a key that
 181     * does not exist it will be created, if the key exists it will be replaced
 182     * by the new data.
 183     *
 184     * Example:
 185     * @code
 186     * #include <Eet.h>
 187     * #include <stdio.h>
 188     *
 189     * int
 190     * main(int argc, char **argv)
 191     * {
 192     *   Eet_File *ef;
 193     *   char buf[1024], *ret, **list;
 194     *   int size, num, i;
 195     *
 196     *   strcpy(buf, "Here is a string of data to save!");
 197     *
 198     *   ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE);
 199     *   if (!ef) return -1;
 200     *   if (!eet_write(ef, "/key/to_store/at", buf, 1024, 1))
 201     *     fprintf(stderr, "Error writing data!\n");
 202     *   eet_close(ef);
 203     *
 204     *   ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_READ);
 205     *   if (!ef) return -1;
 206     *   list = eet_list(ef, "*", &num);
 207     *   if (list)
 208     *     {
 209     *       for (i = 0; i < num; i++)
 210     *         printf("Key stored: %s\n", list[i]);
 211     *       free(list);
 212     *     }
 213     *   ret = eet_read(ef, "/key/to_store/at", &size);
 214     *   if (ret)
 215     *     {
 216     *       printf("Data read (%i bytes):\n%s\n", size, ret);
 217     *       free(ret);
 218     *     }
 219     *   eet_close(ef);
 220     *
 221     *   return 0;
 222     * }
 223     * @endcode
 224     *
 225     * @since 1.0.0
 226     */
 227    EAPI Eet_File *eet_open(const char *file, Eet_File_Mode mode);
 228
 229    /**
 230     * Open an eet file directly from a memory location. The data are not copied,
 231     * so you must keep them around as long as the eet file is open. Their is
 232     * currently no cache for this kind of Eet_File, so it's reopen every time
 233     * you do use eet_memopen_read.
 234     *
 235     * @since 2.0.0
 236     */
 237    EAPI Eet_File *eet_memopen_read(const void *data, size_t size);
 238
 239    /**
 240     * Get the mode an Eet_File was opened with.
 241     * @param ef A valid eet file handle.
 242     * @return The mode ef was opened with.
 243     *
 244     * @since 1.0.0
 245     */
 246    EAPI Eet_File_Mode eet_mode_get(Eet_File *ef);
 247
 248    /**
 249     * Close an eet file handle and flush and writes pending.
 250     * @param ef A valid eet file handle.
 251     *
 252     * This function will flush any pending writes to disk if the eet file
 253     * was opened for write, and free all data associated with the file handle
 254     * and file, and close the file.
 255     *
 256     * If the eet file handle is not valid nothing will be done.
 257     *
 258     * @since 1.0.0
 259     */
 260    EAPI Eet_Error eet_close(Eet_File *ef);
 261
 262   /**
 263    * Callback used to request if needed the password of a private key.
 264    *
 265    * @since 2.0.0
 266    */
 267    typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data);
 268
 269    /**
 270     * Create an Eet_Key needed for signing an eet file.
 271     *
 272     * The certificate should provide the public that match the private key.
 273     * No verification is done to ensure that.
 274     *
 275     * @since 2.0.0
 276     */
 277    EAPI Eet_Key* eet_identity_open(const char *certificate_file, const char *private_key_file, Eet_Key_Password_Callback cb);
 278
 279     /**
 280      * Close and release all ressource used by an Eet_Key.
 281      * An reference counter prevent it from being freed until all file using it are
 282      * also closed.
 283      *
 284      * @since 2.0.0
 285      */
 286    EAPI void eet_identity_close(Eet_Key *key);
 287
 288     /**
 289      * Set a key to sign a file
 290      *
 291      * @since 2.0.0
 292      */
 293    EAPI Eet_Error eet_identity_set(Eet_File *ef, Eet_Key *key);
 294
 295     /**
 296      * Display both private and public key of an Eet_Key.
 297      *
 298      * @since 2.0.0
 299      */
 300    EAPI void eet_identity_print(Eet_Key *key, FILE *out);
 301
 302     /**
 303      * Get the x509 der certificate associated with an Eet_File. Will return NULL
 304      * if the file is not signed.
 305      *
 306      * @since 2.0.0
 307      */
 308    EAPI const void *eet_identity_x509(Eet_File *ef, int *der_length);
 309
 310    /**
 311     * Display the x509 der certificate to out.
 312     *
 313     * @since 2.0.0
 314     */
 315    EAPI void eet_identity_certificate_print(const unsigned char *certificate, int der_length, FILE *out);
 316
 317    /**
 318     * Return a handle to the shared string dictionary of the Eet file
 319     * @param ef A valid eet file handle.
 320     * @return A handle to the dictionary of the file
 321     *
 322     * This function returns a handle to the dictionary of an Eet file whose
 323     * handle is @p ef, if a dictionary exists. NULL is returned otherwise or
 324     * if the file handle is known to be invalid.
 325     *
 326     * @since 1.0.0
 327     */
 328    EAPI Eet_Dictionary *eet_dictionary_get(Eet_File *ef);
 329
 330    /**
 331     * Check if a given string comes from a given dictionary
 332     * @param ed A valid dictionary handle
 333     * @param string A valid 0 byte terminated C string
 334     * @return 1 if it is in the dictionary, 0 otherwise
 335     *
 336     * This checks the given dictionary to see if the given string is actually
 337     * inside that dictionary (i.e. comes from it) and returns 1 if it does.
 338     * If the dictionary handle is invlide, the string is NULL or the string is
 339     * not in the dictionary, 0 is returned.
 340     *
 341     * @since 1.0.0
 342     */
 343    EAPI int eet_dictionary_string_check(Eet_Dictionary *ed, const char *string);
 344
 345    /**
 346     * Read a specified entry from an eet file and return data
 347     * @param ef A valid eet file handle opened for reading.
 348     * @param name Name of the entry. eg: "/base/file_i_want".
 349     * @param size_ret Number of bytes read from entry and returned.
 350     * @return The data stored in that entry in the eet file.
 351     *
 352     * This function finds an entry in the eet file that is stored under the
 353     * name specified, and returns that data, decompressed, if successful.
 354     * NULL is returned if the lookup fails or if memory errors are
 355     * encountered. It is the job of the calling program to call free() on
 356     * the returned data. The number of bytes in the returned data chunk are
 357     * placed in size_ret.
 358     *
 359     * If the eet file handle is not valid NULL is returned and size_ret is
 360     * filled with 0.
 361     *
 362     * @since 1.0.0
 363     */
 364    EAPI void *eet_read_cipher(Eet_File *ef, const char *name, int *size_ret, const char *cipher_key);
 365    EAPI void *eet_read(Eet_File *ef, const char *name, int *size_ret);
 366
 367    /**
 368     * Read a specified entry from an eet file and return data
 369     * @param ef A valid eet file handle opened for reading.
 370     * @param name Name of the entry. eg: "/base/file_i_want".
 371     * @param size_ret Number of bytes read from entry and returned.
 372     * @return The data stored in that entry in the eet file.
 373     *
 374     * This function finds an entry in the eet file that is stored under the
 375     * name specified, and returns that data if not compressed and successful.
 376     * NULL is returned if the lookup fails or if memory errors are
 377     * encountered or if the data is comrpessed. The calling program must never
 378     * call free() on the returned data. The number of bytes in the returned
 379     * data chunk are placed in size_ret.
 380     *
 381     * If the eet file handle is not valid NULL is returned and size_ret is
 382     * filled with 0.
 383     *
 384     * @since 1.0.0
 385     */
 386    EAPI const void *eet_read_direct(Eet_File *ef, const char *name, int *size_ret);
 387
 388    /**
 389     * Write a specified entry to an eet file handle
 390     * @param ef A valid eet file handle opened for writing.
 391     * @param name Name of the entry. eg: "/base/file_i_want".
 392     * @param data Pointer to the data to be stored.
 393     * @param size Length in bytes in the data to be stored.
 394     * @param compress Compression flags (1 == compress, 0 = don't compress).
 395     * @return Success or failure of the write.
 396     *
 397     * This function will write the specified chunk of data to the eet file
 398     * and return greater than 0 on success. 0 will be returned on failure.
 399     *
 400     * The eet file handle must be a valid file handle for an eet file opened
 401     * for writing. If it is not, 0 will be returned and no action will be
 402     * performed.
 403     *
 404     * Name, and data must not be NULL, and size must be > 0. If these
 405     * conditions are not met, 0 will be returned.
 406     *
 407     * The data will be copied (and optionally compressed) in ram, pending
 408     * a flush to disk (it will stay in ram till the eet file handle is
 409     * closed though).
 410     *
 411     * @since 1.0.0
 412     */
 413    EAPI int eet_write_cipher(Eet_File *ef, const char *name, const void *data, int size, int compress, const char *cipher_key);
 414    EAPI int eet_write(Eet_File *ef, const char *name, const void *data, int size, int compress);
 415
 416    /**
 417     * Delete a specified entry from an Eet file being written or re-written
 418     * @param ef A valid eet file handle opened for writing.
 419     * @param name Name of the entry. eg: "/base/file_i_want".
 420     * @return Success or failure of the delete.
 421     *
 422     * This function will delete the specified chunk of data from the eet file
 423     * and return greater than 0 on success. 0 will be returned on failure.
 424     *
 425     * The eet file handle must be a valid file handle for an eet file opened
 426     * for writing. If it is not, 0 will be returned and no action will be
 427     * performed.
 428     *
 429     * Name, must not be NULL, otherwise 0 will be returned.
 430     *
 431     * @since 1.0.0
 432     */
 433    EAPI int eet_delete(Eet_File *ef, const char *name);
 434
 435    /**
 436     * List all entries in eet file matching shell glob.
 437     * @param ef A valid eet file handle.
 438     * @param glob A shell glob to match against.
 439     * @param count_ret Number of entries found to match.
 440     * @return Pointer to an array of strings.
 441     *
 442     * This function will list all entries in the eet file matching the
 443     * supplied shell glob and return an allocated list of their names, if
 444     * there are any, and if no memory errors occur.
 445     *
 446     * The eet file handle must be valid and glob must not be NULL, or NULL
 447     * will be returned and count_ret will be filled with 0.
 448     *
 449     * The calling program must call free() on the array returned, but NOT
 450     * on the string pointers in the array. They are taken as read-only
 451     * internals from the eet file handle. They are only valid as long as
 452     * the file handle is not closed. When it is closed those pointers in the
 453     * array are now not valid and should not be used.
 454     *
 455     * On success the array returned will have a list of string pointers
 456     * that are the names of the entries that matched, and count_ret will have
 457     * the number of entries in this array placed in it.
 458     *
 459     * Hint: an easy way to list all entries in an eet file is to use a glob
 460     * value of "*".
 461     *
 462     * @since 1.0.0
 463     */
 464    EAPI char **eet_list(Eet_File *ef, const char *glob, int *count_ret);
 465
 466    /**
 467     * Return the number of entries in the specified eet file.
 468     * @param ef A valid eet file handle.
 469     * @return Number of entries in ef or -1 if the number of entries
 470     *         cannot be read due to open mode restrictions.
 471     *
 472     * @since 1.0.0
 473     */
 474    EAPI int eet_num_entries(Eet_File *ef);
 475
 476 /***************************************************************************/
 477
 478    /**
 479     * Read just the header data for an image and dont decode the pixels.
 480     * @param ef A valid eet file handle opened for reading.
 481     * @param name Name of the entry. eg: "/base/file_i_want".
 482     * @param w A pointer to the unsigned int to hold the width in pixels.
 483     * @param h A pointer to the unsigned int to hold the height in pixels.
 484     * @param alpha A pointer to the int to hold the alpha flag.
 485     * @param compress A pointer to the int to hold the compression amount.
 486     * @param quality A pointer to the int to hold the quality amount.
 487     * @param lossy A pointer to the int to hold the lossiness flag.
 488     * @return 1 on successfull decode, 0 otherwise
 489     *
 490     * This function reads an image from an eet file stored under the named
 491     * key in the eet file and return a pointer to the decompressed pixel data.
 492     *
 493     * The other parameters of the image (width, height etc.) are placed into
 494     * the values pointed to (they must be supplied). The pixel data is a linear
 495     * array of pixels starting from the top-left of the image scanning row by
 496     * row from left to right. Each pile is a 32bit value, with the high byte
 497     * being the alpha channel, the next being red, then green, and the low byte
 498     * being blue. The width and height are measured in pixels and will be
 499     * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
 500     * that the alpha channel is not used. 1 denotes that it is significant.
 501     * Compress is filled with the compression value/amount the image was
 502     * stored with. The quality value is filled with the quality encoding of
 503     * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
 504     * the image was encoded lossily or not.
 505     *
 506     * On success the function returns 1 indicating the header was read and
 507     * decoded properly, or 0 on failure.
 508     *
 509     * @since 1.0.0
 510     */
 511    EAPI int eet_data_image_header_read_cipher(Eet_File *ef, const char *name, const char *key, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 512    EAPI int eet_data_image_header_read(Eet_File *ef, const char *name, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 513
 514    /**
 515     * Read image data from the named key in the eet file.
 516     * @param ef A valid eet file handle opened for reading.
 517     * @param name Name of the entry. eg: "/base/file_i_want".
 518     * @param w A pointer to the unsigned int to hold the width in pixels.
 519     * @param h A pointer to the unsigned int to hold the height in pixels.
 520     * @param alpha A pointer to the int to hold the alpha flag.
 521     * @param compress A pointer to the int to hold the compression amount.
 522     * @param quality A pointer to the int to hold the quality amount.
 523     * @param lossy A pointer to the int to hold the lossiness flag.
 524     * @return The image pixel data decoded
 525     *
 526     * This function reads an image from an eet file stored under the named
 527     * key in the eet file and return a pointer to the decompressed pixel data.
 528     *
 529     * The other parameters of the image (width, height etc.) are placed into
 530     * the values pointed to (they must be supplied). The pixel data is a linear
 531     * array of pixels starting from the top-left of the image scanning row by
 532     * row from left to right. Each pile is a 32bit value, with the high byte
 533     * being the alpha channel, the next being red, then green, and the low byte
 534     * being blue. The width and height are measured in pixels and will be
 535     * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
 536     * that the alpha channel is not used. 1 denotes that it is significant.
 537     * Compress is filled with the compression value/amount the image was
 538     * stored with. The quality value is filled with the quality encoding of
 539     * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
 540     * the image was encoded lossily or not.
 541     *
 542     * On success the function returns a pointer to the image data decoded. The
 543     * calling application is responsible for calling free() on the image data
 544     * when it is done with it. On failure NULL is returned and the parameter
 545     * values may not contain any sensible data.
 546     *
 547     * @since 1.0.0
 548     */
 549    EAPI void *eet_data_image_read_cipher(Eet_File *ef, const char *name, const char *key, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 550    EAPI void *eet_data_image_read(Eet_File *ef, const char *name, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 551
 552    /**
 553     * Read image data from the named key in the eet file.
 554     * @param ef A valid eet file handle opened for reading.
 555     * @param name Name of the entry. eg: "/base/file_i_want".
 556     * @param src_x The starting x coordinate from where to dump the stream.
 557     * @param src_y The starting y coordinate from where to dump the stream.
 558     * @param d A pointer to the pixel surface.
 559     * @param w The expected width in pixels of the pixel surface to decode.
 560     * @param h The expected height in pixels of the pixel surface to decode.
 561     * @param row_stride The length of a pixels line in the destination surface.
 562     * @param alpha A pointer to the int to hold the alpha flag.
 563     * @param compress A pointer to the int to hold the compression amount.
 564     * @param quality A pointer to the int to hold the quality amount.
 565     * @param lossy A pointer to the int to hold the lossiness flag.
 566     * @return 1 on success, 0 otherwise.
 567     *
 568     * This function reads an image from an eet file stored under the named
 569     * key in the eet file and return a pointer to the decompressed pixel data.
 570     *
 571     * The other parameters of the image (width, height etc.) are placed into
 572     * the values pointed to (they must be supplied). The pixel data is a linear
 573     * array of pixels starting from the top-left of the image scanning row by
 574     * row from left to right. Each pile is a 32bit value, with the high byte
 575     * being the alpha channel, the next being red, then green, and the low byte
 576     * being blue. The width and height are measured in pixels and will be
 577     * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
 578     * that the alpha channel is not used. 1 denotes that it is significant.
 579     * Compress is filled with the compression value/amount the image was
 580     * stored with. The quality value is filled with the quality encoding of
 581     * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
 582     * the image was encoded lossily or not.
 583     *
 584     * On success the function returns 1, and 0 on failure. On failure the
 585     * parameter values may not contain any sensible data.
 586     *
 587     * @since 1.0.2
 588     */
 589    EAPI int eet_data_image_read_to_surface_cipher(Eet_File *ef, const char *name, const char *key, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
 590    EAPI int eet_data_image_read_to_surface(Eet_File *ef, const char *name, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
 591
 592    /**
 593     * Write image data to the named key in an eet file.
 594     * @param ef A valid eet file handle opened for writing.
 595     * @param name Name of the entry. eg: "/base/file_i_want".
 596     * @param data A pointer to the image pixel data.
 597     * @param w The width of the image in pixels.
 598     * @param h The height of the image in pixels.
 599     * @param alpha The alpha channel flag.
 600     * @param compress The compression amount.
 601     * @param quality The quality encoding amount.
 602     * @param lossy The lossiness flag.
 603     * @return Success if the data was encoded and written or not.
 604     *
 605     * This function takes image pixel data and encodes it in an eet file
 606     * stored under the supplied name key, and returns how many bytes were
 607     * actually written to encode the image data.
 608     *
 609     * The data expected is the same format as returned by eet_data_image_read.
 610     * If this is not the case weird things may happen. Width and height must
 611     * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
 612     * the alpha values are not useful and 1 meaning they are). Compress can
 613     * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
 614     * This is only used if the image is not lossily encoded. Quality is used on
 615     * lossy compression and should be a value from 0 to 100. The lossy flag
 616     * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
 617     * image quality loss (but then have a much smaller encoding).
 618     *
 619     * On success this function returns the number of bytes that were required
 620     * to encode the image data, or on failure it returns 0.
 621     *
 622     * @since 1.0.0
 623     */
 624    EAPI int eet_data_image_write_cipher(Eet_File *ef, const char *name, const char *key, const void *data, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy);
 625    EAPI int eet_data_image_write(Eet_File *ef, const char *name, const void *data, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy);
 626
 627    /**
 628     * Decode Image data header only to get information.
 629     * @param data The encoded pixel data.
 630     * @param size The size, in bytes, of the encoded pixel data.
 631     * @param w A pointer to the unsigned int to hold the width in pixels.
 632     * @param h A pointer to the unsigned int to hold the height in pixels.
 633     * @param alpha A pointer to the int to hold the alpha flag.
 634     * @param compress A pointer to the int to hold the compression amount.
 635     * @param quality A pointer to the int to hold the quality amount.
 636     * @param lossy A pointer to the int to hold the lossiness flag.
 637     * @return 1 on success, 0 on failure.
 638     *
 639     * This function takes encoded pixel data and decodes it into raw RGBA
 640     * pixels on success.
 641     *
 642     * The other parameters of the image (width, height etc.) are placed into
 643     * the values pointed to (they must be supplied). The pixel data is a linear
 644     * array of pixels starting from the top-left of the image scanning row by
 645     * row from left to right. Each pixel is a 32bit value, with the high byte
 646     * being the alpha channel, the next being red, then green, and the low byte
 647     * being blue. The width and height are measured in pixels and will be
 648     * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
 649     * that the alpha channel is not used. 1 denotes that it is significant.
 650     * Compress is filled with the compression value/amount the image was
 651     * stored with. The quality value is filled with the quality encoding of
 652     * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
 653     * the image was encoded lossily or not.
 654     *
 655     * On success the function returns 1 indicating the header was read and
 656     * decoded properly, or 0 on failure.
 657     *
 658     * @since 1.0.0
 659     */
 660    EAPI int eet_data_image_header_decode_cipher(const void *data, const char *key, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 661    EAPI int eet_data_image_header_decode(const void *data, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 662
 663    /**
 664     * Decode Image data into pixel data.
 665     * @param data The encoded pixel data.
 666     * @param size The size, in bytes, of the encoded pixel data.
 667     * @param w A pointer to the unsigned int to hold the width in pixels.
 668     * @param h A pointer to the unsigned int to hold the height in pixels.
 669     * @param alpha A pointer to the int to hold the alpha flag.
 670     * @param compress A pointer to the int to hold the compression amount.
 671     * @param quality A pointer to the int to hold the quality amount.
 672     * @param lossy A pointer to the int to hold the lossiness flag.
 673     * @return The image pixel data decoded
 674     *
 675     * This function takes encoded pixel data and decodes it into raw RGBA
 676     * pixels on success.
 677     *
 678     * The other parameters of the image (width, height etc.) are placed into
 679     * the values pointed to (they must be supplied). The pixel data is a linear
 680     * array of pixels starting from the top-left of the image scanning row by
 681     * row from left to right. Each pixel is a 32bit value, with the high byte
 682     * being the alpha channel, the next being red, then green, and the low byte
 683     * being blue. The width and height are measured in pixels and will be
 684     * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
 685     * that the alpha channel is not used. 1 denotes that it is significant.
 686     * Compress is filled with the compression value/amount the image was
 687     * stored with. The quality value is filled with the quality encoding of
 688     * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
 689     * the image was encoded lossily or not.
 690     *
 691     * On success the function returns a pointer to the image data decoded. The
 692     * calling application is responsible for calling free() on the image data
 693     * when it is done with it. On failure NULL is returned and the parameter
 694     * values may not contain any sensible data.
 695     *
 696     * @since 1.0.0
 697     */
 698    EAPI void *eet_data_image_decode_cipher(const void *data, const char *key, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 699    EAPI void *eet_data_image_decode(const void *data, int size, unsigned int *w, unsigned int *h, int *alpha, int *compress, int *quality, int *lossy);
 700
 701    /**
 702     * Decode Image data into pixel data.
 703     * @param data The encoded pixel data.
 704     * @param size The size, in bytes, of the encoded pixel data.
 705     * @param src_x The starting x coordinate from where to dump the stream.
 706     * @param src_y The starting y coordinate from where to dump the stream.
 707     * @param d A pointer to the pixel surface.
 708     * @param w The expected width in pixels of the pixel surface to decode.
 709     * @param h The expected height in pixels of the pixel surface to decode.
 710     * @param row_stride The length of a pixels line in the destination surface.
 711     * @param alpha A pointer to the int to hold the alpha flag.
 712     * @param compress A pointer to the int to hold the compression amount.
 713     * @param quality A pointer to the int to hold the quality amount.
 714     * @param lossy A pointer to the int to hold the lossiness flag.
 715     * @return 1 on success, 0 otherwise.
 716     *
 717     * This function takes encoded pixel data and decodes it into raw RGBA
 718     * pixels on success.
 719     *
 720     * The other parameters of the image (alpha, compress etc.) are placed into
 721     * the values pointed to (they must be supplied). The pixel data is a linear
 722     * array of pixels starting from the top-left of the image scanning row by
 723     * row from left to right. Each pixel is a 32bit value, with the high byte
 724     * being the alpha channel, the next being red, then green, and the low byte
 725     * being blue. The width and height are measured in pixels and will be
 726     * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
 727     * that the alpha channel is not used. 1 denotes that it is significant.
 728     * Compress is filled with the compression value/amount the image was
 729     * stored with. The quality value is filled with the quality encoding of
 730     * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
 731     * the image was encoded lossily or not.
 732     *
 733     * On success the function returns 1, and 0 on failure. On failure the
 734     * parameter values may not contain any sensible data.
 735     *
 736     * @since 1.0.2
 737     */
 738    EAPI int eet_data_image_decode_to_surface_cipher(const void *data, const char *key, int size, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
 739    EAPI int eet_data_image_decode_to_surface(const void *data, int size, unsigned int src_x, unsigned int src_y, unsigned int *d, unsigned int w, unsigned int h, unsigned int row_stride, int *alpha, int *compress, int *quality, int *lossy);
 740
 741    /**
 742     * Encode image data for storage or transmission.
 743     * @param data A pointer to the image pixel data.
 744     * @param size_ret A pointer to an int to hold the size of the returned data.
 745     * @param w The width of the image in pixels.
 746     * @param h The height of the image in pixels.
 747     * @param alpha The alpha channel flag.
 748     * @param compress The compression amount.
 749     * @param quality The quality encoding amount.
 750     * @param lossy The lossiness flag.
 751     * @return The encoded image data.
 752     *
 753     * This function stakes image pixel data and encodes it with compression and
 754     * possible loss of quality (as a trade off for size) for storage or
 755     * transmission to another system.
 756     *
 757     * The data expected is the same format as returned by eet_data_image_read.
 758     * If this is not the case weird things may happen. Width and height must
 759     * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning
 760     * the alpha values are not useful and 1 meaning they are). Compress can
 761     * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
 762     * This is only used if the image is not lossily encoded. Quality is used on
 763     * lossy compression and should be a value from 0 to 100. The lossy flag
 764     * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
 765     * image quality loss (but then have a much smaller encoding).
 766     *
 767     * On success this function returns a pointer to the encoded data that you
 768     * can free with free() when no longer needed.
 769     *
 770     * @since 1.0.0
 771     */
 772    EAPI void *eet_data_image_encode_cipher(const void *data, const char *key, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy, int *size_ret);
 773    EAPI void *eet_data_image_encode(const void *data, int *size_ret, unsigned int w, unsigned int h, int alpha, int compress, int quality, int lossy);
 774
 775 /***************************************************************************/
 776
 777    /**
 778     * Create a new empty data structure descriptor.
 779     * @param name The string name of this data structure (most be a global constant and never change).
 780     * @param size The size of the struct (in bytes).
 781     * @param func_list_next The function to get the next list node.
 782     * @param func_list_append The function to append a member to a list.
 783     * @param func_list_data The function to get the data from a list node.
 784     * @param func_list_free The function to free an entire linked list.
 785     * @param func_hash_foreach The function to iterate through all hash table entries.
 786     * @param func_hash_add The function to add a member to a hash table.
 787     * @param func_hash_free The function to free an entire hash table.
 788     * @return A new empty data descriptor.
 789     *
 790     * This function creates a new data descriptore and returns a handle to the
 791     * new data descriptor. On creation it will be empty, containing no contents
 792     * describing anything other than the shell of the data structure.
 793     *
 794     * You add structure members to the data descriptor using the macros
 795     * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
 796     * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
 797     * adding to the description.
 798     *
 799     * Once you have described all the members of a struct you want loaded, or
 800     * saved eet can load and save those members for you, encode them into
 801     * endian-independant serialised data chunks for transmission across a
 802     * a network or more.
 803     *
 804     * The function pointers to the list and hash table functions are only
 805     * needed if you use those data types, else you can pass NULL instead.
 806     *
 807     * Example:
 808     *
 809     * @code
 810     * #include <Eet.h>
 811     * #include <Evas.h>
 812     *
 813     * typedef struct _blah2
 814     * {
 815     *    char *string;
 816     * }
 817     * Blah2;
 818     *
 819     * typedef struct _blah3
 820     * {
 821     *    char *string;
 822     * }
 823     * Blah3;
 824     *
 825     * typedef struct _blah
 826     * {
 827     *    char character;
 828     *    short sixteen;
 829     *    int integer;
 830     *    long long lots;
 831     *    float floating;
 832     *    double floating_lots;
 833     *    char *string;
 834     *    Blah2 *blah2;
 835     *    Eina_List *blah3;
 836     * }
 837     * Blah;
 838     *
 839     * int
 840     * main(int argc, char **argv)
 841     * {
 842     *    Blah blah;
 843     *    Blah2 blah2;
 844     *    Blah3 blah3;
 845     *    Eet_Data_Descriptor *edd, *edd2, *edd3;
 846     *    void *data;
 847     *    int size;
 848     *    FILE *f;
 849     *    Blah *blah_in;
 850     *
 851     *    edd3 = eet_data_descriptor_new("blah3", sizeof(Blah3),
 852     *                                   eina_list_next,
 853     *                                   eina_list_append,
 854     *                                   eina_list_data_get,
 855     *                                   eina_list_free,
 856     *                                   evas_hash_foreach,
 857     *                                   evas_hash_add,
 858     *                                   evas_hash_free);
 859     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd3, Blah3, "string3", string, EET_T_STRING);
 860     *
 861     *    edd2 = eet_data_descriptor_new("blah2", sizeof(Blah2),
 862     *                                   eina_list_next,
 863     *                                   eina_list_append,
 864     *                                   eina_list_data_get,
 865     *                                   eina_list_free,
 866     *                                   evas_hash_foreach,
 867     *                                   evas_hash_add,
 868     *                                   evas_hash_free);
 869     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd2, Blah2, "string2", string, EET_T_STRING);
 870     *
 871     *    edd = eet_data_descriptor_new("blah", sizeof(Blah),
 872     *                                   eina_list_next,
 873     *                                   eina_list_append,
 874     *                                   eina_list_data_get,
 875     *                                   eina_list_free,
 876     *                                   evas_hash_foreach,
 877     *                                   evas_hash_add,
 878     *                                   evas_hash_free);
 879     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "character", character, EET_T_CHAR);
 880     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "sixteen", sixteen, EET_T_SHORT);
 881     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "integer", integer, EET_T_INT);
 882     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "lots", lots, EET_T_LONG_LONG);
 883     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating", floating, EET_T_FLOAT);
 884     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating_lots", floating_lots, EET_T_DOUBLE);
 885     *    EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "string", string, EET_T_STRING);
 886     *    EET_DATA_DESCRIPTOR_ADD_SUB(edd, Blah, "blah2", blah2, edd2);
 887     *    EET_DATA_DESCRIPTOR_ADD_LIST(edd, Blah, "blah3", blah3, edd3);
 888     *
 889     *    blah3.string="PANTS";
 890     *
 891     *    blah2.string="subtype string here!";
 892     *
 893     *    blah.character='7';
 894     *    blah.sixteen=0x7777;
 895     *    blah.integer=0xc0def00d;
 896     *    blah.lots=0xdeadbeef31337777;
 897     *    blah.floating=3.141592654;
 898     *    blah.floating_lots=0.777777777777777;
 899     *    blah.string="bite me like a turnip";
 900     *    blah.blah2 = &blah2;
 901     *    blah.blah3 = eina_list_append(NULL, &blah3);
 902     *    blah.blah3 = eina_list_append(blah.blah3, &blah3);
 903     *    blah.blah3 = eina_list_append(blah.blah3, &blah3);
 904     *    blah.blah3 = eina_list_append(blah.blah3, &blah3);
 905     *    blah.blah3 = eina_list_append(blah.blah3, &blah3);
 906     *    blah.blah3 = eina_list_append(blah.blah3, &blah3);
 907     *    blah.blah3 = eina_list_append(blah.blah3, &blah3);
 908     *
 909     *    data = eet_data_descriptor_encode(edd, &blah, &size);
 910     *    printf("-----DECODING\n");
 911     *    blah_in = eet_data_descriptor_decode(edd, data, size);
 912     *
 913     *    printf("-----DECODED!\n");
 914     *    printf("%c\n", blah_in->character);
 915     *    printf("%x\n", (int)blah_in->sixteen);
 916     *    printf("%x\n", blah_in->integer);
 917     *    printf("%lx\n", blah_in->lots);
 918     *    printf("%f\n", (double)blah_in->floating);
 919     *    printf("%f\n", (double)blah_in->floating_lots);
 920     *    printf("%s\n", blah_in->string);
 921     *    printf("%p\n", blah_in->blah2);
 922     *    printf("  %s\n", blah_in->blah2->string);
 923     *      {
 924     *         Eina_List *l;
 925     *         Blah3 *blah3_in;
 926     *
 927     *         EINA_LIST_FOREACH(blah_in->blah3, l, blah3_in)
 928     *           {
 929     *              printf("%p\n", blah3_in);
 930     *              printf("  %s\n", blah3_in->string);
 931     *           }
 932     *      }
 933     *    eet_data_descriptor_free(edd);
 934     *    eet_data_descriptor_free(edd2);
 935     *    eet_data_descriptor_free(edd3);
 936     *
 937     *   return 0;
 938     * }
 939     *
 940     * @endcode
 941     *
 942     * @since 1.0.0
 943     */
 944    EAPI Eet_Data_Descriptor *eet_data_descriptor_new(const char *name, int size, void *(*func_list_next) (void *l), void *(*func_list_append) (void *l, void *d), void *(*func_list_data) (void *l), void *(*func_list_free) (void *l), void  (*func_hash_foreach) (void *h, int (*func) (void *h, const char *k, void *dt, void *fdt), void *fdt), void *(*func_hash_add) (void *h, const char *k, void *d), void  (*func_hash_free) (void *h));
 945    /*
 946     * FIXME:
 947     *
 948     * moving to this api from the old above. this will break things when the
 949     * move happens - but be warned
 950     */
 951    EAPI Eet_Data_Descriptor *eet_data_descriptor2_new(Eet_Data_Descriptor_Class *eddc);
 952    EAPI Eet_Data_Descriptor *eet_data_descriptor3_new(Eet_Data_Descriptor_Class *eddc);
 953
 954    /**
 955     * This function frees a data descriptor when it is not needed anymore.
 956     * @param edd The data descriptor to free.
 957     *
 958     * This function takes a data descriptor handle as a parameter and frees all
 959     * data allocated for the data descriptor and the handle itself. After this
 960     * call the descriptor is no longer valid.
 961     *
 962     * @since 1.0.0
 963     */
 964    EAPI void eet_data_descriptor_free(Eet_Data_Descriptor *edd);
 965
 966    /**
 967     * This function is an internal used by macros.
 968     *
 969     * This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(),
 970     * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is
 971     * complex to use by hand and should be left to be used by the macros, and
 972     * thus is not documented.
 973     *
 974     * @since 1.0.0
 975     */
 976    EAPI void eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, const char *name, int type, int group_type, int offset, /* int count_offset,  */int count, const char *counter_name, Eet_Data_Descriptor *subtype);
 977
 978    /**
 979     * Read a data structure from an eet file and decodes it.
 980     * @param ef The eet file handle to read from.
 981     * @param edd The data descriptor handle to use when decoding.
 982     * @param name The key the data is stored under in the eet file.
 983     * @return A pointer to the decoded data structure.
 984     *
 985     * This function decodes a data structure stored in an eet file, returning
 986     * a pointer to it if it decoded successfully, or NULL on failure. This
 987     * can save a programmer dozens of hours of work in writing configuration
 988     * file parsing and writing code, as eet does all that work for the program
 989     * and presents a program-friendly data structure, just as the programmer
 990     * likes. Eet can handle members being added or deleted from the data in
 991     * storage and safely zero-fills unfilled members if they were not found
 992     * in the data. It checks sizes and headers whenever it reads data, allowing
 993     * the programmer to not worry about corrupt data.
 994     *
 995     * Once a data structure has been described by the programmer with the
 996     * fields they wish to save or load, storing or retrieving a data structure
 997     * from an eet file, or from a chunk of memory is as simple as a single
 998     * function call.
 999     *
1000     * @since 1.0.0
1001     */
1002    EAPI void *eet_data_read_cipher(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const char *key);
1003    EAPI void *eet_data_read(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name);
1004
1005    /**
1006     * Write a data structure from memory and store in an eet file.
1007     * @param ef The eet file handle to write to.
1008     * @param edd The data descriptor to use when encoding.
1009     * @param name The key to store the data under in the eet file.
1010     * @param data A pointer to the data structure to ssave and encode.
1011     * @param compress Compression flags for storage.
1012     * @return 1 on successful write, 0 on failure.
1013     *
1014     * This function is the reverse of eet_data_read(), saving a data structure
1015     * to an eet file.
1016     *
1017     * @since 1.0.0
1018     */
1019    EAPI int eet_data_write_cipher(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const char *key, const void *data, int compress);
1020    EAPI int eet_data_write(Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const void *data, int compress);
1021
1022    /**
1023     * Dump an eet encoded data structure into ascii text
1024     * @param data_in The pointer to the data to decode into a struct.
1025     * @param size_in The size of the data pointed to in bytes.
1026     * @param dumpfunc The function to call passed a string when new data is converted to text
1027     * @param dumpdata The data to pass to the @p dumpfunc callback.
1028     * @return 1 on success, 0 on failure
1029     *
1030     * This function will take a chunk of data encoded by
1031     * eet_data_descriptor_encode() and convert it into human readable ascii text.
1032     * It does this by calling the @p dumpfunc callback for all new text that is
1033     * generated. This callback should append to any existing text buffer and
1034     * will be passed the pointer @p dumpdata as a parameter as well as a string
1035     * with new text to be appended.
1036     *
1037     * Example:
1038     *
1039     * @code
1040     *
1041     * void output(void *data, const char *string)
1042     * {
1043     *   printf("%s", string);
1044     * }
1045     *
1046     * void dump(const char *file)
1047     * {
1048     *   FILE *f;
1049     *   int len;
1050     *   void *data;
1051     *
1052     *   f = fopen(file, "r");
1053     *   fseek(f, 0, SEEK_END);
1054     *   len = ftell(f);
1055     *   rewind(f);
1056     *   data = malloc(len);
1057     *   fread(data, len, 1, f);
1058     *   fclose(f);
1059     *   eet_data_text_dump(data, len, output, NULL);
1060     * }
1061     * @endcode
1062     *
1063     * @since 1.0.0
1064     */
1065    EAPI int eet_data_text_dump_cipher(const void *data_in, const char *key, int size_in, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
1066    EAPI int eet_data_text_dump(const void *data_in, int size_in, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
1067
1068    /**
1069     * Take an ascii encoding from eet_data_text_dump() and re-encode in binary.
1070     * @param text The pointer to the string data to parse and encode.
1071     * @param textlen The size of the string in bytes (not including 0 byte terminator).
1072     * @param size_ret This gets filled in with the encoded data blob size in bytes.
1073     * @return The encoded data on success, NULL on failure.
1074     *
1075     * This function will parse the string pointed to by @p text and return
1076     * an encoded data lump the same way eet_data_descriptor_encode() takes an
1077     * in-memory data struct and encodes into a binary blob. @p text is a normal
1078     * C string.
1079     *
1080     * @since 1.0.0
1081     */
1082    EAPI void *eet_data_text_undump_cipher(const char *text, const char *key, int textlen, int *size_ret);
1083    EAPI void *eet_data_text_undump(const char *text, int textlen, int *size_ret);
1084
1085    /**
1086     * Dump an eet encoded data structure from an eet file into ascii text
1087     * @param ef A valid eet file handle.
1088     * @param name Name of the entry. eg: "/base/file_i_want".
1089     * @param dumpfunc The function to call passed a string when new data is converted to text
1090     * @param dumpdata The data to pass to the @p dumpfunc callback.
1091     * @return 1 on success, 0 on failure
1092     *
1093     * This function will take an open and valid eet file from eet_open() request
1094     * the data encoded by eet_data_descriptor_encode() corresponding to the key @p name
1095     * and convert it into human readable ascii text. It does this by calling the
1096     * @p dumpfunc callback for all new text that is generated. This callback should
1097     * append to any existing text buffer and will be passed the pointer @p dumpdata
1098     * as a parameter as well as a string with new text to be appended.
1099     *
1100     * @since 1.0.0
1101     */
1102    EAPI int eet_data_dump_cipher(Eet_File *ef, const char *name, const char *key, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
1103    EAPI int eet_data_dump(Eet_File *ef, const char *name, void (*dumpfunc) (void *data, const char *str), void *dumpdata);
1104
1105    /**
1106     * Take an ascii encoding from eet_data_dump() and re-encode in binary.
1107     * @param ef A valid eet file handle.
1108     * @param name Name of the entry. eg: "/base/file_i_want".
1109     * @param text The pointer to the string data to parse and encode.
1110     * @param textlen The size of the string in bytes (not including 0 byte terminator).
1111     * @param compress Compression flags (1 == compress, 0 = don't compress).
1112     * @return 1 on success, 0 on failure
1113     *
1114     * This function will parse the string pointed to by @p text, encode it the same
1115     * way eet_data_descriptor_encode() takes an in-memory data struct and encodes into a
1116     * binary blob.
1117     *
1118     * The data (optionally compressed) will be in ram, pending a flush to
1119     * disk (it will stay in ram till the eet file handle is closed though).
1120     *
1121     * @since 1.0.0
1122     */
1123    EAPI int eet_data_undump_cipher(Eet_File *ef, const char *name, const char *key, const char *text, int textlen, int compress);
1124    EAPI int eet_data_undump(Eet_File *ef, const char *name, const char *text, int textlen, int compress);
1125
1126    /**
1127     * Decode a data structure from an arbitary location in memory.
1128     * @param edd The data  descriptor to use when decoding.
1129     * @param data_in The pointer to the data to decode into a struct.
1130     * @param size_in The size of the data pointed to in bytes.
1131     * @return NULL on failure, or a valid decoded struct pointer on success.
1132     *
1133     * This function will decode a data structure that has been encoded using
1134     * eet_data_descriptor_encode(), and return a data structure with all its
1135     * elements filled out, if successful, or NULL on failure.
1136     *
1137     * The data to be decoded is stored at the memory pointed to by @p data_in,
1138     * and is described by the descriptor pointed to by @p edd. The data size is
1139     * passed in as the value to @p size_in, ande must be greater than 0 to
1140     * succeed.
1141     *
1142     * This function is useful for decoding data structures delivered to the
1143     * application by means other than an eet file, such as an IPC or socket
1144     * connection, raw files, shared memory etc.
1145     *
1146     * Please see eet_data_read() for more information.
1147     *
1148     * @since 1.0.0
1149     */
1150    EAPI void *eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd, const void *data_in, const char *key, int size_in);
1151    EAPI void *eet_data_descriptor_decode(Eet_Data_Descriptor *edd, const void *data_in, int size_in);
1152
1153    /**
1154     * Encode a dsata struct to memory and return that encoded data.
1155     * @param edd The data  descriptor to use when encoding.
1156     * @param data_in The pointer to the struct to encode into data.
1157     * @param size_ret A pointer to the an int to be filled with the decoded size.
1158     * @return NULL on failure, or a valid encoded data chunk on success.
1159     *
1160     * This function takes a data structutre in memory and encodes it into a
1161     * serialised chunk of data that can be decoded again by
1162     * eet_data_descriptor_decode(). This is useful for being able to transmit
1163     * data structures across sockets, pipes, IPC or shared file mechanisms,
1164     * without having to worry about memory space, machine type, endianess etc.
1165     *
1166     * The parameter @p edd must point to a valid data descriptor, and
1167     * @p data_in must point to the right data structure to encode. If not, the
1168     * encoding may fail.
1169     *
1170     * On success a non NULL valid pointer is returned and what @p size_ret
1171     * points to is set to the size of this decoded data, in bytes. When the
1172     * encoded data is no longer needed, call free() on it. On failure NULL is
1173     * returned and what @p size_ret points to is set to 0.
1174     *
1175     * Please see eet_data_write() for more information.
1176     *
1177     * @since 1.0.0
1178     */
1179    EAPI void *eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd, const void *data_in, const char *key, int *size_ret);
1180    EAPI void *eet_data_descriptor_encode(Eet_Data_Descriptor *edd, const void *data_in, int *size_ret);
1181
1182    /**
1183     * Add a basic data element to a data descriptor.
1184     * @param edd The data descriptor to add the type to.
1185     * @param struct_type The type of the struct.
1186     * @param name The string name to use to encode/decode this member (must be a constant global and never change).
1187     * @param member The struct member itself to be encoded.
1188     * @param type The type of the member to encode.
1189     *
1190     * This macro is a convenience macro provided to add a member to the data
1191     * descriptor @p edd. The type of the structure is provided as the
1192     * @p struct_type parameter (for example: struct my_struct). The @p name
1193     * parameter defines a string that will be used to uniquely name that
1194     * member of the struct (it is suggested to use the struct member itself).
1195     * The @p member parameter is the actual struct member itself (for
1196 eet_dictionary_string_check    * example: values), and @p type is the basic data type of the member which
1197     * must be one of: EET_T_CHAR, EET_T_SHORT, EET_T_INT, EET_T_LONG_LONG,
1198     * EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR, EET_T_USHORT, EET_T_UINT,
1199     * EET_T_ULONG_LONG or EET_T_STRING.
1200     *
1201     * @since 1.0.0
1202     */
1203 #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
1204      { \
1205         struct_type ___ett; \
1206         \
1207         eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \
1208                                         (char *)(&(___ett.member)) - (char *)(&(___ett)), \
1209                                         0, /* 0,  */NULL, NULL); \
1210      }
1211
1212    /**
1213     * Add a sub-element type to a data descriptor
1214     * @param edd The data descriptor to add the type to.
1215     * @param struct_type The type of the struct.
1216     * @param name The string name to use to encode/decode this member (must be a constant global and never change).
1217     * @param member The struct member itself to be encoded.
1218     * @param subtype The type of sub-type struct to add.
1219     *
1220     * This macro lets you easily add a sub-type (a struct that's pointed to
1221     * by this one). All the parameters are the same as for
1222     * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception.
1223     * This must be the data descriptor of the struct that is pointed to by
1224     * this element.
1225     *
1226     * @since 1.0.0
1227     */
1228 #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
1229      { \
1230         struct_type ___ett; \
1231         \
1232         eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN, \
1233                                         (char *)(&(___ett.member)) - (char *)(&(___ett)), \
1234                                         0, /* 0,  */NULL, subtype); \
1235      }
1236
1237    /**
1238     * Add a linked list type to a data descriptor
1239     * @param edd The data descriptor to add the type to.
1240     * @param struct_type The type of the struct.
1241     * @param name The string name to use to encode/decode this member (must be a constant global and never change).
1242     * @param member The struct member itself to be encoded.
1243     * @param subtype The type of linked list member to add.
1244     *
1245     * This macro lets you easily add a linked list of other data types. All the
1246     * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
1247     * @p subtype being the exception. This must be the data descriptor of the
1248     * element that is in each member of the linked list to be stored.
1249     *
1250     * @since 1.0.0
1251     */
1252 #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \
1253      { \
1254         struct_type ___ett; \
1255         \
1256         eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, \
1257                                         (char *)(&(___ett.member)) - (char *)(&(___ett)), \
1258                                         0, /* 0,  */NULL, subtype); \
1259      }
1260
1261    /**
1262     * Add a hash type to a data descriptor
1263     * @param edd The data descriptor to add the type to.
1264     * @param struct_type The type of the struct.
1265     * @param name The string name to use to encode/decode this member (must be a constant global and never change).
1266     * @param member The struct member itself to be encoded.
1267     * @param subtype The type of hash member to add.
1268     *
1269     * This macro lets you easily add a hash of other data types. All the
1270     * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
1271     * @p subtype being the exception. This must be the data descriptor of the
1272     * element that is in each member of the hash to be stored.
1273     *
1274     * @since 1.0.0
1275     */
1276 #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \
1277      { \
1278         struct_type ___ett; \
1279         \
1280         eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, \
1281                                         (char *)(&(___ett.member)) - (char *)(&(___ett)), \
1282                                         0, /* 0,  */NULL, subtype); \
1283      }
1284
1285    /**
1286     * Add a fixed size array type to a data descriptor
1287     * @param edd The data descriptor to add the type to.
1288     * @param struct_type The type of the struct.
1289     * @param name The string name to use to encode/decode this member (must be a constant global and never change).
1290     * @param member The struct member itself to be encoded.
1291     * @param subtype The type of hash member to add.
1292     *
1293     * This macro lets you easily add a fixed size array of other data types. All the
1294     * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
1295     * @p subtype being the exception. This must be the data descriptor of the
1296     * element that is in each member of the hash to be stored.
1297     *
1298     * @since 1.0.2
1299     */
1300 #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \
1301      { \
1302         struct_type ___ett; \
1303         \
1304         eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, \
1305                                         (char *)(&(___ett.member)) - (char *)(&(___ett)), \
1306                                         /* 0,  */sizeof(___ett.member)/sizeof(___ett.member[0]), NULL, subtype); \
1307      }
1308
1309    /**
1310     * Add a variable size array type to a data descriptor
1311     * @param edd The data descriptor to add the type to.
1312     * @param struct_type The type of the struct.
1313     * @param name The string name to use to encode/decode this member (must be a constant global and never change).
1314     * @param member The struct member itself to be encoded.
1315     * @param subtype The type of hash member to add.
1316     *
1317     * This macro lets you easily add a fixed size array of other data types. All the
1318     * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
1319     * @p subtype being the exception. This must be the data descriptor of the
1320     * element that is in each member of the hash to be stored.
1321     *
1322     * @since 1.0.2
1323     */
1324 #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \
1325      { \
1326         struct_type ___ett; \
1327         \
1328         eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VAR_ARRAY, \
1329                                         (char *)(&(___ett.member)) - (char *)(&(___ett)), \
1330                                         (char *)(&(___ett.member ## _count)) - (char *)(&(___ett)), /* 0,  */NULL, subtype); \
1331      }
1332
1333 /***************************************************************************/
1334 #ifdef __cplusplus
1335 }
1336 #endif
1337
1338 #endif