Eet.h   Eet.h 
/**
@brief Eet Data Handling Library Public API Calls
These routines are used for Eet Library interaction
@mainpage Eet Library Documentation
@version 1.5.0
@date 2000-2011
Please see the @ref authors page for contact details.
@section toc Table of Contents
@li @ref intro
@li @ref example
@li @ref compiling
@li @ref install
@li @ref next_steps
@li @ref intro_example
@section intro What is Eet?
It is a tiny library designed to write an arbitrary set of chunks of dat
a
to a file and optionally compress each chunk (very much like a zip file)
and allow fast random-access reading of the file later on. It does not
do zip as a zip itself has more complexity than is needed, and it was mu
ch
simpler to implement this once here.
Eet is extremely fast, small and simple. Eet files can be very small and
highly compressed, making them very optimal for just sending across the
internet without having to archive, compress or decompress and install t
hem.
They allow for lightning-fast random-acess reads once created, making th
em
perfect for storing data that is written once (or rarely) and read many
times, but the program does not want to have to read it all in at once.
It also can encode and decode data structures in memory, as well as imag
e
data for saving to Eet files or sending across the network to other
machines, or just writing to arbitrary files on the system. All data is
encoded in a platform independent way and can be written and read by any
architecture.
@section example A simple example on using Eet
Here is a simple example on how to use Eet to save a series of strings t
o a
file and load them again. The advantage of using Eet over just
fprintf() and
fscanf() is that not only can these entries be strings, they need no spe
cial
parsing to handle delimiter characters or escaping, they can be binary d
ata,
image data, data structures containing integers, strings, other data
structures, linked lists and much more, without the programmer having to
worry about parsing, and best of all, Eet is very fast.
This is just a very simple example that doesn't show all of the capabili
ties
of Eet, but it serves to illustrate its simplicity.
@include eet-basic.c
@section compiling How to compile using Eet ?
Eet is a library your application links to. The procedure for this is ve
ry
simple. You simply have to compile your application with the appropriate
compiler flags that the @p pkg-config script outputs. For example:
Compiling C or C++ files into object files:
@verbatim
gcc -c -o main.o main.c `pkg-config --cflags eet`
@endverbatim
Linking object files into a binary executable:
@verbatim
gcc -o my_application main.o `pkg-config --libs eet`
@endverbatim
You simply have to make sure that pkg-config is in your shell's PATH (se
e
the manual page for your appropriate shell) and eet.pc in /usr/lib/pkgco
nfig
or its path is in the PKG_CONFIG_PATH environment variable. It's that si
mple
to link and use Eet once you have written your code to use it.
Since the program is linked to Eet, it is now able to use any advertised
API calls to serialize your data.
You should make sure you add any extra compile and link flags to your
compile commands that your application may need as well. The above examp
le
is only guaranteed to make Eet add it's own requirements.
@section install How is it installed?
Simple:
@verbatim
./configure
make
su -
...
make install
@endverbatim
@section next_steps Next Steps
After you understood what Eet is and installed it in your system you
should proceed understanding the programming interface. We'd recommend
you to take a while to learn Eina
(http://docs.enlightenment.org/auto/eina/) as it is very convenient
and optimized, and Eet provides integration with it.
Recommended reading:
@li @ref Eet_File_Group to know the basics to open and save files.
@li @ref Eet_Data_Group to know the convenient way to serialize and
parse your data structures automatically. Just create your
descriptors and let Eet do the work for you.
@section intro_example Introductory Examples
@ref Examples
@todo Document data format for images and data structures.
*/
/**
@page authors Authors
@author Carsten Haitzler <raster@@rasterman.com>
@author David Goodlad <dgoodlad@@gmail.com>
@author Cedric Bail <cedric.bail@@free.fr>
@author Arnaud de Turckheim <quarium@@gmail.com>
@author Luis Felipe Strano Moraes <lfelipe@@profusion.mobi>
@author Chidambar Zinnoury <illogict@@online.fr>
@author Vincent Torri <vtorri@@univ-evry.fr>
@author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
@author Raphael Kubo da Costa <kubo@@profusion.mobi>
@author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
@author Albin "Lutin" Tonnerre <albin.tonnerre@@gmail.com>
@author Adam Simpkins <adam@@adamsimpkins.net>
@author Mike Blumenkrantz <michael.blumenkrantz@gmail.com>
Please contact <enlightenment-devel@lists.sourceforge.net> to get in
contact with the developers and maintainers.
*/
#ifndef _EET_H #ifndef _EET_H
#define _EET_H #define _EET_H
#include <stdlib.h> #include <stdlib.h>
#include <stdio.h> #include <stdio.h>
#include <Eina.h> #include <Eina.h>
#ifdef EAPI #ifdef EAPI
# undef EAPI # undef EAPI
#endif /* ifdef EAPI */ #endif /* ifdef EAPI */
skipping to change at line 52 skipping to change at line 195
* This header provides the Eet management functions. * This header provides the Eet management functions.
* *
*/ */
#define EET_VERSION_MAJOR 1 #define EET_VERSION_MAJOR 1
#define EET_VERSION_MINOR 4 #define EET_VERSION_MINOR 4
/** /**
* @typedef Eet_Version * @typedef Eet_Version
* *
* This is the Eet version information structure that can be used at * This is the Eet version information structure that can be used at
* runtiime to detect which version of eet is being used and adapt * runtime to detect which version of eet is being used and adapt
* appropriately as follows for example: * appropriately as follows for example:
* *
* @code * @code
* #if defined(EET_VERSION_MAJOR) && (EET_VERSION_MAJOR >= 1) && defined(EE T_VERSION_MINOR) && (EET_VERSION_MINOR > 2) * #if defined(EET_VERSION_MAJOR) && (EET_VERSION_MAJOR >= 1) && defined(EE T_VERSION_MINOR) && (EET_VERSION_MINOR > 2)
* printf("Eet version: %i.%i.%i\n", * printf("Eet version: %i.%i.%i\n",
* eet_version->major, * eet_version->major,
* eet_version->minor, * eet_version->minor,
* eet_version->micro); * eet_version->micro);
* if (eet_version->revision > 0) * if (eet_version->revision > 0)
* { * {
skipping to change at line 97 skipping to change at line 240
/** /**
* @enum _Eet_Error * @enum _Eet_Error
* All the error identifiers known by Eet. * All the error identifiers known by Eet.
*/ */
typedef enum _Eet_Error typedef enum _Eet_Error
{ {
EET_ERROR_NONE, /**< No error, it's all fine! */ EET_ERROR_NONE, /**< No error, it's all fine! */
EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */ EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */
EET_ERROR_EMPTY, /**< There was nothing to do */ EET_ERROR_EMPTY, /**< There was nothing to do */
EET_ERROR_NOT_WRITABLE, /**< Could not write to file or fine is #EET_FIL E_MODE_READ */ EET_ERROR_NOT_WRITABLE, /**< Could not write to file or file is #EET_FIL E_MODE_READ */
EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */ EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */
EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */ EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */
EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it i s too big */ EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it i s too big */
EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write since generic Input /Output error */ EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write due a generic Input /Output error */
EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of spac e */ EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of spac e */
EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */ EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */
EET_ERROR_MMAP_FAILED, /**< Could not mmap file */ EET_ERROR_MMAP_FAILED, /**< Could not mmap file */
EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */ EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */
EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */ EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */
EET_ERROR_INVALID_SIGNATURE, /**< Signature is invalid */ EET_ERROR_INVALID_SIGNATURE, /**< Signature is invalid */
EET_ERROR_NOT_SIGNED, /**< File or contents are not signed */ EET_ERROR_NOT_SIGNED, /**< File or contents are not signed */
EET_ERROR_NOT_IMPLEMENTED, /**< Function is not implemented */ EET_ERROR_NOT_IMPLEMENTED, /**< Function is not implemented */
EET_ERROR_PRNG_NOT_SEEDED, /**< Could not introduce random seed */ EET_ERROR_PRNG_NOT_SEEDED, /**< Could not introduce random seed */
EET_ERROR_ENCRYPT_FAILED, /**< Could not encrypt contents */ EET_ERROR_ENCRYPT_FAILED, /**< Could not encrypt contents */
EET_ERROR_DECRYPT_FAILED /**< Could not decrypt contents */ EET_ERROR_DECRYPT_FAILED /**< Could not decrypt contents */
} Eet_Error; /**< Eet error identifiers */ } Eet_Error; /**< Eet error identifiers */
/** /**
* @} * @}
*/ */
/** /**
* Initialize the EET library. * Initialize the EET library.
* *
* @return The new init count. * The first time this function is called, it will perform all the internal
* initialization required for the library to function properly and increme
mnt
* the initializiation counter. Any subsequent call only increment this cou
nter
* and return its new value, so it's safe to call this function more than o
nce.
*
* @return The new init count. Will be 0 if initialization failed.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Group * @ingroup Eet_Group
*/ */
EAPI int EAPI int
eet_init(void); eet_init(void);
/** /**
* Shut down the EET library. * Shut down the EET library.
* *
* If eet_init() was called more than once for the running application,
* eet_shutdown() will decrement the initialization counter and return its
* new value, without doing anything else. When the counter reaches 0, all
* of the internal elements will be shutdown and any memory used freed.
*
* @return The new init count. * @return The new init count.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Group * @ingroup Eet_Group
*/ */
EAPI int EAPI int
eet_shutdown(void); eet_shutdown(void);
/** /**
* Clear eet cache * Clear eet cache
* *
* Eet didn't free items by default. If you are under memory * For a faster access to previously accessed data, Eet keeps an internal
* presure, just call this function to recall all memory that are * cache of files. These files will be freed automatically only when
* not yet referenced anymore. The cache take care of modification * they are unused and the cache gets full, in order based on the last time
* on disk. * they were used.
* On systems with little memory this may present an unnecessary constraint
,
* so eet_clearcache() is available for users to reclaim the memory used by
* files that are no longer needed. Those that were open using
* ::EET_FILE_MODE_WRITE or ::EET_FILE_MODE_READ_WRITE and have modificatio
ns,
* will be written down to disk before flushing them from memory.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Group * @ingroup Eet_Group
*/ */
EAPI void EAPI void
eet_clearcache(void); eet_clearcache(void);
/** /**
* @defgroup Eet_File_Group Eet File Main Functions * @defgroup Eet_File_Group Eet File Main Functions
* *
* Functions to create, destroy and do basic manipulation of * Functions to create, destroy and do basic manipulation of
* #Eet_File handles. * #Eet_File handles.
* *
* This sections explains how to use the most basic Eet functions, which
* are used to work with eet files, read data from them, store it back in o
r
* take a look at what entries it contains, without making use of the
* serialization capabilities explained in @ref Eet_Data_Group.
*
* The following example will serve as an introduction to most, if not all,
* of these functions.
*
* If you are only using Eet, this is the only header you need to include.
* @dontinclude eet-file.c
* @skipline Eet.h
*
* Now let's create ourselves an eet file to play with. The following funct
ion
* shows step by step how to open a file and write some data in it.
* First, we define our file handler and some other things we'll put in it.
* @line static int
* @skip Eet_File
* @until ";
* @skip eet_open
*
* We open a new file in write mode, and if it fails, we just return, since
* there's not much more we can do about it..
* @until return
*
* Now, we need to write some data in our file. For now, strings will suffi
ce,
* so let's just dump a bunch of them in there.
* @until }
*
* As you can see, we copied a string into our static buffer, which is a bi
t
* bigger than the full length of the string, and then told Eet to write it
* into the file, compressed, returning the size of the data written into t
he
* file.
* This is all to show that Eet treats data as just data. It doesn't matter
* what that data represents (for now), it's all just bytes for it. As runn
ing
* the following code will show, we took a string of around 30 bytes and pu
t it
* in a buffer of 1024 bytes, but the returned size won't be any of those.
* @until printf
*
* Next, we copy into our buffer our set of strings, including their null
* terminators and write them into the file. No error checking for the sake
* of brevitiy. And a call to eet_sync() to make sure all out data is
* properly written down to disk, even though we haven't yet closed the fil
e.
* @until eet_sync
*
* One more write, this time our large array of binary data and... well, I
* couldn't come up with a valid use of the last set of strings we stored,
* so let's take it out from the file with eet_delete().
* @until eet_delete
*
* Finally, we close the file, saving any changes back to disk and return.
* Notice how, if there's any error closing the file or saving its contents
,
* the return value from the function will be a false one, which later on
* will make the program exit with an error code.
* @until return
*
* Moving onto our main function, we will open the same file and read it ba
ck.
* Trivial, but it'll show how we can do so in more than one way. We'll ski
p
* the variable declarations, as they aren't very different from what we've
* seen already.
*
* We start from the beginning by initializing Eet so things in general wor
k.
* Forgetting to do so will result in weird results or crashes when calling
* any eet function, so if you experience something like that, the first th
ing
* to look at is whether eet_init() is missing.
* Then we call our @p create_eet_file function, described above, to make
* sure we have something to work with. If the function fails it will retur
n
* 0 and we just exit, since nothing from here onwards will work anyway.
* @skip eet_init
* @until return
*
* Let's take a look now at what entries our file has. For this, we use
* eet_list(), which will return a list of strings, each being the name of
* one entry. Since we skipped before, it may be worth noting that @p list
* is declared as a @p char **.
* The @p num parameter will, of course, have the number of entries contain
ed
* in our file.
* If everything's fine, we'll get our list and print it to the screen, and
* once done with it, we free the list. That's just the list, not its conte
nts,
* as they are internal strings used by Eet and trying to free them will su
rely
* break things.
* @until }
*
* Reading back plain data is simple. Just a call to eet_read() with the fi
le
* to read from, and the name of the entry we are interested in. We get bac
k
* our data and the passed @p size parameter will contain the size of it. I
f
* the data was stored compressed, it will decompressed first.
* @until }
*
* Another simple read for the set of strings from before, except those wer
e
* deleted, so we should get a NULL return and continue normally.
* @until }
*
* Finally, we'll get our binary data in the same way we got the strings. O
nce
* again, it makes no difference for Eet what the data is, it's up to us to
* know how to handle it.
* @until {
*
* Now some cheating, we know that this data is an Eet file because, well..
.
* we just know it. So we are going to open it and take a look at its insid
es.
* For this, eet_open() won't work, as it needs to have a file on disk to r
ead
* from and all we have is some data in RAM.
*
* So how do we do? One way would be to create a normal file and write down
* our data, then open it with eet_open(). Another, faster and more efficie
nt
* if all we want to do is read the file, is to use eet_memopen_read().
* @until memopen
*
* As you can see, the size we got from our previous read was put to good u
se
* this time. Unlike the first one where all we had were strings, the size
* of the data read only serves to demonstrate that we are reading back the
* entire size of our original @p buf variable.
*
* A little peeking to see how many entries the file has and to make an
* example of eet_num_entries() to get that number when we don't care about
* their names.
* @until printf
*
* More cheating follows. Just like we knew this was an Eet file, we also k
now
* what key to read from, and ontop of that we know that the data in it is
not
* compressed.
* Knowing all this allows us to take some shortcuts.
* @until read_direct
*
* That's a direct print of our data, whatever that data is. We don't want
* to worry about having to free it later, so we just used eet_direct_read(
)
* to tell Eet to gives a pointer to the internal data in the file, without
* duplicating it. Since we said that data was not compressed, we shouldn't
* worry about printing garbage to the screen (and yes, we also know the da
ta
* is yet another string).
* We also don't care about the size of the data as it was stored in the fi
le,
* so we passed NULL as the size parameter.
* One very important note about this, however, is that we don't care about
* the size parameter because the data in the file contains the null
* terminator for the string. So when using Eet to store strings this way,
* it's very important to consider whether you will keep that final null
* byte, or to always get the size read and do the necessary checks and cop
ies.
* It's up to the user and the particular use cases to decide how this will
* be done.
*
* With everything done, close this second file and free the data used to o
pen
* it. And this is important, we can't free that data until we are done wit
h
* the file, as Eet is using it. When opening with eet_memopen_read(), the
data
* passed to it must be available for as long as the the file is open.
* @until }
*
* Finally, we close the first file, shutdown all internal resources used b
y
* Eet and leave our main function, thus terminating our program.
* @until return
*
* You can look at the full code of the example @ref eet-file.c "here".
* @{ * @{
*/ */
/** /**
* @enum _Eet_File_Mode * @enum _Eet_File_Mode
* Modes that a file can be opened. * Modes that a file can be opened.
*/ */
typedef enum _Eet_File_Mode typedef enum _Eet_File_Mode
{ {
EET_FILE_MODE_INVALID = -1, EET_FILE_MODE_INVALID = -1,
EET_FILE_MODE_READ, /**< File is read-only. */ EET_FILE_MODE_READ, /**< File is read-only. */
EET_FILE_MODE_WRITE, /**< File is write-only. */ EET_FILE_MODE_WRITE, /**< File is write-only. */
EET_FILE_MODE_READ_WRITE /**< File is for both read and write */ EET_FILE_MODE_READ_WRITE /**< File is for both read and write */
} Eet_File_Mode; /**< Modes that a file can be opened. */ } Eet_File_Mode; /**< Modes that a file can be opened. */
/** /**
* @typedef Eet_File * @typedef Eet_File
* Opaque handle that defines an Eet file (or memory). * Opaque handle that defines an Eet file (or memory).
* *
* This handle will be returned by the functions eet_open() and
* eet_memopen_read() and is used by every other function that affects the
* file in any way. When you are done with it, call eet_close() to clsoe it
* and, if the file was open for writing, write down to disk any changes ma
de
* to it.
*
* @see eet_open() * @see eet_open()
* @see eet_memopen_read() * @see eet_memopen_read()
* @see eet_close() * @see eet_close()
*/ */
typedef struct _Eet_File Eet_File; typedef struct _Eet_File Eet_File;
/** /**
* @typedef Eet_Dictionary * @typedef Eet_Dictionary
* Opaque handle that defines a file-backed (mmaped) dictionary of strings. * Opaque handle that defines a file-backed (mmaped) dictionary of strings.
*/ */
typedef struct _Eet_Dictionary Eet_Dictionary; typedef struct _Eet_Dictionary Eet_Dictionary;
/** /**
* @} * @}
*/ */
/** /**
* Open an eet file on disk, and returns a handle to it. * Open an eet file on disk, and returns a handle to it.
* @param file The file path to the eet file. eg: @c "/tmp/file.eet". * @param file The file path to the eet file. eg: @c "/tmp/file.eet".
* @param mode The mode for opening. Either #EET_FILE_MODE_READ, * @param mode The mode for opening. Either #EET_FILE_MODE_READ,
* #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE. * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE.
skipping to change at line 218 skipping to change at line 532
* *
* It will also open an eet file for writing. This will, if successful, * It will also open an eet file for writing. This will, if successful,
* delete the original file and replace it with a new empty file, till * delete the original file and replace it with a new empty file, till
* the eet file handle is closed or flushed. If it cannot be opened for * the eet file handle is closed or flushed. If it cannot be opened for
* writing or a memory error occurs, NULL is returned. * writing or a memory error occurs, NULL is returned.
* *
* You can also open the file for read/write. If you then write a key that * You can also open the file for read/write. If you then write a key that
* does not exist it will be created, if the key exists it will be replaced * does not exist it will be created, if the key exists it will be replaced
* by the new data. * by the new data.
* *
* Example: * If the same file is opened multiple times, then the same file handle wil
* @code l
* #include <Eet.h> * be returned as eet maintains an internal list of all currently open
* #include <stdio.h> * files. Note that it considers files opened for read only and those opene
* #include <string.h> d
* * for read/write and write only as 2 separate sets. Those that do not writ
* int e
* main(int argc, char **argv) * to the file and those that do. Eet will allow 2 handles to the same file
* { * if they are in the 2 separate lists/groups. That means opening a file fo
* Eet_File *ef; r
* char buf[1024], *ret, **list; * read only looks in the read only set, and returns a handle to that file
* int size, num, i; * handle and increments its reference count. If you open a file for read/w
* rite
* eet_init(); * or write only it looks in the write set and returns a handle after
* * incrementing the reference count. You need to close an eet file handle
* strcpy(buf, "Here is a string of data to save!"); * as many times as it has been opened to maintain correct reference counts
* .
* ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE); * Files whose modified timestamp or size do not match those of the existin
* if (!ef) return -1; g
* if (!eet_write(ef, "/key/to_store/at", buf, 1024, 1)) * referenced file handles will not be returned and a new handle will be
* fprintf(stderr, "Error writing data!\n"); * returned instead.
* eet_close(ef);
*
* ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_READ);
* if (!ef) return -1;
* list = eet_list(ef, "*", &num);
* if (list)
* {
* for (i = 0; i < num; i++)
* printf("Key stored: %s\n", list[i]);
* free(list);
* }
* ret = eet_read(ef, "/key/to_store/at", &size);
* if (ret)
* {
* printf("Data read (%i bytes):\n%s\n", size, ret);
* free(ret);
* }
* eet_close(ef);
*
* eet_shutdown();
*
* return 0;
* }
* @endcode
* *
* @since 1.0.0 * @since 1.0.0
*/ */
EAPI Eet_File * EAPI Eet_File *
eet_open(const char *file, eet_open(const char *file,
Eet_File_Mode mode); Eet_File_Mode mode);
/** /**
* Open an eet file directly from a memory location. The data is not copied , * Open an eet file directly from a memory location. The data is not copied ,
* so you must keep it around as long as the eet file is open. There is * so you must keep it around as long as the eet file is open. There is
* currently no cache for this kind of Eet_File, so it's reopened every tim e * currently no cache for this kind of Eet_File, so it's reopened every tim e
* you use eet_memopen_read. * you use eet_memopen_read.
* Files opened this way will always be in read-only mode.
* *
* @since 1.1.0 * @since 1.1.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI Eet_File * EAPI Eet_File *
eet_memopen_read(const void *data, eet_memopen_read(const void *data,
size_t size); size_t size);
/** /**
* Get the mode an Eet_File was opened with. * Get the mode an Eet_File was opened with.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @return The mode ef was opened with. * @return The mode ef was opened with.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI Eet_File_Mode EAPI Eet_File_Mode
skipping to change at line 352 skipping to change at line 636
eet_dictionary_get(Eet_File *ef); eet_dictionary_get(Eet_File *ef);
/** /**
* Check if a given string comes from a given dictionary * Check if a given string comes from a given dictionary
* @param ed A valid dictionary handle * @param ed A valid dictionary handle
* @param string A valid 0 byte terminated C string * @param string A valid 0 byte terminated C string
* @return 1 if it is in the dictionary, 0 otherwise * @return 1 if it is in the dictionary, 0 otherwise
* *
* This checks the given dictionary to see if the given string is actually * This checks the given dictionary to see if the given string is actually
* inside that dictionary (i.e. comes from it) and returns 1 if it does. * inside that dictionary (i.e. comes from it) and returns 1 if it does.
* If the dictionary handle is invlide, the string is NULL or the string is * If the dictionary handle is invalid, the string is NULL or the string is
* not in the dictionary, 0 is returned. * not in the dictionary, 0 is returned.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI int EAPI int
eet_dictionary_string_check(Eet_Dictionary *ed, eet_dictionary_string_check(Eet_Dictionary *ed,
const char *string); const char *string);
/** /**
* Read a specified entry from an eet file and return data * Read a specified entry from an eet file and return data
* @param ef A valid eet file handle opened for reading. * @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param size_ret Number of bytes read from entry and returned. * @param size_ret Number of bytes read from entry and returned.
* @return The data stored in that entry in the eet file. * @return The data stored in that entry in the eet file.
* *
* This function finds an entry in the eet file that is stored under the * This function finds an entry in the eet file that is stored under the
* name specified, and returns that data, decompressed, if successful. * name specified, and returns that data, decompressed, if successful.
skipping to change at line 385 skipping to change at line 669
* *
* If the eet file handle is not valid NULL is returned and size_ret is * If the eet file handle is not valid NULL is returned and size_ret is
* filled with 0. * filled with 0.
* *
* @see eet_read_cipher() * @see eet_read_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI void * EAPI void *
eet_read(Eet_File *ef, eet_read(Eet_File *ef,
const char *name, const char *name,
int *size_ret); int *size_ret);
/** /**
* Read a specified entry from an eet file and return data * Read a specified entry from an eet file and return data
* @param ef A valid eet file handle opened for reading. * @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param size_ret Number of bytes read from entry and returned. * @param size_ret Number of bytes read from entry and returned.
* @return The data stored in that entry in the eet file. * @return The data stored in that entry in the eet file.
* *
* This function finds an entry in the eet file that is stored under the * This function finds an entry in the eet file that is stored under the
* name specified, and returns that data if not compressed and successful. * name specified, and returns that data if not compressed and successful.
skipping to change at line 410 skipping to change at line 694
* call free() on the returned data. The number of bytes in the returned * call free() on the returned data. The number of bytes in the returned
* data chunk are placed in size_ret. * data chunk are placed in size_ret.
* *
* If the eet file handle is not valid NULL is returned and size_ret is * If the eet file handle is not valid NULL is returned and size_ret is
* filled with 0. * filled with 0.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI const void * EAPI const void *
eet_read_direct(Eet_File *ef, eet_read_direct(Eet_File *ef,
const char *name, const char *name,
int *size_ret); int *size_ret);
/** /**
* Write a specified entry to an eet file handle * Write a specified entry to an eet file handle
* @param ef A valid eet file handle opened for writing. * @param ef A valid eet file handle opened for writing.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param data Pointer to the data to be stored. * @param data Pointer to the data to be stored.
* @param size Length in bytes in the data to be stored. * @param size Length in bytes in the data to be stored.
* @param compress Compression flags (1 == compress, 0 = don't compress). * @param compress Compression flags (1 == compress, 0 = don't compress).
* @return bytes written on successful write, 0 on failure. * @return bytes written on successful write, 0 on failure.
* *
skipping to change at line 443 skipping to change at line 727
* The data will be copied (and optionally compressed) in ram, pending * The data will be copied (and optionally compressed) in ram, pending
* a flush to disk (it will stay in ram till the eet file handle is * a flush to disk (it will stay in ram till the eet file handle is
* closed though). * closed though).
* *
* @see eet_write_cipher() * @see eet_write_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI int EAPI int
eet_write(Eet_File *ef, eet_write(Eet_File *ef,
const char *name, const char *name,
const void *data, const void *data,
int size, int size,
int compress); int compress);
/** /**
* Delete a specified entry from an Eet file being written or re-written * Delete a specified entry from an Eet file being written or re-written
* @param ef A valid eet file handle opened for writing. * @param ef A valid eet file handle opened for writing.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @return Success or failure of the delete. * @return Success or failure of the delete.
* *
* This function will delete the specified chunk of data from the eet file * This function will delete the specified chunk of data from the eet file
* and return greater than 0 on success. 0 will be returned on failure. * and return greater than 0 on success. 0 will be returned on failure.
* *
* The eet file handle must be a valid file handle for an eet file opened * The eet file handle must be a valid file handle for an eet file opened
* for writing. If it is not, 0 will be returned and no action will be * for writing. If it is not, 0 will be returned and no action will be
* performed. * performed.
* *
* Name, must not be NULL, otherwise 0 will be returned. * Name, must not be NULL, otherwise 0 will be returned.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI int EAPI int
eet_delete(Eet_File *ef, eet_delete(Eet_File *ef,
const char *name); const char *name);
/** /**
* Alias a specific section to another one. Destination may exist or not, * Alias a specific section to another one. Destination may exist or not,
* no check are done. * no check are done.
* @param ef A valid eet file handle opened for writing. * @param ef A valid eet file handle opened for writing.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the new entry. eg: "/base/file_i_want".
* @param destination Destionation of the alias. eg: "/base/the_real_stuff_ * @param destination Actual source of the aliased entry eg: "/base/the_rea
i_want". l_stuff_i_want".
* @param compress Compression flags (1 == compress, 0 = don't compress). * @param compress Compression flags (1 == compress, 0 = don't compress).
* @return EINA_TRUE on success, EINA_FALSE on failure. * @return EINA_TRUE on success, EINA_FALSE on failure.
* *
* Name and Destination must not be NULL, otherwhise EINA_FALSE will be ret * Name and Destination must not be NULL, otherwise EINA_FALSE will be retu
urned. rned.
* The equivalent of this would be calling 'ln -s destination name'
* *
* @since 1.3.3 * @since 1.3.3
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI Eina_Bool EAPI Eina_Bool
eet_alias(Eet_File *ef, eet_alias(Eet_File *ef,
const char *name, const char *name,
const char *destination, const char *destination,
int compress); int compress);
/**
* Retrieve the destination name of an alias
* @param ef A valid eet file handle opened for writing
* @param name Name of the entry. eg: "/base/file_i_want"
* @return Destination of the alias. eg: "/base/the_real_stuff_i_want", NUL
L on failure
*
* Name must not be NULL, otherwise NULL will be returned.
*
* @since 1.5
* @ingroup Eet_File_Group
*/
EAPI const char *
eet_alias_get(Eet_File *ef,
const char *name);
/** /**
* List all entries in eet file matching shell glob. * List all entries in eet file matching shell glob.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @param glob A shell glob to match against. * @param glob A shell glob to match against.
* @param count_ret Number of entries found to match. * @param count_ret Number of entries found to match.
* @return Pointer to an array of strings. * @return Pointer to an array of strings.
* *
* This function will list all entries in the eet file matching the * This function will list all entries in the eet file matching the
* supplied shell glob and return an allocated list of their names, if * supplied shell glob and return an allocated list of their names, if
skipping to change at line 522 skipping to change at line 822
* that are the names of the entries that matched, and count_ret will have * that are the names of the entries that matched, and count_ret will have
* the number of entries in this array placed in it. * the number of entries in this array placed in it.
* *
* Hint: an easy way to list all entries in an eet file is to use a glob * Hint: an easy way to list all entries in an eet file is to use a glob
* value of "*". * value of "*".
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI char ** EAPI char **
eet_list(Eet_File *ef, eet_list(Eet_File *ef,
const char *glob, const char *glob,
int *count_ret); int *count_ret);
/** /**
* Return the number of entries in the specified eet file. * Return the number of entries in the specified eet file.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @return Number of entries in ef or -1 if the number of entries * @return Number of entries in ef or -1 if the number of entries
* cannot be read due to open mode restrictions. * cannot be read due to open mode restrictions.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
skipping to change at line 573 skipping to change at line 873
* *
* If the eet file handle is not valid NULL is returned and size_ret is * If the eet file handle is not valid NULL is returned and size_ret is
* filled with 0. * filled with 0.
* *
* @see eet_read() * @see eet_read()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Cipher_Group * @ingroup Eet_File_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_read_cipher(Eet_File *ef, eet_read_cipher(Eet_File *ef,
const char *name, const char *name,
int *size_ret, int *size_ret,
const char *cipher_key); const char *cipher_key);
/** /**
* Write a specified entry to an eet file handle using a cipher. * Write a specified entry to an eet file handle using a cipher.
* @param ef A valid eet file handle opened for writing. * @param ef A valid eet file handle opened for writing.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param data Pointer to the data to be stored. * @param data Pointer to the data to be stored.
* @param size Length in bytes in the data to be stored. * @param size Length in bytes in the data to be stored.
* @param compress Compression flags (1 == compress, 0 = don't compress). * @param compress Compression flags (1 == compress, 0 = don't compress).
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
skipping to change at line 608 skipping to change at line 908
* The data will be copied (and optionally compressed) in ram, pending * The data will be copied (and optionally compressed) in ram, pending
* a flush to disk (it will stay in ram till the eet file handle is * a flush to disk (it will stay in ram till the eet file handle is
* closed though). * closed though).
* *
* @see eet_write() * @see eet_write()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Cipher_Group * @ingroup Eet_File_Cipher_Group
*/ */
EAPI int EAPI int
eet_write_cipher(Eet_File *ef, eet_write_cipher(Eet_File *ef,
const char *name, const char *name,
const void *data, const void *data,
int size, int size,
int compress, int compress,
const char *cipher_key); const char *cipher_key);
/** /**
* @defgroup Eet_File_Image_Group Image Store and Load * @defgroup Eet_File_Image_Group Image Store and Load
* *
* Eet efficiently stores and loads images, including alpha * Eet efficiently stores and loads images, including alpha
* channels and lossy compressions. * channels and lossy compressions.
*
* Eet can handle both lossy compression with different levels of quality a
nd
* non-lossy compression with different compression levels. It's also possi
ble,
* given an image data, to only read its header to get the image informatio
n
* without decoding the entire content for it.
*
* The encode family of functions will take an image raw buffer and its
* parameters and compress it in memory, returning the new buffer.
* Likewise, the decode functions will read from the given location in memo
ry
* and return the uncompressed image.
*
* The read and write functions will, respectively, encode and decode to or
* from an Eet file, under the specified key.
*
* These functions are fairly low level and the same functionality can be
* achieved using Evas and Edje, making it much easier to work with images
* as well as not needing to worry about things like scaling them.
*/ */
/** /**
* Read just the header data for an image and dont decode the pixels. * Read just the header data for an image and dont decode the pixels.
* @param ef A valid eet file handle opened for reading. * @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param w A pointer to the unsigned int to hold the width in pixels. * @param w A pointer to the unsigned int to hold the width in pixels.
* @param h A pointer to the unsigned int to hold the height in pixels. * @param h A pointer to the unsigned int to hold the height in pixels.
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on successful decode, 0 otherwise * @return 1 on successful decode, 0 otherwise
* *
* This function reads an image from an eet file stored under the named * Reads and decodes the image header data stored under the given key and
* key in the eet file and return a pointer to the decompressed pixel data. * Eet file.
*
* The other parameters of the image (width, height etc.) are placed into
* the values pointed to (they must be supplied). The pixel data is a linea
r
* array of pixels starting from the top-left of the image scanning row by
* row from left to right. Each pile is a 32bit value, with the high byte
* being the alpha channel, the next being red, then green, and the low byt
e
* being blue. The width and height are measured in pixels and will be
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not.
* *
* On success the function returns 1 indicating the header was read and * The information decoded is placed in each of the parameters, which must
* decoded properly, or 0 on failure. be
* provided. The width and height, measured in pixels, will be stored under
* the variables pointed by @p w and @p h, respectively. If the read or
* decode of the header fails, this values will be 0. The @p alpha paramete
r
* will be 1 or 0, denoting if the alpha channel of the image is used or no
t.
* If the image was losslessly compressed, the @p compress parameter will h
old
* the compression amount used, ranging from 0 to 9 and @p lossy will be 0.
* In the case of lossy compression, @p lossy will be 1, and the compressio
n
* quality will be placed under @p quality, with a value ranging from 0 to
100.
* *
* @see eet_data_image_header_decode()
* @see eet_data_image_header_read_cipher() * @see eet_data_image_header_read_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI int EAPI int
eet_data_image_header_read(Eet_File *ef, eet_data_image_header_read(Eet_File *ef,
const char *name, const char *name,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Read image data from the named key in the eet file. * Read image data from the named key in the eet file.
* @param ef A valid eet file handle opened for reading. * @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param w A pointer to the unsigned int to hold the width in pixels. * @param w A pointer to the unsigned int to hold the width in pixels.
* @param h A pointer to the unsigned int to hold the height in pixels. * @param h A pointer to the unsigned int to hold the height in pixels.
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return The image pixel data decoded * @return The image pixel data decoded
* *
* This function reads an image from an eet file stored under the named * Reads and decodes the image stored in the given Eet file under the named
* key in the eet file and return a pointer to the decompressed pixel data. * key.
* *
* The other parameters of the image (width, height etc.) are placed into * The returned pixel data is a linear array of pixels starting from the
* the values pointed to (they must be supplied). The pixel data is a linea * top-left of the image, scanning row by row from left to right. Each pile
r * is a 32bit value, with the high byte being the alpha channel, the next b
* array of pixels starting from the top-left of the image scanning row by eing
* row from left to right. Each pile is a 32bit value, with the high byte * red, then green, and the low byte being blue.
* being the alpha channel, the next being red, then green, and the low byt *
e * The rest of the parameters are the same as in eet_data_image_header_read
* being blue. The width and height are measured in pixels and will be ().
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not.
* *
* On success the function returns a pointer to the image data decoded. The * On success the function returns a pointer to the image data decoded. The
* calling application is responsible for calling free() on the image data * calling application is responsible for calling free() on the image data
* when it is done with it. On failure NULL is returned and the parameter * when it is done with it. On failure NULL is returned and the parameter
* values may not contain any sensible data. * values may not contain any sensible data.
* *
* @see eet_data_image_header_read()
* @see eet_data_image_decode()
* @see eet_data_image_read_cipher() * @see eet_data_image_read_cipher()
* @see eet_data_image_read_to_surface()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI void * EAPI void *
eet_data_image_read(Eet_File *ef, eet_data_image_read(Eet_File *ef,
const char *name, const char *name,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Read image data from the named key in the eet file. * Read image data from the named key in the eet file and store it in the g iven buffer.
* @param ef A valid eet file handle opened for reading. * @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param src_x The starting x coordinate from where to dump the stream. * @param src_x The starting x coordinate from where to dump the stream.
* @param src_y The starting y coordinate from where to dump the stream. * @param src_y The starting y coordinate from where to dump the stream.
* @param d A pointer to the pixel surface. * @param d A pointer to the pixel surface.
* @param w The expected width in pixels of the pixel surface to decode. * @param w The expected width in pixels of the pixel surface to decode.
* @param h The expected height in pixels of the pixel surface to decode. * @param h The expected height in pixels of the pixel surface to decode.
* @param row_stride The length of a pixels line in the destination surface . * @param row_stride The length of a pixels line in the destination surface .
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on success, 0 otherwise. * @return 1 on success, 0 otherwise.
* *
* This function reads an image from an eet file stored under the named * Reads and decodes the image stored in the given Eet file, placing the
* key in the eet file and return a pointer to the decompressed pixel data. * resulting pixel data in the buffer pointed by the user.
* *
* The other parameters of the image (width, height etc.) are placed into * Like eet_data_image_read(), it takes the image data stored under the
* the values pointed to (they must be supplied). The pixel data is a linea * @p name key in the @p ef file, but instead of returning a new buffer wit
r h
* array of pixels starting from the top-left of the image scanning row by * the pixel data, it places the result in the buffer pointed by @p d, whic
* row from left to right. Each pile is a 32bit value, with the high byte h
* being the alpha channel, the next being red, then green, and the low byt * must be provided by the user and of sufficient size to hold the requeste
e d
* being blue. The width and height are measured in pixels and will be * portion of the image.
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes *
* that the alpha channel is not used. 1 denotes that it is significant. * The @p src_x and @p src_y parameters indicate the top-left corner of the
* Compress is filled with the compression value/amount the image was * section of the image to decode. These have to be higher or equal than 0
* stored with. The quality value is filled with the quality encoding of and
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if * less than the respective total width and height of the image. The width
* the image was encoded lossily or not. * and height of the section of the image to decode are given in @p w and @
p h
* and also can't be higher than the total width and height of the image.
*
* The @p row_stride parameter indicates the length in bytes of each line i
n
* the destination buffer and it has to be at least @p w * 4.
*
* All the other parameters are the same as in eet_data_image_read().
* *
* On success the function returns 1, and 0 on failure. On failure the * On success the function returns 1, and 0 on failure. On failure the
* parameter values may not contain any sensible data. * parameter values may not contain any sensible data.
* *
* @see eet_data_image_read()
* @see eet_data_image_decode()
* @see eet_data_image_decode_to_surface()
* @see eet_data_image_read_to_surface_cipher() * @see eet_data_image_read_to_surface_cipher()
* *
* @since 1.0.2 * @since 1.0.2
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI int EAPI int
eet_data_image_read_to_surface(Eet_File *ef, eet_data_image_read_to_surface(Eet_File *ef,
const char *name, const char *name,
unsigned int src_x, unsigned int src_x,
unsigned int src_y, unsigned int src_y,
unsigned int *d, unsigned int *d,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
unsigned int row_stride, unsigned int row_stride,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Write image data to the named key in an eet file. * Write image data to the named key in an eet file.
* @param ef A valid eet file handle opened for writing. * @param ef A valid eet file handle opened for writing.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param data A pointer to the image pixel data. * @param data A pointer to the image pixel data.
* @param w The width of the image in pixels. * @param w The width of the image in pixels.
* @param h The height of the image in pixels. * @param h The height of the image in pixels.
* @param alpha The alpha channel flag. * @param alpha The alpha channel flag.
* @param compress The compression amount. * @param compress The compression amount.
skipping to change at line 800 skipping to change at line 1116
* the alpha values are not useful and 1 meaning they are). Compress can * the alpha values are not useful and 1 meaning they are). Compress can
* be from 0 to 9 (0 meaning no compression, 9 meaning full compression). * be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
* This is only used if the image is not lossily encoded. Quality is used o n * This is only used if the image is not lossily encoded. Quality is used o n
* lossy compression and should be a value from 0 to 100. The lossy flag * lossy compression and should be a value from 0 to 100. The lossy flag
* can be 0 or 1. 0 means encode losslessly and 1 means to encode with * can be 0 or 1. 0 means encode losslessly and 1 means to encode with
* image quality loss (but then have a much smaller encoding). * image quality loss (but then have a much smaller encoding).
* *
* On success this function returns the number of bytes that were required * On success this function returns the number of bytes that were required
* to encode the image data, or on failure it returns 0. * to encode the image data, or on failure it returns 0.
* *
* @see eet_data_image_read()
* @see eet_data_image_encode()
* @see eet_data_image_write_cipher() * @see eet_data_image_write_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI int EAPI int
eet_data_image_write(Eet_File *ef, eet_data_image_write(Eet_File *ef,
const char *name, const char *name,
const void *data, const void *data,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
int alpha, int alpha,
int compress, int compress,
int quality, int quality,
int lossy); int lossy);
/** /**
* Decode Image data header only to get information. * Decode Image data header only to get information.
* @param data The encoded pixel data. * @param data The encoded pixel data.
* @param size The size, in bytes, of the encoded pixel data. * @param size The size, in bytes, of the encoded pixel data.
* @param w A pointer to the unsigned int to hold the width in pixels. * @param w A pointer to the unsigned int to hold the width in pixels.
* @param h A pointer to the unsigned int to hold the height in pixels. * @param h A pointer to the unsigned int to hold the height in pixels.
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on success, 0 on failure. * @return 1 on success, 0 on failure.
* *
* This function takes encoded pixel data and decodes it into raw RGBA * This function works exactly like eet_data_image_header_read(), but inste
* pixels on success. ad
* * of reading from an Eet file, it takes the buffer of size @p size pointed
* The other parameters of the image (width, height etc.) are placed into * by @p data, which must be a valid Eet encoded image.
* the values pointed to (they must be supplied). The pixel data is a linea
r
* array of pixels starting from the top-left of the image scanning row by
* row from left to right. Each pixel is a 32bit value, with the high byte
* being the alpha channel, the next being red, then green, and the low byt
e
* being blue. The width and height are measured in pixels and will be
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not.
* *
* On success the function returns 1 indicating the header was read and * On success the function returns 1 indicating the header was read and
* decoded properly, or 0 on failure. * decoded properly, or 0 on failure.
* *
* @see eet_data_image_header_read()
* @see eet_data_image_header_decode_cipher() * @see eet_data_image_header_decode_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI int EAPI int
eet_data_image_header_decode(const void *data, eet_data_image_header_decode(const void *data,
int size, int size,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Decode Image data into pixel data. * Decode Image data into pixel data.
* @param data The encoded pixel data. * @param data The encoded pixel data.
* @param size The size, in bytes, of the encoded pixel data. * @param size The size, in bytes, of the encoded pixel data.
* @param w A pointer to the unsigned int to hold the width in pixels. * @param w A pointer to the unsigned int to hold the width in pixels.
* @param h A pointer to the unsigned int to hold the height in pixels. * @param h A pointer to the unsigned int to hold the height in pixels.
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return The image pixel data decoded * @return The image pixel data decoded
* *
* This function takes encoded pixel data and decodes it into raw RGBA * This function takes encoded pixel data and decodes it into raw RGBA
* pixels on success. * pixels on success.
* *
* The other parameters of the image (width, height etc.) are placed into * It works exactly like eet_data_image_read(), but it takes the encoded
* the values pointed to (they must be supplied). The pixel data is a linea * data in the @p data buffer of size @p size, instead of reading from a fi
r le.
* array of pixels starting from the top-left of the image scanning row by * All the others parameters are also the same.
* row from left to right. Each pixel is a 32bit value, with the high byte
* being the alpha channel, the next being red, then green, and the low byt
e
* being blue. The width and height are measured in pixels and will be
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not.
* *
* On success the function returns a pointer to the image data decoded. The * On success the function returns a pointer to the image data decoded. The
* calling application is responsible for calling free() on the image data * calling application is responsible for calling free() on the image data
* when it is done with it. On failure NULL is returned and the parameter * when it is done with it. On failure NULL is returned and the parameter
* values may not contain any sensible data. * values may not contain any sensible data.
* *
* @see eet_data_image_read()
* @see eet_data_image_decode_cipher() * @see eet_data_image_decode_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI void * EAPI void *
eet_data_image_decode(const void *data, eet_data_image_decode(const void *data,
int size, int size,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Decode Image data into pixel data. * Decode Image data into pixel data and stores in the given buffer.
* @param data The encoded pixel data. * @param data The encoded pixel data.
* @param size The size, in bytes, of the encoded pixel data. * @param size The size, in bytes, of the encoded pixel data.
* @param src_x The starting x coordinate from where to dump the stream. * @param src_x The starting x coordinate from where to dump the stream.
* @param src_y The starting y coordinate from where to dump the stream. * @param src_y The starting y coordinate from where to dump the stream.
* @param d A pointer to the pixel surface. * @param d A pointer to the pixel surface.
* @param w The expected width in pixels of the pixel surface to decode. * @param w The expected width in pixels of the pixel surface to decode.
* @param h The expected height in pixels of the pixel surface to decode. * @param h The expected height in pixels of the pixel surface to decode.
* @param row_stride The length of a pixels line in the destination surface . * @param row_stride The length of a pixels line in the destination surface .
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on success, 0 otherwise. * @return 1 on success, 0 otherwise.
* *
* This function takes encoded pixel data and decodes it into raw RGBA * Like eet_data_image_read_to_surface(), but reading the given @p data buf
* pixels on success. fer
* * instead of a file.
* The other parameters of the image (alpha, compress etc.) are placed into
* the values pointed to (they must be supplied). The pixel data is a linea
r
* array of pixels starting from the top-left of the image scanning row by
* row from left to right. Each pixel is a 32bit value, with the high byte
* being the alpha channel, the next being red, then green, and the low byt
e
* being blue. The width and height are measured in pixels and will be
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not.
* *
* On success the function returns 1, and 0 on failure. On failure the * On success the function returns 1, and 0 on failure. On failure the
* parameter values may not contain any sensible data. * parameter values may not contain any sensible data.
* *
* @see eet_data_image_read_to_surface()
* @see eet_data_image_decode_to_surface_cipher() * @see eet_data_image_decode_to_surface_cipher()
* *
* @since 1.0.2 * @since 1.0.2
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI int EAPI int
eet_data_image_decode_to_surface(const void *data, eet_data_image_decode_to_surface(const void *data,
int size, int size,
unsigned int src_x, unsigned int src_x,
unsigned int src_y, unsigned int src_y,
unsigned int *d, unsigned int *d,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
unsigned int row_stride, unsigned int row_stride,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Encode image data for storage or transmission. * Encode image data for storage or transmission.
* @param data A pointer to the image pixel data. * @param data A pointer to the image pixel data.
* @param size_ret A pointer to an int to hold the size of the returned dat a. * @param size_ret A pointer to an int to hold the size of the returned dat a.
* @param w The width of the image in pixels. * @param w The width of the image in pixels.
* @param h The height of the image in pixels. * @param h The height of the image in pixels.
* @param alpha The alpha channel flag. * @param alpha The alpha channel flag.
* @param compress The compression amount. * @param compress The compression amount.
* @param quality The quality encoding amount. * @param quality The quality encoding amount.
* @param lossy The lossiness flag. * @param lossy The lossiness flag.
* @return The encoded image data. * @return The encoded image data.
* *
* This function stakes image pixel data and encodes it with compression an d * This function stakes image pixel data and encodes it with compression an d
* possible loss of quality (as a trade off for size) for storage or * possible loss of quality (as a trade off for size) for storage or
* transmission to another system. * transmission to another system.
* *
* The data expected is the same format as returned by eet_data_image_read. * It works like eet_data_image_write(), but instead of writing the encoded
* If this is not the case weird things may happen. Width and height must * image into an Eet file, it allocates a new buffer of the size required a
* be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning nd
* the alpha values are not useful and 1 meaning they are). Compress can * returns the encoded data in it.
* be from 0 to 9 (0 meaning no compression, 9 meaning full compression).
* This is only used if the image is not lossily encoded. Quality is used o
n
* lossy compression and should be a value from 0 to 100. The lossy flag
* can be 0 or 1. 0 means encode losslessly and 1 means to encode with
* image quality loss (but then have a much smaller encoding).
* *
* On success this function returns a pointer to the encoded data that you * On success this function returns a pointer to the encoded data that you
* can free with free() when no longer needed. * can free with free() when no longer needed.
* *
* @see eet_data_image_write()
* @see eet_data_image_read()
* @see eet_data_image_encode_cipher() * @see eet_data_image_encode_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
*/ */
EAPI void * EAPI void *
eet_data_image_encode(const void *data, eet_data_image_encode(const void *data,
int *size_ret, int *size_ret,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
int alpha, int alpha,
int compress, int compress,
int quality, int quality,
int lossy); int lossy);
/** /**
* @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Ciphe r * @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Ciphe r
* *
* Most of the @ref Eet_File_Image_Group have alternative versions * Most of the @ref Eet_File_Image_Group have alternative versions
* that accounts for ciphers to protect their content. * that accounts for ciphers to protect their content.
* *
* @see @ref Eet_Cipher_Group * @see @ref Eet_Cipher_Group
* *
* @ingroup Eet_File_Image_Group * @ingroup Eet_File_Image_Group
skipping to change at line 1038 skipping to change at line 1321
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on successful decode, 0 otherwise * @return 1 on successful decode, 0 otherwise
* *
* This function reads an image from an eet file stored under the named * This function reads an image from an eet file stored under the named
* key in the eet file and return a pointer to the decompressed pixel data. * key in the eet file and return a pointer to the decompressed pixel data.
* *
* The other parameters of the image (width, height etc.) are placed into * The other parameters of the image (width, height etc.) are placed into
* the values pointed to (they must be supplied). The pixel data is a linea r * the values pointed to (they must be supplied). The pixel data is a linea r
* array of pixels starting from the top-left of the image scanning row by * array of pixels starting from the top-left of the image scanning row by
* row from left to right. Each pile is a 32bit value, with the high byte * row from left to right. Each pixel is a 32bit value, with the high byte
* being the alpha channel, the next being red, then green, and the low byt e * being the alpha channel, the next being red, then green, and the low byt e
* being blue. The width and height are measured in pixels and will be * being blue. The width and height are measured in pixels and will be
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant. * that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was * Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of * stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not. * the image was encoded lossily or not.
* *
* On success the function returns 1 indicating the header was read and * On success the function returns 1 indicating the header was read and
* decoded properly, or 0 on failure. * decoded properly, or 0 on failure.
* *
* @see eet_data_image_header_read() * @see eet_data_image_header_read()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_image_header_read_cipher(Eet_File *ef, eet_data_image_header_read_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Read image data from the named key in the eet file using a cipher. * Read image data from the named key in the eet file using a cipher.
* @param ef A valid eet file handle opened for reading. * @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param w A pointer to the unsigned int to hold the width in pixels. * @param w A pointer to the unsigned int to hold the width in pixels.
* @param h A pointer to the unsigned int to hold the height in pixels. * @param h A pointer to the unsigned int to hold the height in pixels.
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return The image pixel data decoded * @return The image pixel data decoded
* *
* This function reads an image from an eet file stored under the named * This function reads an image from an eet file stored under the named
* key in the eet file and return a pointer to the decompressed pixel data. * key in the eet file and return a pointer to the decompressed pixel data.
* *
* The other parameters of the image (width, height etc.) are placed into * The other parameters of the image (width, height etc.) are placed into
* the values pointed to (they must be supplied). The pixel data is a linea r * the values pointed to (they must be supplied). The pixel data is a linea r
* array of pixels starting from the top-left of the image scanning row by * array of pixels starting from the top-left of the image scanning row by
* row from left to right. Each pile is a 32bit value, with the high byte * row from left to right. Each pixel is a 32bit value, with the high byte
* being the alpha channel, the next being red, then green, and the low byt e * being the alpha channel, the next being red, then green, and the low byt e
* being blue. The width and height are measured in pixels and will be * being blue. The width and height are measured in pixels and will be
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant. * that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was * Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of * stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not. * the image was encoded lossily or not.
* *
* On success the function returns a pointer to the image data decoded. The * On success the function returns a pointer to the image data decoded. The
* calling application is responsible for calling free() on the image data * calling application is responsible for calling free() on the image data
* when it is done with it. On failure NULL is returned and the parameter * when it is done with it. On failure NULL is returned and the parameter
* values may not contain any sensible data. * values may not contain any sensible data.
* *
* @see eet_data_image_read() * @see eet_data_image_read()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_data_image_read_cipher(Eet_File *ef, eet_data_image_read_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Read image data from the named key in the eet file using a cipher. * Read image data from the named key in the eet file using a cipher.
* @param ef A valid eet file handle opened for reading. * @param ef A valid eet file handle opened for reading.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param src_x The starting x coordinate from where to dump the stream. * @param src_x The starting x coordinate from where to dump the stream.
* @param src_y The starting y coordinate from where to dump the stream. * @param src_y The starting y coordinate from where to dump the stream.
* @param d A pointer to the pixel surface. * @param d A pointer to the pixel surface.
* @param w The expected width in pixels of the pixel surface to decode. * @param w The expected width in pixels of the pixel surface to decode.
skipping to change at line 1140 skipping to change at line 1423
* @param quality A pointer to the int to hold the quality amount. * @param quality A pointer to the int to hold the quality amount.
* @param lossy A pointer to the int to hold the lossiness flag. * @param lossy A pointer to the int to hold the lossiness flag.
* @return 1 on success, 0 otherwise. * @return 1 on success, 0 otherwise.
* *
* This function reads an image from an eet file stored under the named * This function reads an image from an eet file stored under the named
* key in the eet file and return a pointer to the decompressed pixel data. * key in the eet file and return a pointer to the decompressed pixel data.
* *
* The other parameters of the image (width, height etc.) are placed into * The other parameters of the image (width, height etc.) are placed into
* the values pointed to (they must be supplied). The pixel data is a linea r * the values pointed to (they must be supplied). The pixel data is a linea r
* array of pixels starting from the top-left of the image scanning row by * array of pixels starting from the top-left of the image scanning row by
* row from left to right. Each pile is a 32bit value, with the high byte * row from left to right. Each pixel is a 32bit value, with the high byte
* being the alpha channel, the next being red, then green, and the low byt e * being the alpha channel, the next being red, then green, and the low byt e
* being blue. The width and height are measured in pixels and will be * being blue. The width and height are measured in pixels and will be
* greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes
* that the alpha channel is not used. 1 denotes that it is significant. * that the alpha channel is not used. 1 denotes that it is significant.
* Compress is filled with the compression value/amount the image was * Compress is filled with the compression value/amount the image was
* stored with. The quality value is filled with the quality encoding of * stored with. The quality value is filled with the quality encoding of
* the image file (0 - 100). The lossy flags is either 0 or 1 as to if * the image file (0 - 100). The lossy flags is either 0 or 1 as to if
* the image was encoded lossily or not. * the image was encoded lossily or not.
* *
* On success the function returns 1, and 0 on failure. On failure the * On success the function returns 1, and 0 on failure. On failure the
* parameter values may not contain any sensible data. * parameter values may not contain any sensible data.
* *
* @see eet_data_image_read_to_surface() * @see eet_data_image_read_to_surface()
* *
* @since 1.0.2 * @since 1.0.2
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_image_read_to_surface_cipher(Eet_File *ef, eet_data_image_read_to_surface_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
unsigned int src_x, unsigned int src_x,
unsigned int src_y, unsigned int src_y,
unsigned int *d, unsigned int *d,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
unsigned int row_stride, unsigned int row_stride,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Write image data to the named key in an eet file using a cipher. * Write image data to the named key in an eet file using a cipher.
* @param ef A valid eet file handle opened for writing. * @param ef A valid eet file handle opened for writing.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param data A pointer to the image pixel data. * @param data A pointer to the image pixel data.
* @param w The width of the image in pixels. * @param w The width of the image in pixels.
* @param h The height of the image in pixels. * @param h The height of the image in pixels.
* @param alpha The alpha channel flag. * @param alpha The alpha channel flag.
skipping to change at line 1210 skipping to change at line 1493
* *
* On success this function returns the number of bytes that were required * On success this function returns the number of bytes that were required
* to encode the image data, or on failure it returns 0. * to encode the image data, or on failure it returns 0.
* *
* @see eet_data_image_write() * @see eet_data_image_write()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_image_write_cipher(Eet_File *ef, eet_data_image_write_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
const void *data, const void *data,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
int alpha, int alpha,
int compress, int compress,
int quality, int quality,
int lossy); int lossy);
/** /**
* Decode Image data header only to get information using a cipher. * Decode Image data header only to get information using a cipher.
* @param data The encoded pixel data. * @param data The encoded pixel data.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param size The size, in bytes, of the encoded pixel data. * @param size The size, in bytes, of the encoded pixel data.
* @param w A pointer to the unsigned int to hold the width in pixels. * @param w A pointer to the unsigned int to hold the width in pixels.
* @param h A pointer to the unsigned int to hold the height in pixels. * @param h A pointer to the unsigned int to hold the height in pixels.
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
skipping to change at line 1259 skipping to change at line 1542
* *
* On success the function returns 1 indicating the header was read and * On success the function returns 1 indicating the header was read and
* decoded properly, or 0 on failure. * decoded properly, or 0 on failure.
* *
* @see eet_data_image_header_decode() * @see eet_data_image_header_decode()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_image_header_decode_cipher(const void *data, eet_data_image_header_decode_cipher(const void *data,
const char *cipher_key, const char *cipher_key,
int size, int size,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Decode Image data into pixel data using a cipher. * Decode Image data into pixel data using a cipher.
* @param data The encoded pixel data. * @param data The encoded pixel data.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param size The size, in bytes, of the encoded pixel data. * @param size The size, in bytes, of the encoded pixel data.
* @param w A pointer to the unsigned int to hold the width in pixels. * @param w A pointer to the unsigned int to hold the width in pixels.
* @param h A pointer to the unsigned int to hold the height in pixels. * @param h A pointer to the unsigned int to hold the height in pixels.
* @param alpha A pointer to the int to hold the alpha flag. * @param alpha A pointer to the int to hold the alpha flag.
* @param compress A pointer to the int to hold the compression amount. * @param compress A pointer to the int to hold the compression amount.
skipping to change at line 1309 skipping to change at line 1592
* calling application is responsible for calling free() on the image data * calling application is responsible for calling free() on the image data
* when it is done with it. On failure NULL is returned and the parameter * when it is done with it. On failure NULL is returned and the parameter
* values may not contain any sensible data. * values may not contain any sensible data.
* *
* @see eet_data_image_decode() * @see eet_data_image_decode()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_data_image_decode_cipher(const void *data, eet_data_image_decode_cipher(const void *data,
const char *cipher_key, const char *cipher_key,
int size, int size,
unsigned int *w, unsigned int *w,
unsigned int *h, unsigned int *h,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Decode Image data into pixel data using a cipher. * Decode Image data into pixel data using a cipher.
* @param data The encoded pixel data. * @param data The encoded pixel data.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param size The size, in bytes, of the encoded pixel data. * @param size The size, in bytes, of the encoded pixel data.
* @param src_x The starting x coordinate from where to dump the stream. * @param src_x The starting x coordinate from where to dump the stream.
* @param src_y The starting y coordinate from where to dump the stream. * @param src_y The starting y coordinate from where to dump the stream.
* @param d A pointer to the pixel surface. * @param d A pointer to the pixel surface.
* @param w The expected width in pixels of the pixel surface to decode. * @param w The expected width in pixels of the pixel surface to decode.
skipping to change at line 1361 skipping to change at line 1644
* *
* On success the function returns 1, and 0 on failure. On failure the * On success the function returns 1, and 0 on failure. On failure the
* parameter values may not contain any sensible data. * parameter values may not contain any sensible data.
* *
* @see eet_data_image_decode_to_surface() * @see eet_data_image_decode_to_surface()
* *
* @since 1.0.2 * @since 1.0.2
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_image_decode_to_surface_cipher(const void *data, eet_data_image_decode_to_surface_cipher(const void *data,
const char *cipher_key, const char *cipher_key,
int size, int size,
unsigned int src_x, unsigned int src_x,
unsigned int src_y, unsigned int src_y,
unsigned int *d, unsigned int *d,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
unsigned int row_stride, unsigned int row_stride,
int *alpha, int *alpha,
int *compress, int *compress,
int *quality, int *quality,
int *lossy); int *lossy);
/** /**
* Encode image data for storage or transmission using a cipher. * Encode image data for storage or transmission using a cipher.
* @param data A pointer to the image pixel data. * @param data A pointer to the image pixel data.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param size_ret A pointer to an int to hold the size of the returned dat a. * @param size_ret A pointer to an int to hold the size of the returned dat a.
* @param w The width of the image in pixels. * @param w The width of the image in pixels.
* @param h The height of the image in pixels. * @param h The height of the image in pixels.
* @param alpha The alpha channel flag. * @param alpha The alpha channel flag.
* @param compress The compression amount. * @param compress The compression amount.
skipping to change at line 1411 skipping to change at line 1694
* *
* On success this function returns a pointer to the encoded data that you * On success this function returns a pointer to the encoded data that you
* can free with free() when no longer needed. * can free with free() when no longer needed.
* *
* @see eet_data_image_encode() * @see eet_data_image_encode()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Image_Cipher_Group * @ingroup Eet_File_Image_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_data_image_encode_cipher(const void *data, eet_data_image_encode_cipher(const void *data,
const char *cipher_key, const char *cipher_key,
unsigned int w, unsigned int w,
unsigned int h, unsigned int h,
int alpha, int alpha,
int compress, int compress,
int quality, int quality,
int lossy, int lossy,
int *size_ret); int *size_ret);
/** /**
* @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms * @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms
* *
* Eet allows one to protect entries of an #Eet_File * Eet allows one to protect entries of an #Eet_File
* individually. This may be used to ensure data was not tampered or * individually. This may be used to ensure data was not tampered or
* that third party does not read your data. * that third party does not read your data.
* *
* @see @ref Eet_File_Cipher_Group * @see @ref Eet_File_Cipher_Group
* @see @ref Eet_File_Image_Cipher_Group * @see @ref Eet_File_Image_Cipher_Group
* *
* @{ * @{
*/ */
/** /**
* @typedef Eet_Key * @typedef Eet_Key
* Opaque handle that defines an identity (also known as key) * Opaque handle that defines an identity (also known as key)
* in Eet's cipher system. * in Eet's cipher system.
*/ */
typedef struct _Eet_Key Eet_Key; typedef struct _Eet_Key Eet_Key;
/** /**
* @} * @}
*/ */
/** /**
* Callback used to request if needed the password of a private key. * Callback used to request if needed the password of a private key.
* *
* @param buffer the buffer where to store the password. * @param buffer the buffer where to store the password.
* @param size the maximum password size (size of buffer, including '@\0'). * @param size the maximum password size (size of buffer, including '@\0').
* @param rwflag if the buffer is also readable or just writable. * @param rwflag if the buffer is also readable or just writable.
* @param data currently unused, may contain some context in future. * @param data currently unused, may contain some context in future.
* @return 1 on success and password was set to @p buffer, 0 on failure. * @return 1 on success and password was set to @p buffer, 0 on failure.
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
typedef int (*Eet_Key_Password_Callback) (char *buffer, int size, int rwfla g, void *data); typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag , void *data);
/** /**
* Create an Eet_Key needed for signing an eet file. * Create an Eet_Key needed for signing an eet file.
* *
* The certificate should provide the public that match the private key. * The certificate should provide the public that match the private key.
* No verification is done to ensure that. * No verification is done to ensure that.
* *
* @param certificate_file The file where to find the certificate. * @param certificate_file The file where to find the certificate.
* @param private_key_file The file that contains the private key. * @param private_key_file The file that contains the private key.
* @param cb Function to callback if password is required to unlock * @param cb Function to callback if password is required to unlock
* private key. * private key.
* @return A key handle to use, or @c NULL on failure. * @return A key handle to use, or @c NULL on failure.
* *
* @see eet_identity_close() * @see eet_identity_close()
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
EAPI Eet_Key * EAPI Eet_Key *
eet_identity_open(const char *certificate_file, eet_identity_open(const char *certificate_file,
const char *private_key_file, const char *private_key_file,
Eet_Key_Password_Callback cb); Eet_Key_Password_Callback cb);
/** /**
* Close and release all ressource used by an Eet_Key. An * Close and release all ressource used by an Eet_Key. An
* reference counter prevent it from being freed until all file * reference counter prevent it from being freed until all file
* using it are also closed. * using it are also closed.
* *
* @param key the key handle to close and free resources. * @param key the key handle to close and free resources.
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
skipping to change at line 1507 skipping to change at line 1790
* @param ef the file to set the identity. * @param ef the file to set the identity.
* @param key the key handle to set as identity. * @param key the key handle to set as identity.
* @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or * @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or
* #EET_ERROR_NONE on success. * #EET_ERROR_NONE on success.
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
EAPI Eet_Error EAPI Eet_Error
eet_identity_set(Eet_File *ef, eet_identity_set(Eet_File *ef,
Eet_Key *key); Eet_Key *key);
/** /**
* Display both private and public key of an Eet_Key. * Display both private and public key of an Eet_Key.
* *
* @param key the handle to print. * @param key the handle to print.
* @param out where to print. * @param out where to print.
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
EAPI void EAPI void
eet_identity_print(Eet_Key *key, eet_identity_print(Eet_Key *key,
FILE *out); FILE *out);
/** /**
* Get the x509 der certificate associated with an Eet_File. Will return NU LL * Get the x509 der certificate associated with an Eet_File. Will return NU LL
* if the file is not signed. * if the file is not signed.
* *
* @param ef The file handle to query. * @param ef The file handle to query.
* @param der_length The length of returned data, may be @c NULL. * @param der_length The length of returned data, may be @c NULL.
* @return the x509 certificate or @c NULL on error. * @return the x509 certificate or @c NULL on error.
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
EAPI const void * EAPI const void *
eet_identity_x509(Eet_File *ef, eet_identity_x509(Eet_File *ef,
int *der_length); int *der_length);
/** /**
* Get the raw signature associated with an Eet_File. Will return NULL * Get the raw signature associated with an Eet_File. Will return NULL
* if the file is not signed. * if the file is not signed.
* *
* @param ef The file handle to query. * @param ef The file handle to query.
* @param signature_length The length of returned data, may be @c NULL. * @param signature_length The length of returned data, may be @c NULL.
* @return the raw signature or @c NULL on error. * @return the raw signature or @c NULL on error.
* *
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
EAPI const void * EAPI const void *
eet_identity_signature(Eet_File *ef, eet_identity_signature(Eet_File *ef,
int *signature_length); int *signature_length);
/** /**
* Get the SHA1 associated with a file. Could be the one used to * Get the SHA1 associated with a file. Could be the one used to
* sign the data or if the data where not signed, it will be the * sign the data or if the data where not signed, it will be the
* SHA1 of the file. * SHA1 of the file.
* *
* @param ef The file handle to query. * @param ef The file handle to query.
* @param sha1_length The length of returned data, may be @c NULL. * @param sha1_length The length of returned data, may be @c NULL.
* @return the associated SHA1 or @c NULL on error. * @return the associated SHA1 or @c NULL on error.
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
EAPI const void * EAPI const void *
eet_identity_sha1(Eet_File *ef, eet_identity_sha1(Eet_File *ef,
int *sha1_length); int *sha1_length);
/** /**
* Display the x509 der certificate to out. * Display the x509 der certificate to out.
* *
* @param certificate the x509 certificate to print * @param certificate the x509 certificate to print
* @param der_length The length the certificate. * @param der_length The length the certificate.
* @param out where to print. * @param out where to print.
* *
* @since 1.2.0 * @since 1.2.0
* @ingroup Eet_Cipher_Group * @ingroup Eet_Cipher_Group
*/ */
EAPI void EAPI void
eet_identity_certificate_print(const unsigned char *certificate, eet_identity_certificate_print(const unsigned char *certificate,
int der_length, int der_length,
FILE *out); FILE *out);
/** /**
* @defgroup Eet_Data_Group Eet Data Serialization * @defgroup Eet_Data_Group Eet Data Serialization
* *
* Convenience functions to serialize and parse complex data * Convenience functions to serialize and parse complex data
* structures to binary blobs. * structures to binary blobs.
* *
* While Eet core just handles binary blobs, it is often required * While Eet core just handles binary blobs, it is often required
* to save some structured data of different types, such as * to save some structured data of different types, such as
* strings, integers, lists, hashes and so on. * strings, integers, lists, hashes and so on.
skipping to change at line 1609 skipping to change at line 1892
* - #Eet_Data_Descriptor to tell inside such type, the members and * - #Eet_Data_Descriptor to tell inside such type, the members and
* their offsets inside the memory blob, their types and * their offsets inside the memory blob, their types and
* names. These members can be simple types or other * names. These members can be simple types or other
* #Eet_Data_Descriptor, allowing hierarchical types to be * #Eet_Data_Descriptor, allowing hierarchical types to be
* defined. * defined.
* *
* Given that C provides no introspection, this process can be * Given that C provides no introspection, this process can be
* quite cumbersome, so we provide lots of macros and convenience * quite cumbersome, so we provide lots of macros and convenience
* functions to aid creating the types. * functions to aid creating the types.
* *
* Example: * We make now a quick overview of some of the most commonly used elements
* of this part of the library. A simple example of a configuration system
* will work as a somewhat real life example that is still simple enough to
* follow.
* Only the relevant sections will be shown here, but you can get the full
* code @ref eet-data-simple.c "here".
*
* Ignoring the included headers, we'll begin by defining our configuration
* struct.
* @dontinclude eet-data-simple.c
* @skip typedef
* @until }
*
* When using Eet, you don't think in matters of what data the program need
s
* to run and which you would like to store. It's all the same and if it ma
kes
* more sense to keep them together, it's perfectly fine to do so. At the t
ime
* of telling Eet how your data is comprised you can leave out the things
* that are runtime only and let Eet take care of the rest for you.
*
* The key used to store the config follows, as well as the variable used t
o
* store our data descriptor.
* This last one is very important. It's the one thing that Eet will use to
* identify your data, both at the time of writing it to the file and when
* loading from it.
* @skipline MY_CONF
* @skipline Eet_Data_Descriptor
*
* Now we'll see how to create this descriptor, so Eet knows how to handle
* our data later on.
* Begin our function by declaring an Eet_Data_Descriptor_Class, which is
* used to create the actual descriptor. This class contains the name of
* our data type, its size and several functions that dictate how Eet shoul
d
* handle memory to allocate the necessary bits to bring our data to life.
* You, as a user, will very hardly set this class' contents directly. The
* most common scenario is to use one of the provided macros that set it us
ing
* the Eina data types, so that's what we'll be doing across all our exampl
es.
* @skip static void
* @until eet_data_descriptor_stream_new
*
* Now that we have our descriptor, we need to make it describe something.
* We do so by telling it which members of our struct we want it to know ab
out
* and their types.
* The eet_data_descriptor_element_add() function takes care of this, but i
t's
* too cumbersome for normal use, so several macros are provided that make
* it easier to handle. Even with them, however, code can get very repetiti
ve
* and it's not uncommon to define custom macros using them to save on typi
ng.
* @skip #define
* @until }
*
* Now our descriptor knows about the parts of our structure that we are
* interesting in saving. You can see that not all of them are there, yet E
et
* will find those that need saving and do the right thing. When loading ou
r
* data, any non-described fields in the structure will be zeroed, so there
's
* no need to worry about garbage memory in them.
* Refer to the documentation of #EET_DATA_DESCRIPTOR_ADD_BASIC to understa
nd
* what our macro does.
*
* We are done with our descriptor init function and it's proper to have th
e
* relevant shutdown. Proper coding guidelines indiciate that all memory
* allocated should be freed when the program ends, and since you will most
* likely keep your descriptor around for the life or your application, it'
s
* only right to free it at the end.
* @skip static void
* @until }
*
* Not listed here, but included in the full example are functions to creat
e
* a blank configuration and free it. The first one will only be used when
* no file exists to load from, or nothing is found in it, but the latter i
s
* used regardless of where our data comes from. Unless you are reading dir
ect
* data from the Eet file, you will be in charge of freeing anything loaded
* from it.
*
* Now it's time to look at how we can load our config from some file.
* Begin by opening the Eet file normally.
* @skip static My_Conf_Type
* @until }
*
* And now we need to read the data from the file and decode it using our
* descriptor. Fortunately, that's all done in one single step.
* @until goto
*
* And that's it for all Eet cares about. But since we are dealing with a
* common case, as is save and load of user configurations, the next fragme
nt
* of code shows why we have a version field in our struct, and how you can
* use it to load older configuration files and update them as needed.
* @until }
*
* Finally, clsoe the file and return the newly loaded config data.
* @until }
*
* Saving data is just as easy. The full version of the following function
* includes code to save to a temporary file first, so you can be sure not
* to lose all your data in the case of a failure mid-writing. You can look
* at it @ref eet-data-simple.c "here".
* @skip static Eina_Bool
* @until {
* @skipline Eina_Bool ret
* @skip eet_open
* @until eet_close
* @skip return
* @until }
*
* To close, our main function, which doesn't do much. Just take some argum
ents
* from the command line with the name of the file to load and another one
* where to save again. If input file doesn't exist, a new config structure
* will be created and saved to our output file.
* @skip int main
* @until return ret
* @until }
*
* The following is a list of more advanced and detailed examples.
* @li @ref eet_data_nested_example
* @li @ref eet_data_file_descriptor
* @li @ref Example_Eet_Data_File_Descriptor_02
* @li @ref Example_Eet_Data_Cipher_Decipher
*/
/**
* @page eet_data_nested_example Nested structures and Eet Data Descriptors
*
* We've seen already a simple example of how to use Eet Data Descriptors
* to handle our structures, but it didn't show how this works when you
* have structures inside other structures.
*
* Now, there's a very simple case of this, for when you have inline struct
s
* to keep your big structure more organized, you don't need anything else
* besides what @ref eet-data-simple.c "this simple example does".
* Just use something like @p some_struct.sub_struct.member when adding the
* member to the descriptor and it will work.
* *
* For example:
* @code * @code
* #include <Eet.h> * typedef struct
* #include <Evas.h>
*
* typedef struct _blah2
* { * {
* char *string; * int a_number;
* } Blah2; * char *a_string;
* struct {
* int other_num;
* int one_more;
* } sub;
* } some_struct;
* *
* typedef struct _blah3 * void some_function()
* { * {
* char *string; * ...
* } Blah3; * my_desc = eet_data_descriptor_stream_new(&eddc);
* * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_number",
* typedef struct _blah * a_number, EET_T_INT);
* { * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "a_string",
* char character; * a_string, EET_T_STRING);
* short sixteen; * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.other_num",
* int integer; * sub.other_num, EET_T_INT);
* long long lots; * EET_DATA_DESCRIPTOR_ADD_BASIC(my_desc, some_struct, "sub.one_more",
* float floating; * sub.one_more", EET_T_INT);
* double floating_lots; * ...
* char *string; * }
* Blah2 *blah2; * @endcode
* Eina_List *blah3;
* } Blah;
* *
* int * But this is not what we are here for today. When we talk about nested
* main(int argc, char **argv) * structures, what we really want are things like lists and hashes to be
* taken into consideration automatically, and all their contents saved and
* loaded just like ordinary integers and strings are.
*
* And of course, Eet can do that, and considering the work it saves you as
a
* programmer, we could say it's even easier to do than handling just integ
ers.
*
* Let's begin with our example then, which is not all too different from t
he
* simple one introduced earlier.
*
* We won't ignore the headers this time to show how easy it is to use Eina
* data types with Eet, but we'll still skip most of the code that is not
* pertinent to what we want to show now, but as usual, you can get it full
* by follwing @ref eet-data-nested.c "this link".
*
* @dontinclude eet-data-nested.c
* @skipline Eina.h
* @skipline Eet.h
* @skip typedef struct
* @until } My_Conf_Subtype
*
* Extremely similar to our previous example. Just a new struct in there, a
nd
* a pointer to a list in the one we already had. Handling a list of subtyp
es
* is easy on our program, but now we'll see what Eet needs to work with th
em
* (Hint: it's easy too).
* @skip _my_conf_descriptor
* @until _my_conf_sub_descriptor
*
* Since we have two structures now, it's only natural that we'll need two
* descriptors. One for each, which will be defined exactly as before.
* @skip static void
* @until eddc
* @skip EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET
* @until _my_conf_sub_descriptor
*
* We create our descriptors, each for one type, and as before, we are goin
g to
* use a simple macro to set their contents, to save on typing.
* @skip #define
* @until EET_T_UCHAR
*
* So far, nothing new. We have our descriptors and we know already how to
* save them separately. But what we want is to link them together, and eve
n
* more so, we want our main type to hold a list of more than one of the ne
w
* sub type. So how do we do that?
*
* Simple enough, we tell Eet that our main descriptor will hold a list, of
* which each node will point to some type described by our new descriptor.
* @skip EET_DATA_DESCRIPTOR_ADD_LIST
* @until _my_conf_sub_descriptor
*
* And that's all. We are closing the function now so as to not leave dangl
ing
* curly braces, but there's nothing more to show in this example. Only oth
er
* additions are the necessary code to free our new data, but you can see i
t
* in the full code listing.
* @until }
*/
/**
* @page eet_data_file_descriptor Advanced use of Eet Data Descriptors
*
* A real life example is usually the best way to see how things are used,
* but they also involve a lot more code than what needs to be shown, so
* instead of going that way, we'll be borrowing some pieces from one in
* the following example. It's been slightly modified from the original
* source to show more of the varied ways in which Eet can handle our data.
*
* @ref eet-data-file_descriptor_01.c "This example" shows a cache of user
* accounts and messages received, and it's a bit more interactive than
* previous examples.
*
* Let's begin by looking at the structures we'll be using. First we have
* one to define the messages the user receives and one for the one he post
s.
* Straight forward and nothing new here.
* @dontinclude eet-data-file_descriptor_01.c
* @skip typedef
* @until My_Post
*
* One more to declare the account itself. This one will contain a list of
* all messages received, and the posts we make ourselves will be kept in a
n
* array. No special reason other than to show how to use arrays with Eet.
* @until My_Account
*
* Finally, the main structure to hold our cache of accounts. We'll be look
ing
* for these accounts by their names, so let's keep them in a hash, using
* that name as the key.
* @until My_Cache
*
* As explained before, we need one descriptor for each struct we want Eet
* to handle, but this time we also want to keep around our Eet file and it
s
* string dictionary. You will see why in a moment.
* @skip Eet_Data_Descriptor
* @until _my_post_descriptor
* @skip Eet_File
* @until Eet_Dictionary
*
* The differences begin now. They aren't much, but we'll be creating our
* descriptors differently. Things can be added to our cache, but we won't
* be modifying the current contents, so we can consider the data read from
* it to be read-only, and thus allow Eet to save time and memory by not
* duplicating thins unnecessary.
* @skip static void
* @until _my_post_descriptor
*
* As the comment in the code explains, we are asking Eet to give us string
s
* directly from the mapped file, which avoids having to load it in memory
* and data duplication.
* Of course, there are things to take into account when doing things this
* way, and they will be mentioned as we encounter those special cases.
*
* Next comes the actual description of our data, just like we did in the
* previous examples.
* @skip #define
* @until #undef
* @until #define
* @until #undef
*
* And the account struct's description doesn't add much new, but it's wort
h
* commenting on it.
* @skip #define
* @until _my_post_descriptor
*
* How to add a list we've seen before, but now we are also adding an array
.
* There's nothing really special about it, but it's important to note that
* the EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY is used to add arrays of variable
* length to a descriptor. That is, arrays just like the one we defined.
* Since there's no way in C to know how long they are, we need to keep
* track of the count ourselves and Eet needs to know how to do so as well.
* That's what the @p posts_count member of our struct is for. When adding
* our array member, this macro will look for another variable in the struc
t
* named just like the array, but with @p _count attached to the end.
* When saving our data, Eet will know how many elements the array contains
* by looking into this count variable. When loading back from a file, this
* variable will be set to the right number of elements.
*
* Another option for arrays is to use EET_DATA_DESCRIPTOR_ADD_ARRAY, which
* takes care of fixed sized arrays.
* For example, let's suppose that we want to keep track of only the last
* ten posts the user sent, and we declare our account struct as follows
* @code
* typedef struct
* { * {
* Blah blah; * unsigned int id;
* Blah2 blah2; * const char *name;
* Blah3 blah3; * Eina_List *messages;
* Eet_Data_Descriptor *edd, *edd2, *edd3; * My_Post posts[10];
* Eet_Data_Descriptor_Class eddc, eddc2, eddc3; * } My_Account;
* void *data; * @endcode
* int size; * Then we would add the array to our descriptor with
* FILE *f; * @code
* Blah *blah_in; * EET_DATA_DESCRIPTOR_ADD_ARRAY(_my_account_descriptor, My_Account, "posts
* ",
* eet_init(); * posts, _my_post_descriptor);
*
* EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc3, Blah3);
* edd3 = eet_data_descriptor_stream_new(&eddc3);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd3, Blah3, "string3", string, EET_T_S
TRING);
*
* EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc2, Blah2);
* edd2 = eet_data_descriptor_stream_new(&eddc2);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd2, Blah2, "string2", string, EET_T_S
TRING);
*
* EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(&eddc, Blah);
* edd = eet_data_descriptor_stream_new(&eddc);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "character", character, EET_
T_CHAR);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "sixteen", sixteen, EET_T_SH
ORT);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "integer", integer, EET_T_IN
T);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "lots", lots, EET_T_LONG_LON
G);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating", floating, EET_T_
FLOAT);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "floating_lots", floating_lo
ts, EET_T_DOUBLE);
* EET_DATA_DESCRIPTOR_ADD_BASIC(edd, Blah, "string", string, EET_T_STRI
NG);
* EET_DATA_DESCRIPTOR_ADD_SUB(edd, Blah, "blah2", blah2, edd2);
* EET_DATA_DESCRIPTOR_ADD_LIST(edd, Blah, "blah3", blah3, edd3);
*
* blah3.string = "PANTS";
*
* blah2.string = "subtype string here!";
*
* blah.character = '7';
* blah.sixteen = 0x7777;
* blah.integer = 0xc0def00d;
* blah.lots = 0xdeadbeef31337777;
* blah.floating = 3.141592654;
* blah.floating_lots = 0.777777777777777;
* blah.string = "bite me like a turnip";
* blah.blah2 = &blah2;
* blah.blah3 = eina_list_append(NULL, &blah3);
* blah.blah3 = eina_list_append(blah.blah3, &blah3);
* blah.blah3 = eina_list_append(blah.blah3, &blah3);
* blah.blah3 = eina_list_append(blah.blah3, &blah3);
* blah.blah3 = eina_list_append(blah.blah3, &blah3);
* blah.blah3 = eina_list_append(blah.blah3, &blah3);
* blah.blah3 = eina_list_append(blah.blah3, &blah3);
*
* data = eet_data_descriptor_encode(edd, &blah, &size);
* printf("-----DECODING\n");
* blah_in = eet_data_descriptor_decode(edd, data, size);
*
* printf("-----DECODED!\n");
* printf("%c\n", blah_in->character);
* printf("%x\n", (int)blah_in->sixteen);
* printf("%x\n", blah_in->integer);
* printf("%lx\n", blah_in->lots);
* printf("%f\n", (double)blah_in->floating);
* printf("%f\n", (double)blah_in->floating_lots);
* printf("%s\n", blah_in->string);
* printf("%p\n", blah_in->blah2);
* printf(" %s\n", blah_in->blah2->string);
* {
* Eina_List *l;
* Blah3 *blah3_in;
*
* EINA_LIST_FOREACH(blah_in->blah3, l, blah3_in)
* {
* printf("%p\n", blah3_in);
* printf(" %s\n", blah3_in->string);
* }
* }
* eet_data_descriptor_free(edd);
* eet_data_descriptor_free(edd2);
* eet_data_descriptor_free(edd3);
*
* eet_shutdown();
*
* return 0;
* }
* @endcode * @endcode
* *
* Notice how this time we don't have a @p posts_count variable in our stru
ct.
* We could have it for the program to keep track of how many posts the
* array actually contains, but Eet no longer needs it. Being defined that
* way the array is already taking up all the memory needed for the ten
* elements, and it is possible in C to determine how much it is in code.
* When saving our data, Eet will just dump the entire memory blob into the
* file, regardless of how much of it is really used. So it's important to
* take into consideration this kind of things when defining your data type
s.
* Each has its uses, its advantages and disadvantages and it's up to you
* to decide which to use.
*
* Now, going back to our example, we have to finish adding our data to the
* descriptors. We are only missing the main one for the cache, which
* contains our hash of accounts.
* Unless you are using your own hash functions when setting the descriptor
* class, always use hashes with string type keys.
* @skip #define
* @until }
*
* If you remember, we told Eet not to duplicate memory when possible at th
e
* time of loading back our data. But this doesn't mean everything will be
* loaded straight from disk and we don't have to worry about freeing it.
* Data in the Eet file is compressed and encoded, so it still needs to be
* decoded and memory will be allocated to convert it back into something w
e
* can use. We also need to take care of anything we add in the current
* instance of the program.
* To summarize, any string we get from Eet is likely to be a pointer to th
e
* internal dictionary, and trying to free it will, in the best case, crash
* our application right away.
*
* So how do we know if we have to free a string? We check if it's part of
* the dictionary, and if it's not there we can be sure it's safe to get
* rid of it.
* @skip static void
* @skip }
* @skip static void
* @until }
*
* See how this is used when adding a new message to our cache.
* @skip static My_Message
* @until return msg
* @until free(msg)
* @until }
*
* Skipping all the utility functions used by our program (remember you can
* look at the full example @ref eet-data-file_descriptor_01.c "here") we g
et to
* our cache loading code. Nothing out of the ordinary at first, just the
* same old open file, read data using our main descriptor to decode it
* into something we can use and check version of loaded data and if it doe
sn't
* match, do something accordingly.
* @skip static My_Cache
* @until }
* @until }
* @until }
*
* Then comes the interesting part. Remember how we kept two more global
* variables with our descriptors? One of them we already used to check if
* it was right to free a string or not, but we didn't know where it came f
rom.
* Loading our data straight from the mmapped file means that we can't clos
e
* it until we are done using it, so we need to keep its handler around unt
il
* then. It also means that any changes done to the file can, and will,
* invalidate all our pointers to the file backed data, so if we add someth
ing
* and save the file, we need to reload our cache.
*
* Thus our load function checks if we had an open file, if there is it get
s
* closed and our variable is updated to the new handler. Then we get the
* string dictionary we use to check if a string is part of it or not.
* Updating any references to the cache data is up you as a programmer to
* handle properly, there's nothing Eet can do in this situation.
* @until }
*
* The save function doesn't have anything new, and all that's left after i
t
* is the main program, which doesn't really have anything of interest with
in
* the scope of what we are learning.
*/
/**
* @addtogroup Eet_Data_Group
* @{ * @{
*/ */
#define EET_T_UNKNOW 0 /**< Unknown data encoding type */ #define EET_T_UNKNOW 0 /**< Unknown data encoding type */
#define EET_T_CHAR 1 /**< Data type: char */ #define EET_T_CHAR 1 /**< Data type: char */
#define EET_T_SHORT 2 /**< Data type: short */ #define EET_T_SHORT 2 /**< Data type: short */
#define EET_T_INT 3 /**< Data type: int */ #define EET_T_INT 3 /**< Data type: int */
#define EET_T_LONG_LONG 4 /**< Data type: long long */ #define EET_T_LONG_LONG 4 /**< Data type: long long */
#define EET_T_FLOAT 5 /**< Data type: float */ #define EET_T_FLOAT 5 /**< Data type: float */
#define EET_T_DOUBLE 6 /**< Data type: double */ #define EET_T_DOUBLE 6 /**< Data type: double */
#define EET_T_UCHAR 7 /**< Data type: unsigned char */ #define EET_T_UCHAR 7 /**< Data type: unsigned char */
skipping to change at line 1764 skipping to change at line 2319
#define EET_G_VARIANT 106 /**< Selectable subtype group */ #define EET_G_VARIANT 106 /**< Selectable subtype group */
#define EET_G_LAST 107 /**< Last group type */ #define EET_G_LAST 107 /**< Last group type */
#define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */ #define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */
/** /**
* @typedef Eet_Data_Descriptor * @typedef Eet_Data_Descriptor
* *
* Opaque handle that have information on a type members. * Opaque handle that have information on a type members.
* *
* Descriptors are created using an #Eet_Data_Descriptor_Class, and they
* describe the contents of the structure that will be serialized by Eet.
* Not all members need be described by it, just those that should be handl
ed
* by Eet. This way it's possible to have one structure with both data to b
e
* saved to a file, like application configuration, and runtime information
* that would be meaningless to store, but is appropriate to keep together
* during the program execution.
* The members are added by means of * The members are added by means of
* EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(), * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB(),
* EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH() * EET_DATA_DESCRIPTOR_ADD_LIST(), EET_DATA_DESCRIPTOR_ADD_HASH()
* or eet_data_descriptor_element_add(). * or eet_data_descriptor_element_add().
* *
* @see eet_data_descriptor_stream_new() * @see eet_data_descriptor_stream_new()
* @see eet_data_descriptor_file_new() * @see eet_data_descriptor_file_new()
* @see eet_data_descriptor_free() * @see eet_data_descriptor_free()
*/ */
typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor; typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor;
/** /**
* @def EET_DATA_DESCRIPTOR_CLASS_VERSION * @def EET_DATA_DESCRIPTOR_CLASS_VERSION
* The version of #Eet_Data_Descriptor_Class at the time of the * The version of #Eet_Data_Descriptor_Class at the time of the
* distribution of the sources. One should define this to its * distribution of the sources. One should define this to its
* version member so it is compatible with abi changes, or at least * version member so it is compatible with abi changes, or at least
* will not crash with them. * will not crash with them.
*/ */
#define EET_DATA_DESCRIPTOR_CLASS_VERSION 4 #define EET_DATA_DESCRIPTOR_CLASS_VERSION 4
/** /**
* @typedef Eet_Data_Descriptor_Class * @typedef Eet_Data_Descriptor_Class
* *
* Instructs Eet about memory management for different needs under * Instructs Eet about memory management for different needs under
* serialization and parse process. * serialization and parse process.
*/ */
typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class; typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class;
typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void * h, const char *k, void *dt, void *fdt); typedef int (*Eet_Descriptor_Hash_Foreach_Callb ack_Callback)(void *h, const char *k, void *dt, void *fdt);
typedef void *(*Eet_Descriptor_Mem_Alloc_Callback)(size_t size); typedef void * (*Eet_Descriptor_Mem_Alloc_Callback
typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem); )(size_t size);
typedef char *(*Eet_Descriptor_Str_Alloc_Callback)(const char *str); typedef void (*Eet_Descriptor_Mem_Free_Callback)
typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str); (void *mem);
typedef void *(*Eet_Descriptor_List_Next_Callback)(void *l); typedef char * (*Eet_Descriptor_Str_Alloc_Callback
typedef void *(*Eet_Descriptor_List_Append_Callback)(void *l, void *d )(const char *str);
); typedef void (*Eet_Descriptor_Str_Free_Callback)
typedef void *(*Eet_Descriptor_List_Data_Callback)(void *l); (const char *str);
typedef void *(*Eet_Descriptor_List_Free_Callback)(void *l); typedef void * (*Eet_Descriptor_List_Next_Callback
typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_De )(void *l);
scriptor_Hash_Foreach_Callback_Callback func, void *fdt); typedef void * (*Eet_Descriptor_List_Append_Callba
typedef void *(*Eet_Descriptor_Hash_Add_Callback)(void *h, const char ck)(void *l, void *d);
*k, void *d); typedef void * (*Eet_Descriptor_List_Data_Callback
typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h); )(void *l);
typedef char *(*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char typedef void * (*Eet_Descriptor_List_Free_Callback
*str); )(void *l);
typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char * typedef void (*Eet_Descriptor_Hash_Foreach_Callb
str); ack)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt
typedef const char *(*Eet_Descriptor_Type_Get_Callback)(const void *data, E );
ina_Bool *unknow); typedef void * (*Eet_Descriptor_Hash_Add_Callback)
typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, v (void *h, const char *k, void *d);
oid *data, Eina_Bool unknow); typedef void (*Eet_Descriptor_Hash_Free_Callback
typedef void *(*Eet_Descriptor_Array_Alloc_Callback)(size_t size); )(void *h);
typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem); typedef char * (*Eet_Descriptor_Str_Direct_Alloc_C
allback)(const char *str);
typedef void (*Eet_Descriptor_Str_Direct_Free_Ca
llback)(const char *str);
typedef const char * (*Eet_Descriptor_Type_Get_Callback)
(const void *data, Eina_Bool *unknow);
typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)
(const char *type, void *data, Eina_Bool unknow);
typedef void * (*Eet_Descriptor_Array_Alloc_Callba
ck)(size_t size);
typedef void (*Eet_Descriptor_Array_Free_Callbac
k)(void *mem);
/** /**
* @struct _Eet_Data_Descriptor_Class * @struct _Eet_Data_Descriptor_Class
* *
* Instructs Eet about memory management for different needs under * Instructs Eet about memory management for different needs under
* serialization and parse process. * serialization and parse process.
* *
* If using Eina data types, it is advised to use the helpers * The list and hash methods match the Eina API, so for a more detalied
* EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and * reference on them, look at the Eina_List and Eina_Hash documentation,
* EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(). * respectively.
* For the most part these will be used with the standard Eina functions,
* so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
* EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything
* accordingly.
*/ */
struct _Eet_Data_Descriptor_Class struct _Eet_Data_Descriptor_Class
{ {
int version; /**< ABI version as #EET_DATA_DESCRIPTOR_CLASS_VER int version; /**< ABI version. Should always be set to #EET_DAT
SION */ A_DESCRIPTOR_CLASS_VERSION */
const char *name; /**< Name of data type to be serialized */ const char *name; /**< Name of the user data type to be serialized */
int size; /**< Size in bytes of data type to be serialized */ int size; /**< Size in bytes of the user data type to be serial
struct { ized */
Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to allocate memo struct
ry (usually malloc()) */ {
Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free memory (us Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to alloc
ually free()) */ ate memory (usually malloc()) */
Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to allocate a st Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free m
ring */ emory (usually free()) */
Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a string * Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to alloc
/ ate a string */
Eet_Descriptor_List_Next_Callback list_next; /**< how to iterate to th Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a
e next element of a list. Receives and should return the list node. */ string */
Eet_Descriptor_List_Append_Callback list_append; /**< how to append da Eet_Descriptor_List_Next_Callback list_next; /**< how to itera
ta @p d to list which head node is @p l */ te to the next element of a list. Receives and should return the list node.
Eet_Descriptor_List_Data_Callback list_data; /**< retrieves the data f */
rom node @p l */ Eet_Descriptor_List_Append_Callback list_append; /**< how to app
Eet_Descriptor_List_Free_Callback list_free; /**< free all the nodes f end data @p d to list which head node is @p l */
rom the list which head node is @p l */ Eet_Descriptor_List_Data_Callback list_data; /**< retrieves th
Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates over e data from node @p l */
all elements in the hash @p h in no specific order */ Eet_Descriptor_List_Free_Callback list_free; /**< free all the
Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new data @p d as nodes from the list which head node is @p l */
key @p k in hash @p h */ Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates
Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all entries fro over all elements in the hash @p h in no specific order */
m the hash @p h */ Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new dat
Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how to a @p d with key @p k in hash @p h */
allocate a string directly from file backed/mmaped region pointed by @p st Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all ent
r */ ries from the hash @p h */
Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to f Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how t
ree a string returned by str_direct_alloc */ o allocate a string directly from file backed/mmaped region pointed by @p s
Eet_Descriptor_Type_Get_Callback type_get; /**< convert any kind of da tr */
ta type to a name that define an Eet_Data_Element. */ Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to
Eet_Descriptor_Type_Set_Callback type_set; /**< set the type at a part free a string returned by str_direct_alloc */
icular address */ Eet_Descriptor_Type_Get_Callback type_get; /**< get the type,
Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to allocate as used in the union or variant mapping, that should be used to store the
memory for array (usually malloc()) */ given data into the eet file. */
Eet_Descriptor_Array_Free_Callback array_free; /**< how to free memory Eet_Descriptor_Type_Set_Callback type_set; /**< called when l
for array (usually free()) */ oading a mapped type with the given @p type used to describe the type in th
e descriptor */
Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to all
ocate memory for array (usually malloc()) */
Eet_Descriptor_Array_Free_Callback array_free; /**< how to free
memory for array (usually free()) */
} func; } func;
}; };
/** /**
* @} * @}
*/ */
/** /**
* Create a new empty data structure descriptor. * Create a new empty data structure descriptor.
* @param name The string name of this data structure (most be a * @param name The string name of this data structure (most be a
skipping to change at line 1906 skipping to change at line 2473
Eet_Descriptor_Hash_Foreach_Callback func_hash_fore ach, Eet_Descriptor_Hash_Foreach_Callback func_hash_fore ach,
Eet_Descriptor_Hash_Add_Callback func_hash_add, Eet_Descriptor_Hash_Add_Callback func_hash_add,
Eet_Descriptor_Hash_Free_Callback func_hash_free); Eet_Descriptor_Hash_Free_Callback func_hash_free);
/* /*
* FIXME: * FIXME:
* *
* moving to this api from the old above. this will break things when the * moving to this api from the old above. this will break things when the
* move happens - but be warned * move happens - but be warned
*/ */
EINA_DEPRECATED EAPI Eet_Data_Descriptor * EINA_DEPRECATED EAPI Eet_Data_Descriptor *
eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc); eet_data_descriptor2_new(const Eet_Data_Descriptor_Class *eddc);
EINA_DEPRECATED EAPI Eet_Data_Descriptor * EINA_DEPRECATED EAPI Eet_Data_Descriptor *
eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc); eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc);
/** /**
* This function creates a new data descriptore and returns a handle to the * This function creates a new data descriptor and returns a handle to the
* new data descriptor. On creation it will be empty, containing no content s * new data descriptor. On creation it will be empty, containing no content s
* describing anything other than the shell of the data structure. * describing anything other than the shell of the data structure.
* @param eddc The data descriptor to free. * @param eddc The class from where to create the data descriptor.
* *
* You add structure members to the data descriptor using the macros * You add structure members to the data descriptor using the macros
* EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
* EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
* adding to the description. * adding to the description.
* *
* Once you have described all the members of a struct you want loaded, or * Once you have described all the members of a struct you want loaded or
* saved eet can load and save those members for you, encode them into * savedi, eet can load and save those members for you, encode them into
* endian-independent serialised data chunks for transmission across a * endian-independent serialised data chunks for transmission across a
* a network or more. * a network or more.
* *
* This function specially ignore str_direct_alloc and str_direct_free. It * This function specially ignores str_direct_alloc and str_direct_free. It
* is useful when the eet_data you are reading don't have a dictionnary * is useful when the eet_data you are reading doesn't have a dictionary,
* like network stream or ipc. It also mean that all string will be allocat * like network stream or IPC. It also mean that all string will be allocat
ed ed
* and duplicated in memory. * and duplicated in memory.
* *
* @since 1.2.3 * @since 1.2.3
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI Eet_Data_Descriptor * EAPI Eet_Data_Descriptor *
eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc); eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc);
/** /**
* This function creates a new data descriptore and returns a handle to the * This function creates a new data descriptor and returns a handle to the
* new data descriptor. On creation it will be empty, containing no content s * new data descriptor. On creation it will be empty, containing no content s
* describing anything other than the shell of the data structure. * describing anything other than the shell of the data structure.
* @param eddc The data descriptor to free. * @param eddc The class from where to create the data descriptor.
* *
* You add structure members to the data descriptor using the macros * You add structure members to the data descriptor using the macros
* EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
* EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are
* adding to the description. * adding to the description.
* *
* Once you have described all the members of a struct you want loaded, or * Once you have described all the members of a struct you want loaded or
* saved eet can load and save those members for you, encode them into * savedi, eet can load and save those members for you, encode them into
* endian-independent serialised data chunks for transmission across a * endian-independent serialised data chunks for transmission across a
* a network or more. * a network or more.
* *
* This function use str_direct_alloc and str_direct_free. It is * This function uses str_direct_alloc and str_direct_free. It is
* useful when the eet_data you are reading come from a file and * useful when the eet_data you are reading come from a file and
* have a dictionnary. This will reduce memory use, improve the * have a dictionary. This will reduce memory use and improve the
* possibility for the OS to page this string out. But be carrefull * possibility for the OS to page this string out.
* all EET_T_STRING are pointer to a mmapped area and it will point * However, the load speed and memory saving comes with some drawbacks to k
* to nowhere if you close the file. So as long as you use this eep
* strings, you need to have the Eet_File open. * in mind. If you never modify the contents of the structures loaded from
* the file, all you need to remember is that closing the eet file will mak
e
* the strings go away. On the other hand, should you need to free a string
,
* before doing so you have to verify that it's not part of the eet diction
ary.
* You can do this in the following way, assuming @p ef is a valid Eet_File
* and @p str is a string loaded from said file.
*
* @code
* void eet_string_free(Eet_File *ef, const char *str)
* {
* Eet_Dictionary *dict = eet_dictionary_get(ef);
* if (dict && eet_dictionary_string_check(dict, str))
* {
* // The file contains a dictionary and the given string is a part
of
* // of it, so we can't free it, just return.
* return;
* }
* // We assume eina_stringshare was used on the descriptor
* eina_stringshare_del(str);
* }
* @endcode
* *
* @since 1.2.3 * @since 1.2.3
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI Eet_Data_Descriptor * EAPI Eet_Data_Descriptor *
eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc); eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc);
/** /**
* This function is an helper that set all the parameter of an * This function is an helper that set all the parameters of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type * Eet_Data_Descriptor_Class correctly when you use Eina data type
* with a stream. * with a stream.
* @param eddc The Eet_Data_Descriptor_Class you want to set. * @param eddc The Eet_Data_Descriptor_Class you want to set.
* @param name The name of the structure described by this class.
* @param eddc_size The size of the Eet_Data_Descriptor_Class at the compil ation time. * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compil ation time.
* @param name The name of the structure described by this class.
* @param size The size of the structure described by this class. * @param size The size of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only * @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong * reason that could make it fail is if you did give wrong
* parameter). * parameter).
* *
* @note Unless there's a very specific reason to use this function directl
y,
* the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
*
* @since 1.2.3 * @since 1.2.3
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI Eina_Bool EAPI Eina_Bool
eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
unsigned int eddc_si unsigned int eddc_size,
ze, const char *name,
const char *name, int size);
int size);
/** /**
* This macro is an helper that set all the parameter of an * This macro is an helper that set all the parameter of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type * Eet_Data_Descriptor_Class correctly when you use Eina data type
* with stream. * with stream.
* @param clas The Eet_Data_Descriptor_Class you want to set. * @param clas The Eet_Data_Descriptor_Class you want to set.
* @param type The type of the structure described by this class. * @param type The type of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only * @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong * reason that could make it fail is if you did give wrong
* parameter). * parameter).
* *
* @see eet_data_descriptor_stream_new
* @since 1.2.3 * @since 1.2.3
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type)\ #define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
(eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # typ (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type
e, sizeof(type))) , sizeof(type)))
/** /**
* This function is an helper that set all the parameter of an * This function is an helper that set all the parameter of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type * Eet_Data_Descriptor_Class correctly when you use Eina data type
* with a file. * with a file.
* @param eddc The Eet_Data_Descriptor_Class you want to set. * @param eddc The Eet_Data_Descriptor_Class you want to set.
* @param eddc_size The size of the Eet_Data_Descriptor_Class at the compil ation time. * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compil ation time.
* @param name The name of the structure described by this class. * @param name The name of the structure described by this class.
* @param size The size of the structure described by this class. * @param size The size of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only * @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong * reason that could make it fail is if you did give wrong
* parameter). * parameter).
* *
* @note Unless there's a very specific reason to use this function directl
y,
* the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended.
*
* @since 1.2.3 * @since 1.2.3
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI Eina_Bool EAPI Eina_Bool
eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc,
unsigned int eddc_siz unsigned int eddc_size,
e, const char *name,
const char *name, int size);
int size);
/** /**
* This macro is an helper that set all the parameter of an * This macro is an helper that set all the parameter of an
* Eet_Data_Descriptor_Class correctly when you use Eina data type * Eet_Data_Descriptor_Class correctly when you use Eina data type
* with file. * with file.
* @param clas The Eet_Data_Descriptor_Class you want to set. * @param clas The Eet_Data_Descriptor_Class you want to set.
* @param type The type of the structure described by this class. * @param type The type of the structure described by this class.
* @return EINA_TRUE if the structure was correctly set (The only * @return EINA_TRUE if the structure was correctly set (The only
* reason that could make it fail is if you did give wrong * reason that could make it fail is if you did give wrong
* parameter). * parameter).
* *
* @see eet_data_descriptor_file_new
* @since 1.2.3 * @since 1.2.3
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type)\ #define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) \
(eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type))) (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type)))
/** /**
* This function frees a data descriptor when it is not needed anymore. * This function frees a data descriptor when it is not needed anymore.
* @param edd The data descriptor to free. * @param edd The data descriptor to free.
* *
* This function takes a data descriptor handle as a parameter and frees al l * This function takes a data descriptor handle as a parameter and frees al l
* data allocated for the data descriptor and the handle itself. After this * data allocated for the data descriptor and the handle itself. After this
* call the descriptor is no longer valid. * call the descriptor is no longer valid.
* *
skipping to change at line 2083 skipping to change at line 2677
* @param offset byte offset inside the source memory to be serialized. * @param offset byte offset inside the source memory to be serialized.
* @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY). * @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY).
* @param counter_name variable that defines the name of number of elements . * @param counter_name variable that defines the name of number of elements .
* @param subtype If contains a subtype, then its data descriptor. * @param subtype If contains a subtype, then its data descriptor.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI void EAPI void
eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, eet_data_descriptor_element_add(Eet_Data_Descriptor *edd,
const char *name, const char *name,
int type, int type,
int group_type, int group_type,
int offset, int offset,
/* int count_offset, */ /* int count_offset, */
int count, int count,
const char *counter_name, const char *counter_name,
Eet_Data_Descriptor *subtype); Eet_Data_Descriptor *subtype);
/** /**
* Read a data structure from an eet file and decodes it. * Read a data structure from an eet file and decodes it.
* @param ef The eet file handle to read from. * @param ef The eet file handle to read from.
* @param edd The data descriptor handle to use when decoding. * @param edd The data descriptor handle to use when decoding.
* @param name The key the data is stored under in the eet file. * @param name The key the data is stored under in the eet file.
* @return A pointer to the decoded data structure. * @return A pointer to the decoded data structure.
* *
* This function decodes a data structure stored in an eet file, returning * This function decodes a data structure stored in an eet file, returning
skipping to change at line 2120 skipping to change at line 2714
* fields they wish to save or load, storing or retrieving a data structure * fields they wish to save or load, storing or retrieving a data structure
* from an eet file, or from a chunk of memory is as simple as a single * from an eet file, or from a chunk of memory is as simple as a single
* function call. * function call.
* *
* @see eet_data_read_cipher() * @see eet_data_read_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI void * EAPI void *
eet_data_read(Eet_File *ef, eet_data_read(Eet_File *ef,
Eet_Data_Descriptor *edd, Eet_Data_Descriptor *edd,
const char *name); const char *name);
/** /**
* Write a data structure from memory and store in an eet file. * Write a data structure from memory and store in an eet file.
* @param ef The eet file handle to write to. * @param ef The eet file handle to write to.
* @param edd The data descriptor to use when encoding. * @param edd The data descriptor to use when encoding.
* @param name The key to store the data under in the eet file. * @param name The key to store the data under in the eet file.
* @param data A pointer to the data structure to ssave and encode. * @param data A pointer to the data structure to ssave and encode.
* @param compress Compression flags for storage. * @param compress Compression flags for storage.
* @return bytes written on successful write, 0 on failure. * @return bytes written on successful write, 0 on failure.
* *
* This function is the reverse of eet_data_read(), saving a data structure * This function is the reverse of eet_data_read(), saving a data structure
* to an eet file. * to an eet file. The file must have been opening in write mode and the da
ta
* will be kept in memory until the file is either closed or eet_sync() is
* called to flush any unwritten changes.
* *
* @see eet_data_write_cipher() * @see eet_data_write_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI int EAPI int
eet_data_write(Eet_File *ef, eet_data_write(Eet_File *ef,
Eet_Data_Descriptor *edd, Eet_Data_Descriptor *edd,
const char *name, const char *name,
const void *data, const void *data,
int compress); int compress);
typedef void (*Eet_Dump_Callback)(void *data, const char *str); typedef void (*Eet_Dump_Callback)(void *data, const char *str);
/** /**
* Dump an eet encoded data structure into ascii text * Dump an eet encoded data structure into ascii text
* @param data_in The pointer to the data to decode into a struct. * @param data_in The pointer to the data to decode into a struct.
* @param size_in The size of the data pointed to in bytes. * @param size_in The size of the data pointed to in bytes.
* @param dumpfunc The function to call passed a string when new * @param dumpfunc The function to call passed a string when new
* data is converted to text * data is converted to text
* @param dumpdata The data to pass to the @p dumpfunc callback. * @param dumpdata The data to pass to the @p dumpfunc callback.
skipping to change at line 2198 skipping to change at line 2794
* eet_data_text_dump(data, len, output, NULL); * eet_data_text_dump(data, len, output, NULL);
* } * }
* @endcode * @endcode
* *
* @see eet_data_text_dump_cipher() * @see eet_data_text_dump_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI int EAPI int
eet_data_text_dump(const void *data_in, eet_data_text_dump(const void *data_in,
int size_in, int size_in,
Eet_Dump_Callback dumpfunc, Eet_Dump_Callback dumpfunc,
void *dumpdata); void *dumpdata);
/** /**
* Take an ascii encoding from eet_data_text_dump() and re-encode in binary . * Take an ascii encoding from eet_data_text_dump() and re-encode in binary .
* @param text The pointer to the string data to parse and encode. * @param text The pointer to the string data to parse and encode.
* @param textlen The size of the string in bytes (not including 0 * @param textlen The size of the string in bytes (not including 0
* byte terminator). * byte terminator).
* @param size_ret This gets filled in with the encoded data blob * @param size_ret This gets filled in with the encoded data blob
* size in bytes. * size in bytes.
* @return The encoded data on success, NULL on failure. * @return The encoded data on success, NULL on failure.
* *
skipping to change at line 2224 skipping to change at line 2820
* in-memory data struct and encodes into a binary blob. @p text is a norma l * in-memory data struct and encodes into a binary blob. @p text is a norma l
* C string. * C string.
* *
* @see eet_data_text_undump_cipher() * @see eet_data_text_undump_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI void * EAPI void *
eet_data_text_undump(const char *text, eet_data_text_undump(const char *text,
int textlen, int textlen,
int *size_ret); int *size_ret);
/** /**
* Dump an eet encoded data structure from an eet file into ascii text * Dump an eet encoded data structure from an eet file into ascii text
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param dumpfunc The function to call passed a string when new * @param dumpfunc The function to call passed a string when new
* data is converted to text * data is converted to text
* @param dumpdata The data to pass to the @p dumpfunc callback. * @param dumpdata The data to pass to the @p dumpfunc callback.
* @return 1 on success, 0 on failure * @return 1 on success, 0 on failure
* *
skipping to change at line 2251 skipping to change at line 2847
* generated. This callback should append to any existing text * generated. This callback should append to any existing text
* buffer and will be passed the pointer @p dumpdata as a parameter * buffer and will be passed the pointer @p dumpdata as a parameter
* as well as a string with new text to be appended. * as well as a string with new text to be appended.
* *
* @see eet_data_dump_cipher() * @see eet_data_dump_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI int EAPI int
eet_data_dump(Eet_File *ef, eet_data_dump(Eet_File *ef,
const char *name, const char *name,
Eet_Dump_Callback dumpfunc, Eet_Dump_Callback dumpfunc,
void *dumpdata); void *dumpdata);
/** /**
* Take an ascii encoding from eet_data_dump() and re-encode in binary. * Take an ascii encoding from eet_data_dump() and re-encode in binary.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param text The pointer to the string data to parse and encode. * @param text The pointer to the string data to parse and encode.
* @param textlen The size of the string in bytes (not including 0 * @param textlen The size of the string in bytes (not including 0
* byte terminator). * byte terminator).
* @param compress Compression flags (1 == compress, 0 = don't compress). * @param compress Compression flags (1 == compress, 0 = don't compress).
* @return 1 on success, 0 on failure * @return 1 on success, 0 on failure
skipping to change at line 2279 skipping to change at line 2875
* *
* The data (optionally compressed) will be in ram, pending a flush to * The data (optionally compressed) will be in ram, pending a flush to
* disk (it will stay in ram till the eet file handle is closed though). * disk (it will stay in ram till the eet file handle is closed though).
* *
* @see eet_data_undump_cipher() * @see eet_data_undump_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI int EAPI int
eet_data_undump(Eet_File *ef, eet_data_undump(Eet_File *ef,
const char *name, const char *name,
const char *text, const char *text,
int textlen, int textlen,
int compress); int compress);
/** /**
* Decode a data structure from an arbitrary location in memory. * Decode a data structure from an arbitrary location in memory.
* @param edd The data descriptor to use when decoding. * @param edd The data descriptor to use when decoding.
* @param data_in The pointer to the data to decode into a struct. * @param data_in The pointer to the data to decode into a struct.
* @param size_in The size of the data pointed to in bytes. * @param size_in The size of the data pointed to in bytes.
* @return NULL on failure, or a valid decoded struct pointer on success. * @return NULL on failure, or a valid decoded struct pointer on success.
* *
* This function will decode a data structure that has been encoded using * This function will decode a data structure that has been encoded using
* eet_data_descriptor_encode(), and return a data structure with all its * eet_data_descriptor_encode(), and return a data structure with all its
skipping to change at line 2314 skipping to change at line 2910
* *
* Please see eet_data_read() for more information. * Please see eet_data_read() for more information.
* *
* @see eet_data_descriptor_decode_cipher() * @see eet_data_descriptor_decode_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI void * EAPI void *
eet_data_descriptor_decode(Eet_Data_Descriptor *edd, eet_data_descriptor_decode(Eet_Data_Descriptor *edd,
const void *data_in, const void *data_in,
int size_in); int size_in);
/** /**
* Encode a dsata struct to memory and return that encoded data. * Encode a dsata struct to memory and return that encoded data.
* @param edd The data descriptor to use when encoding. * @param edd The data descriptor to use when encoding.
* @param data_in The pointer to the struct to encode into data. * @param data_in The pointer to the struct to encode into data.
* @param size_ret pointer to the an int to be filled with the decoded size . * @param size_ret pointer to the an int to be filled with the decoded size .
* @return NULL on failure, or a valid encoded data chunk on success. * @return NULL on failure, or a valid encoded data chunk on success.
* *
* This function takes a data structutre in memory and encodes it into a * This function takes a data structutre in memory and encodes it into a
* serialised chunk of data that can be decoded again by * serialised chunk of data that can be decoded again by
skipping to change at line 2348 skipping to change at line 2944
* *
* Please see eet_data_write() for more information. * Please see eet_data_write() for more information.
* *
* @see eet_data_descriptor_encode_cipher() * @see eet_data_descriptor_encode_cipher()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
EAPI void * EAPI void *
eet_data_descriptor_encode(Eet_Data_Descriptor *edd, eet_data_descriptor_encode(Eet_Data_Descriptor *edd,
const void *data_in, const void *data_in,
int *size_ret); int *size_ret);
/** /**
* Add a basic data element to a data descriptor. * Add a basic data element to a data descriptor.
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param type The type of the member to encode. * @param type The type of the member to encode.
* *
* This macro is a convenience macro provided to add a member to * This macro is a convenience macro provided to add a member to
* the data descriptor @p edd. The type of the structure is * the data descriptor @p edd. The type of the structure is
* provided as the @p struct_type parameter (for example: struct * provided as the @p struct_type parameter (for example: struct
* my_struct). The @p name parameter defines a string that will be * my_struct). The @p name parameter defines a string that will be
* used to uniquely name that member of the struct (it is suggested * used to uniquely name that member of the struct (it is suggested
* to use the struct member itself). The @p member parameter is * to use the struct member itself). The @p member parameter is
* the actual struct member itself (for eet_dictionary_string_check * the actual struct member itself (for example: values), and @p type is th
* example: values), and @p type is the basic data type of the e
* member which must be one of: EET_T_CHAR, EET_T_SHORT, EET_T_INT, * basic data type of the member which must be one of: EET_T_CHAR, EET_T_SH
* EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR, ORT,
* EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR,
* EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING. * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \ #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN, \ struct_type ___ett;
(char *)(& (___ett.member)) - \ \
(char *)(& (___ett)), \ eet_data_descriptor_element_add(edd, name, type, EET_G_UNKNOWN,
0, /* 0, */ NULL, NULL); \ \
} while(0) (char *)(& (___ett.member)) -
\
(char *)(& (___ett)),
\
0, /* 0, */ NULL, NULL);
\
} while(0)
/** /**
* Add a sub-element type to a data descriptor * Add a sub-element type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param subtype The type of sub-type struct to add. * @param subtype The type of sub-type struct to add.
* *
* This macro lets you easily add a sub-type (a struct that's pointed to * This macro lets you easily add a sub-type (a struct that's pointed to
* by this one). All the parameters are the same as for * by this one). All the parameters are the same as for
* EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception . * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception .
* This must be the data descriptor of the struct that is pointed to by * This must be the data descriptor of the struct that is pointed to by
* this element. * this element.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype
) \ ) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOW struct_type ___ett;
N, \ \
(char *)(& (___ett.member)) - \ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNO
(char *)(& (___ett)), \ WN, \
0, /* 0, */ NULL, subtype); \ (char *)(& (___ett.member)) -
} while (0) \
(char *)(& (___ett)),
\
0, /* 0, */ NULL, subtype);
\
} while (0)
/** /**
* Add a linked list type to a data descriptor * Add a linked list type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param subtype The type of linked list member to add. * @param subtype The type of linked list member to add.
* *
* This macro lets you easily add a linked list of other data types. All th e * This macro lets you easily add a linked list of other data types. All th e
* parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
* @p subtype being the exception. This must be the data descriptor of the * @p subtype being the exception. This must be the data descriptor of the
* element that is in each member of the linked list to be stored. * element that is in each member of the linked list to be stored.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtyp e) \ #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtyp e) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST, struct_type ___ett;
\ \
(char *)(& (___ett.member)) - \ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_LIST,
(char *)(& (___ett)), \ \
0, /* 0, */ NULL, subtype); \ (char *)(& (___ett.member)) -
} while (0) \
(char *)(& (___ett)),
\
0, /* 0, */ NULL, subtype);
\
} while (0)
/**
* Add a linked list of string to a data descriptor
* @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member
* (must be a constant global and never change).
* @param member The struct member itself to be encoded.
*
* This macro lets you easily add a linked list of char *. All the
* parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
*
* @since 1.5.0
* @ingroup Eet_Data_Group
*/
#define EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member)
\
do {
\
struct_type ___ett;
\
eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_LIST,
\
(char *)(& (___ett.member)) -
\
(char *)(& (___ett)),
\
0, /* 0, */ NULL, NULL);
\
} while (0)
/** /**
* Add a hash type to a data descriptor * Add a hash type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param subtype The type of hash member to add. * @param subtype The type of hash member to add.
* *
* This macro lets you easily add a hash of other data types. All the * This macro lets you easily add a hash of other data types. All the
* parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the
* @p subtype being the exception. This must be the data descriptor of the * @p subtype being the exception. This must be the data descriptor of the
* element that is in each member of the hash to be stored. * element that is in each member of the hash to be stored.
* The hash keys must be strings.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtyp e) \ #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtyp e) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH, struct_type ___ett;
\ \
(char *)(& (___ett.member)) - \ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_HASH,
(char *)(& (___ett)), \ \
0, /* 0, */ NULL, subtype); \ (char *)(& (___ett.member)) -
} while (0) \
(char *)(& (___ett)),
\
0, /* 0, */ NULL, subtype);
\
} while (0)
/** /**
* Add a hash of string to a data descriptor * Add a hash of string to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* *
* This macro lets you easily add a hash of string. All the * This macro lets you easily add a hash of string elements. All the
* parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH().
* *
* @since 1.3.4 * @since 1.3.4
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \ #define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH, struct_type ___ett;
\ \
(char *)(& (___ett.member)) - \ eet_data_descriptor_element_add(edd, name, EET_T_STRING, EET_G_HASH,
(char *)(& (___ett)), \ \
0, /* 0, */ NULL, NULL); \ (char *)(& (___ett.member)) -
} while (0) \
(char *)(& (___ett)),
\
0, /* 0, */ NULL, NULL);
\
} while (0)
/**
* Add an array of basic data elements to a data descriptor.
* @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member
* (must be a constant global and never change).
* @param member The struct member itself to be encoded.
* @param type The type of the member to encode.
*
* This macro lets you easily add a fixed size array of basic data
* types. All the parameters are the same as for
* EET_DATA_DESCRIPTOR_ADD_BASIC().
* The array must be defined with a fixed size in the declaration of the
* struct containing it.
*
* @since 1.5.0
* @ingroup Eet_Data_Group
*/
#define EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member,
type) \
do {
\
struct_type ___ett;
\
eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY,
\
(char *)(& (___ett.member)) -
\
(char *)(& (___ett)),
\
sizeof(___ett.member) /
\
sizeof(___ett.member[0]),
\
NULL, NULL);
\
} while(0)
/** /**
* Add a fixed size array type to a data descriptor * Add a fixed size array type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param subtype The type of hash member to add. * @param subtype The type of hash member to add.
* *
* This macro lets you easily add a fixed size array of other data * This macro lets you easily add a fixed size array of other data
* types. All the parameters are the same as for * types. All the parameters are the same as for
* EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
* exception. This must be the data descriptor of the element that * exception. This must be the data descriptor of the element that
* is in each member of the hash to be stored. * is in each member of the array to be stored.
* The array must be defined with a fixed size in the declaration of the
* struct containing it.
* *
* @since 1.0.2 * @since 1.0.2
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subty #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subty
pe) \ pe) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY, struct_type ___ett;
\ \
(char *)(& (___ett.member)) - \ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_ARRAY
(char *)(& (___ett)), \ , \
/* 0, */ sizeof(___ett.member) / \ (char *)(& (___ett.member)) -
sizeof(___ett.member[0]), NULL, subty \
pe); \ (char *)(& (___ett)),
} while (0) \
/* 0, */ sizeof(___ett.member) /
\
sizeof(___ett.member[0]), NULL, subt
ype); \
} while (0)
/** /**
* Add a variable size array type to a data descriptor * Add a variable size array type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param subtype The type of hash member to add. * @param subtype The type of hash member to add.
* *
* This macro lets you easily add a fixed size array of other data * This macro lets you easily add a variable size array of other data
* types. All the parameters are the same as for * types. All the parameters are the same as for
* EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the
* exception. This must be the data descriptor of the element that * exception. This must be the data descriptor of the element that
* is in each member of the hash to be stored. * is in each member of the array to be stored. This assumes you have
* a struct member (of type EET_T_INT) called member_count (note the
* _count appended to the member) that holds the number of items in
* the array. This array will be allocated separately to the struct it
* is in.
* *
* @since 1.0.2 * @since 1.0.2
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, s ubtype) \ #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, s ubtype) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, \ struct_type ___ett;
name, \ \
EET_T_UNKNOW, \ eet_data_descriptor_element_add(edd,
EET_G_VAR_ARRAY, \ \
(char *)(& (___ett.member)) - \ name,
(char *)(& (___ett)), \ \
(char *)(& (___ett.member ## _count)) EET_T_UNKNOW,
- \ \
(char *)(& (___ett)), \ EET_G_VAR_ARRAY,
/* 0, */ NULL, \ \
subtype); \ (char *)(& (___ett.member)) -
} while (0) \
(char *)(& (___ett)),
\
(char *)(& (___ett.member ## _count)
) - \
(char *)(& (___ett)),
\
/* 0, */ NULL,
\
subtype);
\
} while (0)
/** /**
* Add a variable size array type to a data descriptor * Add a variable size array type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* *
* This macro lets you easily add a fixed size array of string. All * This macro lets you easily add a variable size array of strings. All
* the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC().
* *
* @since 1.4.0 * @since 1.4.0
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
*/ */
#define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, me mber) \ #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, me mber) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, \ struct_type ___ett;
name, \ \
EET_T_STRING, \ eet_data_descriptor_element_add(edd,
EET_G_VAR_ARRAY, \ \
(char *)(& (___ett.member)) - \ name,
(char *)(& (___ett)), \ \
(char *)(& (___ett.member ## _count)) EET_T_STRING,
- \ \
(char *)(& (___ett)), \ EET_G_VAR_ARRAY,
/* 0, */ NULL, \ \
NULL); \ (char *)(& (___ett.member)) -
} while (0) \
(char *)(& (___ett)),
\
(char *)(& (___ett.member ## _count)
) - \
(char *)(& (___ett)),
\
/* 0, */ NULL,
\
NULL);
\
} while (0)
/** /**
* Add an union type to a data descriptor * Add an union type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param type_member The member that give hints on what is in the union. * @param type_member The member that give hints on what is in the union.
* @param unified_type Describe all possible type the union could handle. * @param unified_type Describe all possible type the union could handle.
skipping to change at line 2596 skipping to change at line 3250
* This macro lets you easily add an union with a member that specify what is inside. * This macro lets you easily add an union with a member that specify what is inside.
* The @p unified_type is an Eet_Data_Descriptor, but only the entry that m atch the name * The @p unified_type is an Eet_Data_Descriptor, but only the entry that m atch the name
* returned by type_get will be used for each serialized data. The type_get and type_set * returned by type_get will be used for each serialized data. The type_get and type_set
* callback of unified_type should be defined. * callback of unified_type should be defined.
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
* @see Eet_Data_Descriptor_Class * @see Eet_Data_Descriptor_Class
*/ */
#define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_ member, unified_type) \ #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_ member, unified_type) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION, struct_type ___ett;
\ \
(char *)(& (___ett.member)) - \ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNION
(char *)(& (___ett)), \ , \
(char *)(& (___ett.type_member)) - \ (char *)(& (___ett.member)) -
(char *)(& (___ett)), \ \
NULL, unified_type); \ (char *)(& (___ett)),
} while (0) \
(char *)(& (___ett.type_member)) -
\
(char *)(& (___ett)),
\
NULL, unified_type);
\
} while (0)
/** /**
* Add a automatically selectable type to a data descriptor * Add a automatically selectable type to a data descriptor
* @param edd The data descriptor to add the type to. * @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct. * @param struct_type The type of the struct.
* @param name The string name to use to encode/decode this member * @param name The string name to use to encode/decode this member
* (must be a constant global and never change). * (must be a constant global and never change).
* @param member The struct member itself to be encoded. * @param member The struct member itself to be encoded.
* @param type_member The member that give hints on what is in the union. * @param type_member The member that give hints on what is in the union.
* @param unified_type Describe all possible type the union could handle. * @param unified_type Describe all possible type the union could handle.
skipping to change at line 2628 skipping to change at line 3282
* be defined. If the the type is not know at the time of restoring it, eet will still call * be defined. If the the type is not know at the time of restoring it, eet will still call
* type_set of @p unified_type but the pointer will be set to a serialized binary representation * type_set of @p unified_type but the pointer will be set to a serialized binary representation
* of what eet know. This make it possible, to save this pointer again by j ust returning the string * of what eet know. This make it possible, to save this pointer again by j ust returning the string
* given previously and telling it by setting unknow to EINA_TRUE. * given previously and telling it by setting unknow to EINA_TRUE.
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
* @see Eet_Data_Descriptor_Class * @see Eet_Data_Descriptor_Class
*/ */
#define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, typ e_member, unified_type) \ #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, typ e_member, unified_type) \
do { \ do {
struct_type ___ett; \ \
eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIAN struct_type ___ett;
T, \ \
(char *)(& (___ett.member)) - \ eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_VARIA
(char *)(& (___ett)), \ NT, \
(char *)(& (___ett.type_member)) - \ (char *)(& (___ett.member)) -
(char *)(& (___ett)), \ \
NULL, unified_type); \ (char *)(& (___ett)),
} while (0) \
(char *)(& (___ett.type_member)) -
\
(char *)(& (___ett)),
\
NULL, unified_type);
\
} while (0)
/** /**
* Add a mapping to a data descriptor that will be used by union, variant o r inherited type * Add a mapping to a data descriptor that will be used by union, variant o r inherited type
* @param unified_type The data descriptor to add the mapping to. * @param unified_type The data descriptor to add the mapping to.
* @param name The string name to get/set type. * @param name The string name to get/set type.
* @param subtype The matching data descriptor. * @param subtype The matching data descriptor.
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
* @see Eet_Data_Descriptor_Class * @see Eet_Data_Descriptor_Class
*/ */
#define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \ #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \
eet_data_descriptor_element_add(unified_type, \ eet_data_descriptor_element_add(unified_type, \
name, \ name, \
EET_T_UNKNOW, \ EET_T_UNKNOW, \
EET_G_UNKNOWN, \ EET_G_UNKNOWN, \
0, \ 0, \
0, \ 0, \
NULL, \ NULL, \
subtype) subtype)
/** /**
* @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers * @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers
* *
* Most of the @ref Eet_Data_Group have alternative versions that * Most of the @ref Eet_Data_Group have alternative versions that
* accounts for ciphers to protect their content. * accounts for ciphers to protect their content.
* *
* @see @ref Eet_Cipher_Group * @see @ref Eet_Cipher_Group
* *
* @ingroup Eet_Data_Group * @ingroup Eet_Data_Group
skipping to change at line 2698 skipping to change at line 3352
* fields they wish to save or load, storing or retrieving a data structure * fields they wish to save or load, storing or retrieving a data structure
* from an eet file, or from a chunk of memory is as simple as a single * from an eet file, or from a chunk of memory is as simple as a single
* function call. * function call.
* *
* @see eet_data_read() * @see eet_data_read()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_data_read_cipher(Eet_File *ef, eet_data_read_cipher(Eet_File *ef,
Eet_Data_Descriptor *edd, Eet_Data_Descriptor *edd,
const char *name, const char *name,
const char *cipher_key); const char *cipher_key);
/**
* Read a data structure from an eet extended attribute and decodes it usin
g a cipher.
* @param filename The file to extract the extended attribute from.
* @param attribute The attribute to get the data from.
* @param edd The data descriptor handle to use when decoding.
* @param cipher_key The key to use as cipher.
* @return A pointer to the decoded data structure.
*
* This function decodes a data structure stored in an eet extended attribu
te,
* returning a pointer to it if it decoded successfully, or NULL on failure
.
* Eet can handle members being added or deleted from the data in
* storage and safely zero-fills unfilled members if they were not found
* in the data. It checks sizes and headers whenever it reads data, allowin
g
* the programmer to not worry about corrupt data.
*
* Once a data structure has been described by the programmer with the
* fields they wish to save or load, storing or retrieving a data structure
* from an eet file, from a chunk of memory or from an extended attribute
* is as simple as a single function call.
*
* @since 1.5.0
* @ingroup Eet_Data_Cipher_Group
*/
EAPI void *
eet_data_xattr_cipher_get(const char *filename,
const char *attribute,
Eet_Data_Descriptor *edd,
const char *cipher_key);
/** /**
* Write a data structure from memory and store in an eet file * Write a data structure from memory and store in an eet file
* using a cipher. * using a cipher.
* @param ef The eet file handle to write to. * @param ef The eet file handle to write to.
* @param edd The data descriptor to use when encoding. * @param edd The data descriptor to use when encoding.
* @param name The key to store the data under in the eet file. * @param name The key to store the data under in the eet file.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param data A pointer to the data structure to ssave and encode. * @param data A pointer to the data structure to ssave and encode.
* @param compress Compression flags for storage. * @param compress Compression flags for storage.
* @return bytes written on successful write, 0 on failure. * @return bytes written on successful write, 0 on failure.
* *
* This function is the reverse of eet_data_read(), saving a data structure * This function is the reverse of eet_data_read_cipher(), saving a data st ructure
* to an eet file. * to an eet file.
* *
* @see eet_data_write_cipher()
*
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_write_cipher(Eet_File *ef, eet_data_write_cipher(Eet_File *ef,
Eet_Data_Descriptor *edd, Eet_Data_Descriptor *edd,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
const void *data, const void *data,
int compress); int compress);
/**
* Write a data structure from memory and store in an eet extended attribut
e
* using a cipher.
* @param filename The file to write the extended attribute to.
* @param attribute The attribute to store the data to.
* @param edd The data descriptor to use when encoding.
* @param cipher_key The key to use as cipher.
* @param data A pointer to the data structure to ssave and encode.
* @param flags The policy to use when setting the data.
* @return EINA_TRUE on success, EINA_FALSE on failure.
*
* This function is the reverse of eet_data_xattr_cipher_get(), saving a da
ta structure
* to an eet extended attribute.
*
* @since 1.5.0
* @ingroup Eet_Data_Cipher_Group
*/
EAPI Eina_Bool
eet_data_xattr_cipher_set(const char *filename,
const char *attribute,
Eet_Data_Descriptor *edd,
const char *cipher_key,
const void *data,
Eina_Xattr_Flags flags);
/** /**
* Dump an eet encoded data structure into ascii text using a cipher. * Dump an eet encoded data structure into ascii text using a cipher.
* @param data_in The pointer to the data to decode into a struct. * @param data_in The pointer to the data to decode into a struct.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param size_in The size of the data pointed to in bytes. * @param size_in The size of the data pointed to in bytes.
* @param dumpfunc The function to call passed a string when new * @param dumpfunc The function to call passed a string when new
* data is converted to text * data is converted to text
* @param dumpdata The data to pass to the @p dumpfunc callback. * @param dumpdata The data to pass to the @p dumpfunc callback.
* @return 1 on success, 0 on failure * @return 1 on success, 0 on failure
skipping to change at line 2809 skipping to change at line 3515
* C string. * C string.
* *
* @see eet_data_text_undump() * @see eet_data_text_undump()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_data_text_undump_cipher(const char *text, eet_data_text_undump_cipher(const char *text,
const char *cipher_key, const char *cipher_key,
int textlen, int textlen,
int *size_ret); int *size_ret);
/** /**
* Dump an eet encoded data structure from an eet file into ascii * Dump an eet encoded data structure from an eet file into ascii
* text using a cipher. * text using a cipher.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param dumpfunc The function to call passed a string when new * @param dumpfunc The function to call passed a string when new
* data is converted to text * data is converted to text
* @param dumpdata The data to pass to the @p dumpfunc callback. * @param dumpdata The data to pass to the @p dumpfunc callback.
skipping to change at line 2838 skipping to change at line 3544
* generated. This callback should append to any existing text * generated. This callback should append to any existing text
* buffer and will be passed the pointer @p dumpdata as a parameter * buffer and will be passed the pointer @p dumpdata as a parameter
* as well as a string with new text to be appended. * as well as a string with new text to be appended.
* *
* @see eet_data_dump() * @see eet_data_dump()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_dump_cipher(Eet_File *ef, eet_data_dump_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
Eet_Dump_Callback dumpfunc, Eet_Dump_Callback dumpfunc,
void *dumpdata); void *dumpdata);
/** /**
* Take an ascii encoding from eet_data_dump() and re-encode in * Take an ascii encoding from eet_data_dump() and re-encode in
* binary using a cipher. * binary using a cipher.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @param name Name of the entry. eg: "/base/file_i_want". * @param name Name of the entry. eg: "/base/file_i_want".
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param text The pointer to the string data to parse and encode. * @param text The pointer to the string data to parse and encode.
* @param textlen The size of the string in bytes (not including 0 * @param textlen The size of the string in bytes (not including 0
* byte terminator). * byte terminator).
skipping to change at line 2869 skipping to change at line 3575
* *
* The data (optionally compressed) will be in ram, pending a flush to * The data (optionally compressed) will be in ram, pending a flush to
* disk (it will stay in ram till the eet file handle is closed though). * disk (it will stay in ram till the eet file handle is closed though).
* *
* @see eet_data_undump() * @see eet_data_undump()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI int EAPI int
eet_data_undump_cipher(Eet_File *ef, eet_data_undump_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
const char *text, const char *text,
int textlen, int textlen,
int compress); int compress);
/** /**
* Decode a data structure from an arbitrary location in memory * Decode a data structure from an arbitrary location in memory
* using a cipher. * using a cipher.
* @param edd The data descriptor to use when decoding. * @param edd The data descriptor to use when decoding.
* @param data_in The pointer to the data to decode into a struct. * @param data_in The pointer to the data to decode into a struct.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param size_in The size of the data pointed to in bytes. * @param size_in The size of the data pointed to in bytes.
* @return NULL on failure, or a valid decoded struct pointer on success. * @return NULL on failure, or a valid decoded struct pointer on success.
* *
skipping to change at line 2907 skipping to change at line 3613
* *
* Please see eet_data_read() for more information. * Please see eet_data_read() for more information.
* *
* @see eet_data_descriptor_decode() * @see eet_data_descriptor_decode()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd, eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd,
const void *data_in, const void *data_in,
const char *cipher_key, const char *cipher_key,
int size_in); int size_in);
/** /**
* Encode a data struct to memory and return that encoded data * Encode a data struct to memory and return that encoded data
* using a cipher. * using a cipher.
* @param edd The data descriptor to use when encoding. * @param edd The data descriptor to use when encoding.
* @param data_in The pointer to the struct to encode into data. * @param data_in The pointer to the struct to encode into data.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @param size_ret pointer to the an int to be filled with the decoded size . * @param size_ret pointer to the an int to be filled with the decoded size .
* @return NULL on failure, or a valid encoded data chunk on success. * @return NULL on failure, or a valid encoded data chunk on success.
* *
skipping to change at line 2944 skipping to change at line 3650
* *
* Please see eet_data_write() for more information. * Please see eet_data_write() for more information.
* *
* @see eet_data_descriptor_encode() * @see eet_data_descriptor_encode()
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI void * EAPI void *
eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd, eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd,
const void *data_in, const void *data_in,
const char *cipher_key, const char *cipher_key,
int *size_ret); int *size_ret);
/** /**
* @defgroup Eet_Node_Group Low-level Serialization Structures. * @defgroup Eet_Node_Group Low-level Serialization Structures.
* *
* Functions that create, destroy and manipulate serialization nodes * Functions that create, destroy and manipulate serialization nodes
* used by @ref Eet_Data_Group. * used by @ref Eet_Data_Group.
* *
* @{ * @{
*/ */
/** /**
* @typedef Eet_Node * @typedef Eet_Node
* Opaque handle to manage serialization node. * Opaque handle to manage serialization node.
*/ */
typedef struct _Eet_Node Eet_Node; typedef struct _Eet_Node Eet_Node;
/** /**
* @typedef Eet_Node_Data * @typedef Eet_Node_Data
* Contains an union that can fit any kind of node. * Contains an union that can fit any kind of node.
*/ */
typedef struct _Eet_Node_Data Eet_Node_Data; typedef struct _Eet_Node_Data Eet_Node_Data;
/** /**
* @struct _Eet_Node_Data * @struct _Eet_Node_Data
* Contains an union that can fit any kind of node. * Contains an union that can fit any kind of node.
*/ */
struct _Eet_Node_Data struct _Eet_Node_Data
{ {
union { union {
char c; char c;
short s; short s;
int i; int i;
long long l; long long l;
float f; float f;
double d; double d;
unsigned char uc; unsigned char uc;
unsigned short us; unsigned short us;
unsigned int ui; unsigned int ui;
unsigned long long ul; unsigned long long ul;
const char *str; const char *str;
} value; } value;
}; };
/** /**
* @} * @}
*/ */
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_char_new(const char *name, eet_node_char_new(const char *name,
char c); char c);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_short_new(const char *name, eet_node_short_new(const char *name,
short s); short s);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_int_new(const char *name, eet_node_int_new(const char *name,
int i); int i);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_long_long_new(const char *name, eet_node_long_long_new(const char *name,
long long l); long long l);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_float_new(const char *name, eet_node_float_new(const char *name,
float f); float f);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_double_new(const char *name, eet_node_double_new(const char *name,
double d); double d);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_unsigned_char_new(const char *name, eet_node_unsigned_char_new(const char *name,
unsigned char uc); unsigned char uc);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_unsigned_short_new(const char *name, eet_node_unsigned_short_new(const char *name,
unsigned short us); unsigned short us);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_unsigned_int_new(const char *name, eet_node_unsigned_int_new(const char *name,
unsigned int ui); unsigned int ui);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_unsigned_long_long_new(const char *name, eet_node_unsigned_long_long_new(const char *name,
unsigned long long l); unsigned long long l);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_string_new(const char *name, eet_node_string_new(const char *name,
const char *str); const char *str);
/** /**
skipping to change at line 3103 skipping to change at line 3809
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_null_new(const char *name); eet_node_null_new(const char *name);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_list_new(const char *name, eet_node_list_new(const char *name,
Eina_List *nodes); Eina_List *nodes);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_array_new(const char *name, eet_node_array_new(const char *name,
int count, int count,
Eina_List *nodes); Eina_List *nodes);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_var_array_new(const char *name, eet_node_var_array_new(const char *name,
Eina_List *nodes); Eina_List *nodes);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_hash_new(const char *name, eet_node_hash_new(const char *name,
const char *key, const char *key,
Eet_Node *node); Eet_Node *node);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_struct_new(const char *name, eet_node_struct_new(const char *name,
Eina_List *nodes); Eina_List *nodes);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_node_struct_child_new(const char *parent, eet_node_struct_child_new(const char *parent,
Eet_Node *child); Eet_Node *child);
/**
* @brief Get a node's child nodes
* @param node The node
* @return The first child node which contains a pointer to the
* next child node and the parent.
* @since 1.5
*/
EAPI Eet_Node *
eet_node_children_get(Eet_Node *node);
/**
* @brief Get the next node in a list of nodes
* @param node The node
* @return A node which contains a pointer to the
* next child node and the parent.
* @since 1.5
*/
EAPI Eet_Node *
eet_node_next_get(Eet_Node *node);
/**
* @brief Get the parent node of a node
* @param node The node
* @return The parent node of @p node
* @since 1.5
*/
EAPI Eet_Node *
eet_node_parent_get(Eet_Node *node);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI void EAPI void
eet_node_list_append(Eet_Node *parent, eet_node_list_append(Eet_Node *parent,
const char *name, const char *name,
Eet_Node *child); Eet_Node *child);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI void EAPI void
eet_node_struct_append(Eet_Node *parent, eet_node_struct_append(Eet_Node *parent,
const char *name, const char *name,
Eet_Node *child); Eet_Node *child);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI void EAPI void
eet_node_hash_add(Eet_Node *parent, eet_node_hash_add(Eet_Node *parent,
const char *name, const char *name,
const char *key, const char *key,
Eet_Node *child); Eet_Node *child);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI void EAPI void
eet_node_dump(Eet_Node *n, eet_node_dump(Eet_Node *n,
int dumplevel, int dumplevel,
Eet_Dump_Callback dumpfunc, Eet_Dump_Callback dumpfunc,
void *dumpdata); void *dumpdata);
/**
* @brief Return the type of a node
* @param node The node
* @return The node's type (EET_T_$TYPE)
* @since 1.5
*/
EAPI int
eet_node_type_get(Eet_Node *node);
/**
* @brief Return the node's data
* @param node The node
* @return The data contained in the node
* @since 1.5
*/
EAPI Eet_Node_Data *
eet_node_value_get(Eet_Node *node);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI void EAPI void
eet_node_del(Eet_Node *n); eet_node_del(Eet_Node *n);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI void * EAPI void *
eet_data_node_encode_cipher(Eet_Node *node, eet_data_node_encode_cipher(Eet_Node *node,
const char *cipher_key, const char *cipher_key,
int *size_ret); int *size_ret);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_data_node_decode_cipher(const void *data_in, eet_data_node_decode_cipher(const void *data_in,
const char *cipher_key, const char *cipher_key,
int size_in); int size_in);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI Eet_Node * EAPI Eet_Node *
eet_data_node_read_cipher(Eet_File *ef, eet_data_node_read_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key); const char *cipher_key);
/** /**
* TODO FIX ME * TODO FIX ME
* @ingroup Eet_Node_Group * @ingroup Eet_Node_Group
*/ */
EAPI int EAPI int
eet_data_node_write_cipher(Eet_File *ef, eet_data_node_write_cipher(Eet_File *ef,
const char *name, const char *name,
const char *cipher_key, const char *cipher_key,
Eet_Node *node, Eet_Node *node,
int compress); int compress);
/* EXPERIMENTAL: THIS API MAY CHANGE IN THE FUTURE, USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING. */ /* EXPERIMENTAL: THIS API MAY CHANGE IN THE FUTURE, USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING. */
/** /**
* @typedef Eet_Node_Walk * @typedef Eet_Node_Walk
* Describes how to walk trees of #Eet_Node. * Describes how to walk trees of #Eet_Node.
*/ */
typedef struct _Eet_Node_Walk Eet_Node_Walk; typedef struct _Eet_Node_Walk Eet_Node_Walk;
typedef void *(*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void typedef void * (*Eet_Node_Walk_Struct_Alloc_Callback)(const ch
*user_data); ar *type, void *user_data);
typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *pare
*name, void *child, void *user_data); nt, const char *name, void *child, void *user_data);
typedef void *(*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const cha typedef void * (*Eet_Node_Walk_Array_Callback)(Eina_Bool varia
r *name, int count, void *user_data); ble, const char *name, int count, void *user_data);
typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, i
*child, void *user_data); nt index, void *child, void *user_data);
typedef void *(*Eet_Node_Walk_List_Callback)(const char *name, void *user_d typedef void * (*Eet_Node_Walk_List_Callback)(const char *name
ata); , void *user_data);
typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, voi typedef void (*Eet_Node_Walk_Append_Callback)(void *list, vo
d *user_data); id *child, void *user_data);
typedef void *(*Eet_Node_Walk_Hash_Callback)(void *parent, const char *name typedef void * (*Eet_Node_Walk_Hash_Callback)(void *parent, co
, const char *key, void *value, void *user_data); nst char *name, const char *key, void *value, void *user_data);
typedef void *(*Eet_Node_Walk_Simple_Callback)(int type, Eet_Node_Data *dat typedef void * (*Eet_Node_Walk_Simple_Callback)(int type, Eet_
a, void *user_data); Node_Data *data, void *user_data);
/** /**
* @struct _Eet_Node_Walk * @struct _Eet_Node_Walk
* Describes how to walk trees of #Eet_Node. * Describes how to walk trees of #Eet_Node.
*/ */
struct _Eet_Node_Walk struct _Eet_Node_Walk
{ {
Eet_Node_Walk_Struct_Alloc_Callback struct_alloc; Eet_Node_Walk_Struct_Alloc_Callback struct_alloc;
Eet_Node_Walk_Struct_Add_Callback struct_add; Eet_Node_Walk_Struct_Add_Callback struct_add;
Eet_Node_Walk_Array_Callback array; Eet_Node_Walk_Array_Callback array;
Eet_Node_Walk_Insert_Callback insert; Eet_Node_Walk_Insert_Callback insert;
Eet_Node_Walk_List_Callback list; Eet_Node_Walk_List_Callback list;
Eet_Node_Walk_Append_Callback append; Eet_Node_Walk_Append_Callback append;
Eet_Node_Walk_Hash_Callback hash; Eet_Node_Walk_Hash_Callback hash;
Eet_Node_Walk_Simple_Callback simple; Eet_Node_Walk_Simple_Callback simple;
}; };
EAPI void * EAPI void *
eet_node_walk(void *parent, eet_node_walk(void *parent,
const char *name, const char *name,
Eet_Node *root, Eet_Node *root,
Eet_Node_Walk *cb, Eet_Node_Walk *cb,
void *user_data); void *user_data);
/*******/ /*******/
/** /**
* @defgroup Eet_Connection_Group Helper function to use eet over a network link * @defgroup Eet_Connection_Group Helper function to use eet over a network link
* *
* Function that reconstruct and prepare packet of @ref Eet_Data_Group to b e send. * Function that reconstruct and prepare packet of @ref Eet_Data_Group to b e send.
* *
*/ */
/** /**
* @typedef Eet_Connection * @typedef Eet_Connection
* Opaque handle to track paquet for a specific connection. * Opaque handle to track paquet for a specific connection.
* *
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
*/ */
typedef struct _Eet_Connection Eet_Connection; typedef struct _Eet_Connection Eet_Connection;
/** /**
* @typedef Eet_Read_Cb * @typedef Eet_Read_Cb
* Called back when an @ref Eet_Data_Group has been received completly and could be used. * Called back when an @ref Eet_Data_Group has been received completly and could be used.
* *
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
*/ */
typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *use r_data); typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *use r_data);
/** /**
skipping to change at line 3316 skipping to change at line 4069
* @param eet_write_cb Function to call when one Eet_Data packet is ready t o be send over the wire. * @param eet_write_cb Function to call when one Eet_Data packet is ready t o be send over the wire.
* @param user_data Pointer provided to both functions to be used as a cont ext handler. * @param user_data Pointer provided to both functions to be used as a cont ext handler.
* @return NULL on failure, or a valid Eet_Connection handler. * @return NULL on failure, or a valid Eet_Connection handler.
* *
* For every connection to track you will need a separate Eet_Connection pr ovider. * For every connection to track you will need a separate Eet_Connection pr ovider.
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
*/ */
EAPI Eet_Connection * EAPI Eet_Connection *
eet_connection_new(Eet_Read_Cb *eet_read_cb, eet_connection_new(Eet_Read_Cb *eet_read_cb,
Eet_Write_Cb *eet_write_cb, Eet_Write_Cb *eet_write_cb,
const void *user_data); const void *user_data);
/** /**
* Process a raw packet received over the link * Process a raw packet received over the link
* @param conn Connection handler to track. * @param conn Connection handler to track.
* @param data Raw data packet. * @param data Raw data packet.
* @param size The size of that packet. * @param size The size of that packet.
* @return 0 on complete success, any other value indicate where in the str eam it got wrong (It could be before that packet). * @return 0 on complete success, any other value indicate where in the str eam it got wrong (It could be before that packet).
* *
* Every time you receive a packet related to your connection, you should p ass * Every time you receive a packet related to your connection, you should p ass
* it to that function so that it could process and assemble packet has you * it to that function so that it could process and assemble packet has you
* receive it. It will automatically call Eet_Read_Cb when one is fully rec eived. * receive it. It will automatically call Eet_Read_Cb when one is fully rec eived.
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
*/ */
EAPI int EAPI int
eet_connection_received(Eet_Connection *conn, eet_connection_received(Eet_Connection *conn,
const void *data, const void *data,
size_t size); size_t size);
/** /**
* Convert a complex structure and prepare it to be send. * Convert a complex structure and prepare it to be send.
* @param conn Connection handler to track. * @param conn Connection handler to track.
* @param edd The data descriptor to use when encoding. * @param edd The data descriptor to use when encoding.
* @param data_in The pointer to the struct to encode into data. * @param data_in The pointer to the struct to encode into data.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @return EINA_TRUE if the data where correctly send, EINA_FALSE if they d on't. * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they d on't.
* *
* This function serialize data_in with edd, assemble the packet and call * This function serialize data_in with edd, assemble the packet and call
* Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allo cated * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allo cated
* and will vanish just after the return of the callback. * and will vanish just after the return of the callback.
* *
* @see eet_data_descriptor_encode_cipher * @see eet_data_descriptor_encode_cipher
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
*/ */
EAPI Eina_Bool EAPI Eina_Bool
eet_connection_send(Eet_Connection *conn, eet_connection_send(Eet_Connection *conn,
Eet_Data_Descriptor *edd, Eet_Data_Descriptor *edd,
const void *data_in, const void *data_in,
const char *cipher_key); const char *cipher_key);
/** /**
* Convert a Eet_Node tree and prepare it to be send. * Convert a Eet_Node tree and prepare it to be send.
* @param conn Connection handler to track. * @param conn Connection handler to track.
* @param node The data tree to use when encoding. * @param node The data tree to use when encoding.
* @param cipher_key The key to use as cipher. * @param cipher_key The key to use as cipher.
* @return EINA_TRUE if the data where correctly send, EINA_FALSE if they d on't. * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they d on't.
* *
* This function serialize node, assemble the packet and call * This function serialize node, assemble the packet and call
* Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allo cated * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allo cated
* and will vanish just after the return of the callback. * and will vanish just after the return of the callback.
* *
* @see eet_data_node_encode_cipher * @see eet_data_node_encode_cipher
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
*/ */
EAPI Eina_Bool EAPI Eina_Bool
eet_connection_node_send(Eet_Connection *conn, eet_connection_node_send(Eet_Connection *conn,
Eet_Node *node, Eet_Node *node,
const char *cipher_key); const char *cipher_key);
/** /**
* Close a connection and lost its track. * Close a connection and lost its track.
* @param conn Connection handler to close. * @param conn Connection handler to close.
* @param on_going Signal if a partial packet wasn't completed. * @param on_going Signal if a partial packet wasn't completed.
* @return the user_data passed to both callback. * @return the user_data passed to both callback.
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
*/ */
EAPI void * EAPI void *
eet_connection_close(Eet_Connection *conn, eet_connection_close(Eet_Connection *conn,
Eina_Bool *on_going); Eina_Bool *on_going);
/************************************************************************** */ /************************************************************************** */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif /* ifdef __cplusplus */ #endif /* ifdef __cplusplus */
#endif /* ifndef _EET_H */ #endif /* ifndef _EET_H */
 End of changes. 229 change blocks. 
821 lines changed or deleted 1811 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/