@mainpage Eet Library Documentation
- @version 1.5.0
+ @version 1.6.0
@date 2000-2012
Please see the @ref authors page for contact details.
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 them.
- They allow for lightning-fast random-acess reads once created, making them
+ They allow for lightning-fast random-access reads once created, making them
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.
* #endif
* @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.
*/
typedef struct _Eet_Version
int major; /** < major (binary or source incompatible changes) */
int minor; /** < minor (new features, bugfixes, major improvements version) */
int micro; /** < micro (bugfix, internal improvements, no new features version) */
- int revision; /** < svn revision (0 if a proper rlease or the svn revsion number Eet is built from) */
+ int revision; /** < svn revision (0 if a proper release or the svn revision number Eet is built from) */
} Eet_Version;
EAPI extern Eet_Version *eet_version;
/**
* @}
*/
+
+/**
+ * @defgroup Eet_Compression Eet Compression Levels
+ * Compression modes/levels supported by Eet.
+ *
+ * @{
+ */
+
+/**
+ * @enum _Eet_Compression
+ * All the compression modes known by Eet.
+ */
+
+typedef enum _Eet_Compression
+{
+ EET_COMPRESSION_NONE = 0, /**< No compression at all @since 1.7 */
+ EET_COMPRESSION_DEFAULT = 1, /**< Default compression (Zlib) @since 1.7 */
+ EET_COMPRESSION_LOW = 2, /**< Fast but minimal compression (Zlib) @since 1.7 */
+ EET_COMPRESSION_MED = 6, /**< Medium compression level (Zlib) @since 1.7 */
+ EET_COMPRESSION_HI = 9, /**< Slow but high compression level (Zlib) @since 1.7 */
+ EET_COMPRESSION_VERYFAST = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */
+ EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST) (LZ4) @since 1.7 */
+
+ EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Don't use it @since 1.7 */
+ EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Don't use it @since 1.7 */
+ EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Don't use it @since 1.7 */
+ EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Don't use it @since 1.7 */
+ EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Don't use it @since 1.7 */
+} Eet_Compression; /**< Eet compression modes @since 1.7 */
+
+/**
+ * @}
+ */
/**
* Initialize the EET library.
*
* The first time this function is called, it will perform all the internal
- * initialization required for the library to function properly and incrememnt
- * the initializiation counter. Any subsequent call only increment this counter
+ * initialization required for the library to function properly and increment
+ * the initialization counter. Any subsequent call only increment this counter
* and return its new value, so it's safe to call this function more than once.
*
* @return The new init count. Will be 0 if initialization failed.
*
* 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
+ * 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 file.
* @until eet_sync
*
*
* 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
+ * 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 made
* to it.
*
* 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 time
* 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.
*
* @since 1.1.0
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.
+ * @return An eet error identifier.
*
* 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
- * 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.
*
* @since 1.0.0
* @ingroup Eet_File_Group
+ *
+ * @see eet_clearcache()
*/
EAPI Eet_Error
eet_close(Eet_File *ef);
/**
* Sync content of an eet file handle, flushing pending writes.
* @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
* be opened for write.
*
* @see eet_dictionary_string_check() to know if given string came
* 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
* @ingroup Eet_File_Group
* 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.
* 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
* data chunk are placed in size_ret.
*
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
* using it are also closed.
*
* use it to load older configuration files and update them as needed.
* @until }
*
- * Finally, clsoe the file and return the newly loaded config data.
+ * Finally, close the file and return the newly loaded config data.
* @until }
*
* Saving data is just as easy. The full version of the following function
* 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".
+ * by following @ref eet-data-nested.c "this link".
*
* @dontinclude eet-data-nested.c
* @skipline Eina.h
* Instructs Eet about memory management for different needs under
* 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,
* respectively.
* For the most part these will be used with the standard Eina functions,
* @param func_hash_free The function to free an entire hash table.
* @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 contents
* describing anything other than the shell of the data structure.
*
* new data descriptor. On creation it will be empty, containing no contents
* describing anything other than the shell of the data structure.
* @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
* EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
* adding to the description.
*
* 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
- * a network or more.
+ * network or more.
*
* 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,
* new data descriptor. On creation it will be empty, containing no contents
* describing anything other than the shell of the data structure.
* @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
* EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and
* adding to the description.
*
* 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
* a network or more.
*
* #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a
* group, list or hash.
* @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
* the member is a subtype (pointer to another type defined by
* another #Eet_Data_Descriptor).
* @param ef The eet file handle to write to.
* @param edd The data descriptor to use when encoding.
* @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.
* @return bytes written on successful write, 0 on failure.
*
* serialised chunk of data that can be decoded again by
* eet_data_descriptor_decode(). This is useful for being able to transmit
* 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
* @p data_in must point to the right data structure to encode. If not, the
} 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, member, 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
* @param edd The data descriptor to add the type to.
* @param struct_type The type of the struct.
* @param edd The data descriptor to use when encoding.
* @param name The key to store the data under in the eet file.
* @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.
* @return bytes written on successful write, 0 on failure.
*
* @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 data A pointer to the data structure to save and encode.
* @param flags The policy to use when setting the data.
* @return EINA_TRUE on success, EINA_FALSE on failure.
*
/**
* @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
*/
projects / framework / uifw / eet.git / blobdiff