src/lib/Eet.h

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