Eet.h   Eet.h 
/** /**
@brief Eet Data Handling Library Public API Calls @brief Eet Data Handling Library Public API Calls
These routines are used for Eet Library interaction These routines are used for Eet Library interaction
@mainpage Eet Library Documentation @mainpage Eet Library Documentation
@version 1.5.0 @version 1.5.0
@date 2000-2011 @date 2000-2012
Please see the @ref authors page for contact details. Please see the @ref authors page for contact details.
@section toc Table of Contents @section toc Table of Contents
@li @ref intro @li @ref intro
@li @ref example @li @ref example
@li @ref compiling @li @ref compiling
@li @ref install @li @ref install
@li @ref next_steps @li @ref next_steps
skipping to change at line 33 skipping to change at line 33
It is a tiny library designed to write an arbitrary set of chunks of dat a 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) 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 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 do zip as a zip itself has more complexity than is needed, and it was mu ch
simpler to implement this once here. simpler to implement this once here.
Eet is extremely fast, small and simple. Eet files can be very small and 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 highly compressed, making them very optimal for just sending across the
internet without having to archive, compress or decompress and install t hem. 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 They allow for lightning-fast random-access reads once created, making t hem
perfect for storing data that is written once (or rarely) and read many 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. 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 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 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 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 encoded in a platform independent way and can be written and read by any
architecture. architecture.
@section example A simple example on using Eet @section example A simple example on using Eet
skipping to change at line 190 skipping to change at line 190
/** /**
* @file Eet.h * @file Eet.h
* @brief The file that provides the eet functions. * @brief The file that provides the eet functions.
* *
* 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 6
/** /**
* @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
* runtime 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)
* { * {
* printf(" Built from SVN revision # %i\n", eet_version->revision); * printf(" Built from SVN revision # %i\n", eet_version->revision);
* } * }
* #endif * #endif
* @endcode * @endcode
* *
* Note the #if check can be dropped if your program refuses to compile or * Note the \#if check can be dropped if your program refuses to compile or
* work with an Eet version less than 1.3.0. * work with an Eet version less than 1.3.0.
*/ */
typedef struct _Eet_Version typedef struct _Eet_Version
{ {
int major; /** < major (binary or source incompatible changes) */ int major; /** < major (binary or source incompatible changes) */
int minor; /** < minor (new features, bugfixes, major improvements versi on) */ int minor; /** < minor (new features, bugfixes, major improvements versi on) */
int micro; /** < micro (bugfix, internal improvements, no new features v ersion) */ int micro; /** < micro (bugfix, internal improvements, no new features v ersion) */
int revision; /** < svn revision (0 if a proper rlease or the svn revsio n number Eet is built from) */ int revision; /** < svn revision (0 if a proper release or the svn revis ion number Eet is built from) */
} Eet_Version; } Eet_Version;
EAPI extern Eet_Version *eet_version; EAPI extern Eet_Version *eet_version;
/** /**
* @defgroup Eet_Group Top level functions * @defgroup Eet_Group Top level functions
* Functions that affect Eet as a whole. * Functions that affect Eet as a whole.
* *
* @{ * @{
*/ */
skipping to change at line 266 skipping to change at line 266
} Eet_Error; /**< Eet error identifiers */ } Eet_Error; /**< Eet error identifiers */
/** /**
* @} * @}
*/ */
/** /**
* Initialize the EET library. * Initialize the EET library.
* *
* The first time this function is called, it will perform all the internal * The first time this function is called, it will perform all the internal
* initialization required for the library to function properly and increme * initialization required for the library to function properly and increme
mnt nt
* the initializiation counter. Any subsequent call only increment this cou * the initialization counter. Any subsequent call only increment this coun
nter ter
* and return its new value, so it's safe to call this function more than o nce. * 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. * @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);
skipping to change at line 359 skipping to change at line 359
* into the file, compressed, returning the size of the data written into t he * into the file, compressed, returning the size of the data written into t he
* file. * file.
* This is all to show that Eet treats data as just data. It doesn't matter * 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 * 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 * 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. * in a buffer of 1024 bytes, but the returned size won't be any of those.
* @until printf * @until printf
* *
* Next, we copy into our buffer our set of strings, including their null * 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 * 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 * of brevity. 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. * properly written down to disk, even though we haven't yet closed the fil e.
* @until eet_sync * @until eet_sync
* *
* One more write, this time our large array of binary data and... well, I * 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, * 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(). * so let's take it out from the file with eet_delete().
* @until eet_delete * @until eet_delete
* *
* Finally, we close the file, saving any changes back to disk and return. * 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 , * Notice how, if there's any error closing the file or saving its contents ,
skipping to change at line 490 skipping to change at line 490
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 * This handle will be returned by the functions eet_open() and
* eet_memopen_read() and is used by every other function that affects the * 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 * file in any way. When you are done with it, call eet_close() to close it
* and, if the file was open for writing, write down to disk any changes ma de * and, if the file was open for writing, write down to disk any changes ma de
* to it. * 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;
/** /**
skipping to change at line 558 skipping to change at line 558
*/ */
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.
* @param data Address of file in memory.
* @param size Size of memory to be read.
* @return A handle to the file.
*
* Files opened this way will always be in read-only mode. * 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);
/** /**
skipping to change at line 579 skipping to change at line 583
* @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
eet_mode_get(Eet_File *ef); eet_mode_get(Eet_File *ef);
/** /**
* Close an eet file handle and flush and writes pending. * Close an eet file handle and flush pending writes.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @return An eet error identifier.
* *
* This function will flush any pending writes to disk if the eet file * This function will flush any pending writes to disk if the eet file
* was opened for write, and free all data associated with the file handle * was opened for write, and free all data associated with the file handle
* and file, and close the file. * and file, and close the file. If it was opened for read (or read/write),
* the file handle may still be held open internally for caching purposes.
* To flush speculatively held eet file handles use eet_clearcache().
* *
* If the eet file handle is not valid nothing will be done. * If the eet file handle is not valid nothing will be done.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*
* @see eet_clearcache()
*/ */
EAPI Eet_Error EAPI Eet_Error
eet_close(Eet_File *ef); eet_close(Eet_File *ef);
/** /**
* Sync content of an eet file handle, flushing pending writes. * Sync content of an eet file handle, flushing pending writes.
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @return An eet error identifier.
* *
* This function will flush any pending writes to disk. The eet file must * This function will flush any pending writes to disk. The eet file must
* be opened for write. * be opened for write.
* *
* If the eet file handle is not valid nothing will be done. * If the eet file handle is not valid nothing will be done.
* *
* @since 1.2.4 * @since 1.2.4
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI Eet_Error EAPI Eet_Error
skipping to change at line 620 skipping to change at line 630
* Return a handle to the shared string dictionary of the Eet file * Return a handle to the shared string dictionary of the Eet file
* @param ef A valid eet file handle. * @param ef A valid eet file handle.
* @return A handle to the dictionary of the file * @return A handle to the dictionary of the file
* *
* This function returns a handle to the dictionary of an Eet file whose * This function returns a handle to the dictionary of an Eet file whose
* handle is @p ef, if a dictionary exists. NULL is returned otherwise or * handle is @p ef, if a dictionary exists. NULL is returned otherwise or
* if the file handle is known to be invalid. * if the file handle is known to be invalid.
* *
* @see eet_dictionary_string_check() to know if given string came * @see eet_dictionary_string_check() to know if given string came
* from the dictionary or it was dynamically allocated using * from the dictionary or it was dynamically allocated using
* the #Eet_Data_Descriptor_Class instructrions. * the #Eet_Data_Descriptor_Class instructions.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
EAPI Eet_Dictionary * EAPI Eet_Dictionary *
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
skipping to change at line 647 skipping to change at line 657
* 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);
/** /**
* Return the number of strings inside a dictionary
* @param ed A valid dictionary handle
* @return the number of strings inside a dictionary
*
* @since 1.6.0
* @ingroup Eet_File_Group
*/
EAPI int
eet_dictionary_count(const Eet_Dictionary *ed);
/**
* 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.
* NULL is returned if the lookup fails or if memory errors are * NULL is returned if the lookup fails or if memory errors are
* encountered. It is the job of the calling program to call free() on * encountered. It is the job of the calling program to call free() on
skipping to change at line 683 skipping to change at line 704
/** /**
* 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.
* NULL is returned if the lookup fails or if memory errors are * NULL is returned if the lookup fails or if memory errors are
* encountered or if the data is comrpessed. The calling program must never * encountered or if the data is compressed. The calling program must never
* 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 *
skipping to change at line 757 skipping to change at line 778
* *
* @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 checks 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 new entry. eg: "/base/file_i_want". * @param name Name of the new entry. eg: "/base/file_i_want".
* @param destination Actual source of the aliased entry eg: "/base/the_rea l_stuff_i_want". * @param destination Actual source of the aliased entry eg: "/base/the_rea 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, otherwise EINA_FALSE will be retu rned. * Name and Destination must not be NULL, otherwise EINA_FALSE will be retu rned.
* The equivalent of this would be calling 'ln -s destination name' * 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 filename of an Eet_File
* @param ef A valid eet file handle opened for writing.
* @return The stringshared file string opened with eet_open(), or NULL on
error
*
* @note This function will return NULL for files opened with eet_memopen_r
ead()
*
* @since 1.6
* @ingroup Eet_File_Group
*/
EAPI const char *
eet_file_get(Eet_File *ef);
/**
* Retrieve the destination name of an alias * Retrieve the destination name of an alias
* @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 Destination of the alias. eg: "/base/the_real_stuff_i_want", NUL L on failure * @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. * Name must not be NULL, otherwise NULL will be returned.
* *
* @since 1.5 * @since 1.5
* @ingroup Eet_File_Group * @ingroup Eet_File_Group
*/ */
skipping to change at line 1765 skipping to change at line 1799
* *
* @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 resource 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
*/ */
EAPI void EAPI void
eet_identity_close(Eet_Key *key); eet_identity_close(Eet_Key *key);
skipping to change at line 1979 skipping to change at line 2013
* And now we need to read the data from the file and decode it using our * 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. * descriptor. Fortunately, that's all done in one single step.
* @until goto * @until goto
* *
* And that's it for all Eet cares about. But since we are dealing with a * 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 * 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 * 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. * use it to load older configuration files and update them as needed.
* @until } * @until }
* *
* Finally, clsoe the file and return the newly loaded config data. * Finally, close the file and return the newly loaded config data.
* @until } * @until }
* *
* Saving data is just as easy. The full version of the following function * 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 * 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 * to lose all your data in the case of a failure mid-writing. You can look
* at it @ref eet-data-simple.c "here". * at it @ref eet-data-simple.c "here".
* @skip static Eina_Bool * @skip static Eina_Bool
* @until { * @until {
* @skipline Eina_Bool ret * @skipline Eina_Bool ret
* @skip eet_open * @skip eet_open
skipping to change at line 2064 skipping to change at line 2098
* *
* And of course, Eet can do that, and considering the work it saves you as a * 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. * 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 * Let's begin with our example then, which is not all too different from t he
* simple one introduced earlier. * simple one introduced earlier.
* *
* We won't ignore the headers this time to show how easy it is to use Eina * 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 * 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 * 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". * by following @ref eet-data-nested.c "this link".
* *
* @dontinclude eet-data-nested.c * @dontinclude eet-data-nested.c
* @skipline Eina.h * @skipline Eina.h
* @skipline Eet.h * @skipline Eet.h
* @skip typedef struct * @skip typedef struct
* @until } My_Conf_Subtype * @until } My_Conf_Subtype
* *
* Extremely similar to our previous example. Just a new struct in there, a nd * 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 * 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 * is easy on our program, but now we'll see what Eet needs to work with th em
skipping to change at line 2379 skipping to change at line 2413
typedef const char * (*Eet_Descriptor_Type_Get_Callback) (const void *data, Eina_Bool *unknow); 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 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_Alloc_Callba ck)(size_t size);
typedef void (*Eet_Descriptor_Array_Free_Callbac k)(void *mem); 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.
* *
* The list and hash methods match the Eina API, so for a more detalied * The list and hash methods match the Eina API, so for a more detailed
* reference on them, look at the Eina_List and Eina_Hash documentation, * reference on them, look at the Eina_List and Eina_Hash documentation,
* respectively. * respectively.
* For the most part these will be used with the standard Eina functions, * For the most part these will be used with the standard Eina functions,
* so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and * so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and
* EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything
* accordingly. * accordingly.
*/ */
struct _Eet_Data_Descriptor_Class struct _Eet_Data_Descriptor_Class
{ {
int version; /**< ABI version. Should always be set to #EET_DAT A_DESCRIPTOR_CLASS_VERSION */ int version; /**< ABI version. Should always be set to #EET_DAT A_DESCRIPTOR_CLASS_VERSION */
skipping to change at line 2433 skipping to change at line 2467
* @param func_list_next The function to get the next list node. * @param func_list_next The function to get the next list node.
* @param func_list_append The function to append a member to a list. * @param func_list_append The function to append a member to a list.
* @param func_list_data The function to get the data from a list node. * @param func_list_data The function to get the data from a list node.
* @param func_list_free The function to free an entire linked list. * @param func_list_free The function to free an entire linked list.
* @param func_hash_foreach The function to iterate through all * @param func_hash_foreach The function to iterate through all
* hash table entries. * hash table entries.
* @param func_hash_add The function to add a member to a hash table. * @param func_hash_add The function to add a member to a hash table.
* @param func_hash_free The function to free an entire hash table. * @param func_hash_free The function to free an entire hash table.
* @return A new empty data descriptor. * @return A new empty data descriptor.
* *
* 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.
* *
* 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 * saved eet can load and save those members for you, encode them into
skipping to change at line 2482 skipping to change at line 2516
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 descriptor 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 class from where to create the data descriptor. * @param eddc The class from where to create the data descriptor.
* @return A handle to the new 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
* savedi, eet can load and save those members for you, encode them into * saved, 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. * network or more.
* *
* This function specially ignores 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 doesn't have a dictionary, * 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 ed * like network stream or IPC. It also mean that all string will be allocat 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 descriptor 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 class from where to create the data descriptor. * @param eddc The class from where to create the data descriptor.
* @return A handle to the new 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
* savedi, eet can load and save those members for you, encode them into * saved, 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 uses 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 dictionary. This will reduce memory use and improve the * have a dictionary. This will reduce memory use and improve the
* possibility for the OS to page this string out. * possibility for the OS to page this string out.
* However, the load speed and memory saving comes with some drawbacks to k eep * However, the load speed and memory saving comes with some drawbacks to k eep
* in mind. If you never modify the contents of the structures loaded from * 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 file, all you need to remember is that closing the eet file will mak e
skipping to change at line 2663 skipping to change at line 2699
* EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is
* complex to use by hand and should be left to be used by the macros, and * complex to use by hand and should be left to be used by the macros, and
* thus is not documented. * thus is not documented.
* *
* @param edd The data descriptor handle to add element (member). * @param edd The data descriptor handle to add element (member).
* @param name The name of element to be serialized. * @param name The name of element to be serialized.
* @param type The type of element to be serialized, like * @param type The type of element to be serialized, like
* #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a * #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a
* group, list or hash. * group, list or hash.
* @param group_type If element type is #EET_T_UNKNOW, then the @p * @param group_type If element type is #EET_T_UNKNOW, then the @p
* group_type will speficy if it is a list (#EET_G_LIST), * group_type will specify if it is a list (#EET_G_LIST),
* array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then * array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then
* the member is a subtype (pointer to another type defined by * the member is a subtype (pointer to another type defined by
* another #Eet_Data_Descriptor). * another #Eet_Data_Descriptor).
* @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
skipping to change at line 2723 skipping to change at line 2759
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 save 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. The file must have been opening in write mode and the da ta * 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 * will be kept in memory until the file is either closed or eet_sync() is
* called to flush any unwritten changes. * called to flush any unwritten changes.
* *
* @see eet_data_write_cipher() * @see eet_data_write_cipher()
* *
skipping to change at line 2924 skipping to change at line 2960
* 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
* eet_data_descriptor_decode(). This is useful for being able to transmit * eet_data_descriptor_decode(). This is useful for being able to transmit
* data structures across sockets, pipes, IPC or shared file mechanisms, * data structures across sockets, pipes, IPC or shared file mechanisms,
* without having to worry about memory space, machine type, endianess etc. * without having to worry about memory space, machine type, endianness etc .
* *
* The parameter @p edd must point to a valid data descriptor, and * The parameter @p edd must point to a valid data descriptor, and
* @p data_in must point to the right data structure to encode. If not, the * @p data_in must point to the right data structure to encode. If not, the
* encoding may fail. * encoding may fail.
* *
* On success a non NULL valid pointer is returned and what @p size_ret * On success a non NULL valid pointer is returned and what @p size_ret
* points to is set to the size of this decoded data, in bytes. When the * points to is set to the size of this decoded data, in bytes. When the
* encoded data is no longer needed, call free() on it. On failure NULL is * encoded data is no longer needed, call free() on it. On failure NULL is
* returned and what @p size_ret points to is set to 0. * returned and what @p size_ret points to is set to 0.
* *
skipping to change at line 3135 skipping to change at line 3171
struct_type ___ett; \ struct_type ___ett; \
eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY, \ eet_data_descriptor_element_add(edd, name, type, EET_G_ARRAY, \
(char *)(& (___ett.member)) - \ (char *)(& (___ett.member)) - \
(char *)(& (___ett)), \ (char *)(& (___ett)), \
sizeof(___ett.member) / \ sizeof(___ett.member) / \
sizeof(___ett.member[0]), \ sizeof(___ett.member[0]), \
NULL, NULL); \ NULL, NULL); \
} while(0) } while(0)
/** /**
* Add a variable 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 variable size array of basic data
* types. All the parameters are the same as for
* EET_DATA_DESCRIPTOR_ADD_BASIC(). 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.6.0
* @ingroup Eet_Data_Group
*/
#define EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, mem
ber, type) \
do {
\
struct_type ___ett;
\
eet_data_descriptor_element_add(edd, name, type, EET_G_VAR_ARRAY,
\
(char *)(& (___ett.member)) -
\
(char *)(& (___ett)),
\
(char *)(& (___ett.member ## _count)
) - \
(char *)(& (___ett)),
\
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
skipping to change at line 3393 skipping to change at line 3461
Eet_Data_Descriptor *edd, Eet_Data_Descriptor *edd,
const char *cipher_key); 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 save 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_cipher(), saving a data st ructure * This function is the reverse of eet_data_read_cipher(), saving a data st ructure
* to an eet file. * to an eet file.
* *
* @since 1.0.0 * @since 1.0.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI int EAPI int
skipping to change at line 3418 skipping to change at line 3486
const void *data, const void *data,
int compress); int compress);
/** /**
* Write a data structure from memory and store in an eet extended attribut e * Write a data structure from memory and store in an eet extended attribut e
* using a cipher. * using a cipher.
* @param filename The file to write the extended attribute to. * @param filename The file to write the extended attribute to.
* @param attribute The attribute to store the data to. * @param attribute The attribute to store the data to.
* @param edd The data descriptor to use when encoding. * @param edd The data descriptor to use when encoding.
* @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 save and encode.
* @param flags The policy to use when setting the data. * @param flags The policy to use when setting the data.
* @return EINA_TRUE on success, EINA_FALSE on failure. * @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 * This function is the reverse of eet_data_xattr_cipher_get(), saving a da ta structure
* to an eet extended attribute. * to an eet extended attribute.
* *
* @since 1.5.0 * @since 1.5.0
* @ingroup Eet_Data_Cipher_Group * @ingroup Eet_Data_Cipher_Group
*/ */
EAPI Eina_Bool EAPI Eina_Bool
skipping to change at line 4042 skipping to change at line 4110
/** /**
* @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 completely 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);
/** /**
* @typedef Eet_Write_Cb * @typedef Eet_Write_Cb
* Called back when a packet containing @ref Eet_Data_Group data is ready t o be send. * Called back when a packet containing @ref Eet_Data_Group data is ready t o be send.
* *
* @ingroup Eet_Connection_Group * @ingroup Eet_Connection_Group
 End of changes. 36 change blocks. 
30 lines changed or deleted 110 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/