<html>
<head>
<title>Eet: Eet Library Documentation</title>
<meta http-equiv="content-type" content="text/html;charset=UTF-8">
<meta name="author" content="Andres Blanc" >
<link rel="icon" href="img/favicon.png" type="image/x-icon">
<link rel="shortcut icon" href="img/favicon.png" type="image/x-icon">
<link rel="icon" href="img/favicon.png" type="image/ico">
<link rel="shortcut icon" href="img/favicon.png" type="image/ico">
<link rel="stylesheet" type="text/css" media="screen" href="e.css">
<link rel="stylesheet" type="text/css" media="screen" href="edoxy.css">
</head>
<body>
<div id="container">
<div id="header">
<div class="layout">
<h1><span>Enlightenment</span></h1>
<h2><span>Beauty at your fingertips</span></h2>
<div class="menu-container">
<div class="menu">
<ul>
<li class="current"><a href="http://web.enlightenment.org/p.php?p=docs">Docs</a></li>
<li><a href="http://trac.enlightenment.org/e">Tracker</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=contact">Contact</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=contribute">Contribute</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=support">Support</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=download">Download</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=about">About</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=news">News</a></li>
<li><a href="http://www.enlightenment.org/">Home</a></li>
</ul>
</div>
</div>
<div class="doxytitle">
Eet Documentation <small>at 2 Jul 2010</small>
</div>
<div class="menu-container">
<div class="submenu">
<ul class="current">
<li><a href="Examples.html">Examples</a></li>
<li><a href="files.html">Files</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="globals.html">Globals</a></li>
<li><a href="pages.html">Related Pages</a></li>
<li class="current"><a href="index.html">Main Page</a></li>
</ul>
</div>
</div>
<div class="clear"></div>
</div>
</div>
<div id="content">
<div class="layout">
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="contents">
<h1>Eet Library Documentation </h1><div align="center">
<img src="e_big.png" alt="e_big.png"/>
</div>
<dl class="version"><dt><b>Version:</b></dt><dd>1.3.2 </dd></dl>
<dl class="author"><dt><b>Author:</b></dt><dd>Carsten Haitzler <raster@rasterman.com> </dd>
<dd>
David Goodlad <dgoodlad@gmail.com> </dd>
<dd>
Cedric Bail <cedric.bail@free.fr> </dd>
<dd>
Arnaud de Turckheim <quarium@gmail.com> </dd>
<dd>
Luis Felipe Strano Moraes <lfelipe@profusion.mobi> </dd>
<dd>
Chidambar Zinnoury <illogict@online.fr> </dd>
<dd>
Vincent Torri <vtorri@univ-evry.fr> </dd>
<dd>
Gustavo Sverzut Barbieri <barbieri@profusion.mobi> </dd>
<dd>
Raphael Kubo da Costa <kubo@profusion.mobi> </dd>
<dd>
Mathieu Taillefumier <mathieu.taillefumier@free.fr> </dd>
<dd>
Albin "Lutin" Tonnerre <albin.tonnerre@gmail.com> </dd>
<dd>
Adam Simpkins <adam@adamsimpkins.net></dd></dl>
<dl class="date"><dt><b>Date:</b></dt><dd>2000-2010</dd></dl>
<h2><a class="anchor" id="toc">
Table of Contents</a></h2>
<ul>
<li><a class="el" href="index.html#intro">What is Eet?</a> </li>
<li><a class="el" href="index.html#example">A simple example on using Eet</a> </li>
<li><a class="el" href="index.html#format">What does an Eet file look like?</a> </li>
<li><a class="el" href="index.html#compiling">How to compile using Eet ?</a> </li>
<li><a class="el" href="index.html#install">How is it installed?</a> </li>
<li><a class="el" href="index.html#next_steps">Next Steps</a> </li>
<li><a class="el" href="index.html#intro_example">Introductory Examples</a></li>
</ul>
<h2><a class="anchor" id="intro">
What is Eet?</a></h2>
<p>It is a tiny library designed to write an arbitary set of chunks of data 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 much simpler to impliment this once here.</p>
<p>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 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.</p>
<p>It also can encode and decode data structures in memory, as well as image data for saving to Eet files or sending across the network to other machines, or just writing to arbitary files on the system. All data is encoded in a platform independant way and can be written and read by any architecture.</p>
<h2><a class="anchor" id="example">
A simple example on using Eet</a></h2>
<p>Here is a simple example on how to use Eet to save a series of strings to 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 special parsing to handle delimiter characters or escaping, they can be binary data, 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.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="Eet_8h.html" title="The file that provides the eet functions.">Eet.h</a>></span>
<span class="keywordtype">int</span>
main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> **argv)
{
<a class="code" href="group__Eet__File__Group.html#ga8d9779184a9870c1a225f1f40c76e8a7" title="Opaque handle that defines an Eet file (or memory).">Eet_File</a> *ef;
<span class="keywordtype">int</span> i;
<span class="keywordtype">char</span> buf[32];
<span class="keywordtype">char</span> *ret;
<span class="keywordtype">int</span> size;
<span class="keywordtype">char</span> *entries[] =
{
<span class="stringliteral">"Entry 1"</span>,
<span class="stringliteral">"Big text string here compared to others"</span>,
<span class="stringliteral">"Eet is cool"</span>
};
<a class="code" href="group__Eet__Group.html#ga9903687bfa20fe9a9e59d4c1d213e89a" title="Initialize the EET library.">eet_init</a>();
<span class="comment">// blindly open an file for output and write strings with their NUL char</span>
ef = <a class="code" href="group__Eet__File__Group.html#ga5f55956b860aa2c77af9b1a880c4c256" title="Open an eet file on disk, and returns a handle to it.">eet_open</a>(<span class="stringliteral">"test.eet"</span>, <a class="code" href="group__Eet__File__Group.html#ggaa8e1a7af50fefaf15eb2f69543d24998a8f395f56fba48be007c65be51d799ee9" title="File is write-only.">EET_FILE_MODE_WRITE</a>);
<a class="code" href="group__Eet__File__Group.html#ga682d04715f0e11380c460814c4a9bd21" title="Write a specified entry to an eet file handle.">eet_write</a>(ef, <span class="stringliteral">"Entry 1"</span>, entries[0], strlen(entries[0]) + 1, 0);
<a class="code" href="group__Eet__File__Group.html#ga682d04715f0e11380c460814c4a9bd21" title="Write a specified entry to an eet file handle.">eet_write</a>(ef, <span class="stringliteral">"Entry 2"</span>, entries[1], strlen(entries[1]) + 1, 1);
<a class="code" href="group__Eet__File__Group.html#ga682d04715f0e11380c460814c4a9bd21" title="Write a specified entry to an eet file handle.">eet_write</a>(ef, <span class="stringliteral">"Entry 3"</span>, entries[2], strlen(entries[2]) + 1, 0);
<a class="code" href="group__Eet__File__Group.html#ga1675fef1f6012c1e02ae313d13dc3e03" title="Close an eet file handle and flush and writes pending.">eet_close</a>(ef);
<span class="comment">// open the file again and blindly get the entries we wrote</span>
ef = <a class="code" href="group__Eet__File__Group.html#ga5f55956b860aa2c77af9b1a880c4c256" title="Open an eet file on disk, and returns a handle to it.">eet_open</a>(<span class="stringliteral">"test.eet"</span>, <a class="code" href="group__Eet__File__Group.html#ggaa8e1a7af50fefaf15eb2f69543d24998a416f7e9a76b8131a44bbeedb13060c81" title="File is read-only.">EET_FILE_MODE_READ</a>);
ret = <a class="code" href="group__Eet__File__Group.html#gac13cdf7782d1e513f5b1abcc529962f4" title="Read a specified entry from an eet file and return data.">eet_read</a>(ef, <span class="stringliteral">"Entry 1"</span>, &size);
printf(<span class="stringliteral">"%s\n"</span>, ret);
ret = <a class="code" href="group__Eet__File__Group.html#gac13cdf7782d1e513f5b1abcc529962f4" title="Read a specified entry from an eet file and return data.">eet_read</a>(ef, <span class="stringliteral">"Entry 2"</span>, &size);
printf(<span class="stringliteral">"%s\n"</span>, ret);
ret = <a class="code" href="group__Eet__File__Group.html#gac13cdf7782d1e513f5b1abcc529962f4" title="Read a specified entry from an eet file and return data.">eet_read</a>(ef, <span class="stringliteral">"Entry 3"</span>, &size);
printf(<span class="stringliteral">"%s\n"</span>, ret);
<a class="code" href="group__Eet__File__Group.html#ga1675fef1f6012c1e02ae313d13dc3e03" title="Close an eet file handle and flush and writes pending.">eet_close</a>(ef);
<a class="code" href="group__Eet__Group.html#gacbc7583179399d3b3e7b003e911f866f" title="Shut down the EET library.">eet_shutdown</a>();
}
</pre></div><h2><a class="anchor" id="format">
What does an Eet file look like?</a></h2>
<p>The file format is very simple. There is a directory block at the start of the file listing entries and offsets into the file where they are stored, their sizes, compression flags etc. followed by all the entry data strung one element after the other.</p>
<p>All Eet files start with t a 4 byte magic number. It is written using network byte-order (big endian, or from most significant byte first to least significant byte last) and is 0x1ee7ff00 (or byte by byte 0:1e 1:e7 2:ff 3:00). The next 4 bytes are an integer (in big endian notation) indicating how many entries are stored in the Eet file. 0 indicates it is empty. This is a signed integer and thus values less than 0 are invalid, limiting the number of entries in an Eet file to 0x7fffffff entries at most. The next 4 bytes is the size of the directory table, in bytes, encoded in big-endian format. This is a signed integer and cannot be less than 0.</p>
<p>The directory table for the file follows immediately, with a continuous list of all entries in the Eet file, their offset in the file etc. The order of these entries is not important, but convention would have them be from first to last entry in the file. Each directory entry consiste of 5 integers, one after the other, each stored as a signed, big endian integer. The first is the offset in the file that the data for this entry is stored at (based from the very start of the file, not relative to the end of the directory block). The second integer holds flags for the entry. currently only the least significant bit (bit 0) holds any useful information, and it is set to 1 if the entry is compressed using zlib compression calls, or 0 if it is not compressed. The next integer is the size of the entry in bytes stored in the file. The next integer is the size of the data when decompressed (if it was compressed) in bytes. This may be the same as the previous integer if the entry was not compressed. The final integer is the number of bytes used by the string identifier for the entry, without the NUL byte terminator, which is not stored. The next series of bytes is the string name of the entry, with the number of bytes being the same as specified in the last integer above. This list of entries continues until there are no more entries left to list. To read an entry from an Eet file, simply find the appropriate entry in the directory table, find it's offset and size, and read it into memory. If it is compressed, decompress it using zlib and then use that data.</p>
<p>Here is a data map of an Eet file. All integers are encoded using big-endian notation (most significant byte first) and are signed. There is no alignment of data, so all data types follow immediately on, one after the other. All compressed data is compressed using the zlib compress2() function, and decompressed using the zlib uncompress() function. Please see zlib documentation for more information as to the encoding of compressed data.</p>
<div class="fragment"><pre class="fragment">
HEADER:
[INT] Magic number (0x1ee7ff00)
[INT] Number of entries in the directory table
[INT] The size of the directory table, in bytes
DIRECTORY TABLE ENTRIES (as many as specified in the header):
[INT] Offest from file start at which entry is stored (in bytes)
[INT] Entry flags (1 = compressed, 0 = not compressed)
[INT] Size of data chunk in file (in bytes)
[INT] Size of the data chunk once decompressed (or the same as above, if not)
[INT] The length of the string itendifier, in bytes, without NUL terminator
[STR] Series of bytes for the string identifier, no NUL terminator
... more directory entries
DATA STORED, ONE AFTER ANOTHER:
[DAT] DATA ENTRY 1...
[DAT] DATA ENTRY 2...
[DAT] DATA ENTRY 3...
... more data chunks
</pre></div><p>The contents of each entry in an Eet file has no defined format as such. It is an opaque chunk of data, that is up to the application to deocde, unless it is an image, ecoded by Eet, or a data structure encoded by Eet. The data itself for these entries can be encoded and decoded by Eet with extra helper functions in Eet. <a class="el" href="group__Eet__File__Image__Group.html#ga986872ec682c29f842b2ef6dad810257" title="Read image data from the named key in the eet file.">eet_data_image_read()</a> and <a class="el" href="group__Eet__File__Image__Group.html#gab4e8a3419744fac22bca24af533f5051" title="Write image data to the named key in an eet file.">eet_data_image_write()</a> are used to handle reading and writing image data from a known Eet file entry name. <a class="el" href="group__Eet__Data__Group.html#ga4d1807cbbc448304f22a8808318a3429" title="Read a data structure from an eet file and decodes it.">eet_data_read()</a> and <a class="el" href="group__Eet__Data__Group.html#gac66d1c49e3490bc5d803982d833ff8aa" title="Write a data structure from memory and store in an eet file.">eet_data_write()</a> are used to decode and encode program data structures from an Eet file, making the loading and saving of program information stored in data structures a simple 1 function call process.</p>
<p>Please see src/lib/eet_data.c for information on the format of these specially encoded data entries in an Eet file (for now).</p>
<h2><a class="anchor" id="compiling">
How to compile using Eet ?</a></h2>
<p>Eet is a library your application links to. The procedure for this is very simple. You simply have to compile your application with the appropriate compiler flags that the <code>pkg-config</code> script outputs. For example:</p>
<p>Compiling C or C++ files into object files:</p>
<div class="fragment"><pre class="fragment">
gcc -c -o main.o main.c `pkg-config --cflags eet`
</pre></div><p>Linking object files into a binary executable:</p>
<div class="fragment"><pre class="fragment">
gcc -o my_application main.o `pkg-config --libs eet`
</pre></div><p>You simply have to make sure that pkg-config is in your shell's PATH (see the manual page for your appropriate shell) and eet.pc in /usr/lib/pkgconfig or its path is in the PKG_CONFIG_PATH environment variable. It's that simple to link and use Eet once you have written your code to use it.</p>
<p>Since the program is linked to Eet, it is now able to use any advertised API calls to serialize your data.</p>
<p>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 example is only guaranteed to make Eet add it's own requirements.</p>
<h2><a class="anchor" id="install">
How is it installed?</a></h2>
<p>Simple:</p>
<div class="fragment"><pre class="fragment">
./configure
make
su -
...
make install
</pre></div><h2><a class="anchor" id="next_steps">
Next Steps</a></h2>
<p>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 (<a href="http://docs.enlightenment.org/auto/eina/">http://docs.enlightenment.org/auto/eina/</a>) as it is very convenient and optimized, and Eet provides integration with it.</p>
<p>Recommended reading:</p>
<ul>
<li><a class="el" href="group__Eet__File__Group.html">Eet File Main Functions</a> to know the basics to open and save files. </li>
<li><a class="el" href="group__Eet__Data__Group.html">Eet Data Serialization</a> 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.</li>
</ul>
<h2><a class="anchor" id="intro_example">
Introductory Examples</a></h2>
<p>Examples</p>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000001">Todo:</a></b></dt><dd>Document data format for images and data structures.</dd></dl>
</div>
<div id="push"></div>
</div> <!-- #content -->
</div> <!-- .layout -->
</div> <!-- #container -->
<div id="footer">
<table><tr>
<td class="poweredby"><img src="doxygen.png"></td>
<td class="copyright">Copyright ©2010 Enlightenment</td>
<td class="generated">Docs generated Fri Jul 2 11:41:28 2010</td>
</tr></table>
</div>
</body>
</html>
