summaryrefslogtreecommitdiff
path: root/legacy/eet/doc
diff options
context:
space:
mode:
authorCarsten Haitzler <raster@rasterman.com>2011-04-08 06:21:40 +0000
committerCarsten Haitzler <raster@rasterman.com>2011-04-08 06:21:40 +0000
commitb504157045c8552cd7c894d8d9f4f526ab843238 (patch)
tree717e506ea7dc0e490867bcbe01c614c835064cdb /legacy/eet/doc
parent296739cd7d4b7cf1eca03bff9f304d94b8c4b44f (diff)
more of eet docs in .h - all of it minus examples actually.
SVN revision: 58475
Diffstat (limited to 'legacy/eet/doc')
-rw-r--r--legacy/eet/doc/eet.dox.in257
1 files changed, 0 insertions, 257 deletions
diff --git a/legacy/eet/doc/eet.dox.in b/legacy/eet/doc/eet.dox.in
index c44970760d..e69de29bb2 100644
--- a/legacy/eet/doc/eet.dox.in
+++ b/legacy/eet/doc/eet.dox.in
@@ -1,257 +0,0 @@
1/**
2@file eet.dox
3@brief Eet Data Handling Library Public API Calls
4
5These routines are used for Eet Library interaction
6*/
7
8/**
9
10@mainpage Eet Library Documentation
11
12@image html e_big.png
13
14@version @PACKAGE_VERSION@
15@author Carsten Haitzler <raster@@rasterman.com>
16@author David Goodlad <dgoodlad@@gmail.com>
17@author Cedric Bail <cedric.bail@@free.fr>
18@author Arnaud de Turckheim <quarium@@gmail.com>
19@author Luis Felipe Strano Moraes <lfelipe@@profusion.mobi>
20@author Chidambar Zinnoury <illogict@@online.fr>
21@author Vincent Torri <vtorri@@univ-evry.fr>
22@author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
23@author Raphael Kubo da Costa <kubo@@profusion.mobi>
24@author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
25@author Albin "Lutin" Tonnerre <albin.tonnerre@@gmail.com>
26@author Adam Simpkins <adam@@adamsimpkins.net>
27@date 2000-2011
28
29@section toc Table of Contents
30
31@li @ref intro
32@li @ref example
33@li @ref format
34@li @ref compiling
35@li @ref install
36@li @ref next_steps
37@li @ref intro_example
38
39@section intro What is Eet?
40
41It is a tiny library designed to write an arbitrary set of chunks of data
42to a file and optionally compress each chunk (very much like a zip file)
43and allow fast random-access reading of the file later on. It does not
44do zip as a zip itself has more complexity than is needed, and it was much
45simpler to implement this once here.
46
47Eet is extremely fast, small and simple. Eet files can be very small and
48highly compressed, making them very optimal for just sending across the
49internet without having to archive, compress or decompress and install them.
50They allow for lightning-fast random-acess reads once created, making them
51perfect for storing data that is written once (or rarely) and read many
52times, but the program does not want to have to read it all in at once.
53
54It also can encode and decode data structures in memory, as well as image
55data for saving to Eet files or sending across the network to other
56machines, or just writing to arbitrary files on the system. All data is
57encoded in a platform independent way and can be written and read by any
58architecture.
59
60@section example A simple example on using Eet
61
62Here is a simple example on how to use Eet to save a series of strings to a
63file and load them again. The advantage of using Eet over just fprintf() and
64fscanf() is that not only can these entries be strings, they need no special
65parsing to handle delimiter characters or escaping, they can be binary data,
66image data, data structures containing integers, strings, other data
67structures, linked lists and much more, without the programmer having to
68worry about parsing, and best of all, Eet is very fast.
69
70@code
71#include <Eet.h>
72
73int
74main(int argc, char **argv)
75{
76 Eet_File *ef;
77 int i;
78 char buf[32];
79 char *ret;
80 int size;
81 char *entries[] =
82 {
83 "Entry 1",
84 "Big text string here compared to others",
85 "Eet is cool"
86 };
87
88 eet_init();
89
90 // blindly open an file for output and write strings with their NUL char
91 ef = eet_open("test.eet", EET_FILE_MODE_WRITE);
92 eet_write(ef, "Entry 1", entries[0], strlen(entries[0]) + 1, 0);
93 eet_write(ef, "Entry 2", entries[1], strlen(entries[1]) + 1, 1);
94 eet_write(ef, "Entry 3", entries[2], strlen(entries[2]) + 1, 0);
95 eet_close(ef);
96
97 // open the file again and blindly get the entries we wrote
98 ef = eet_open("test.eet", EET_FILE_MODE_READ);
99 ret = eet_read(ef, "Entry 1", &size);
100 printf("%s\n", ret);
101 ret = eet_read(ef, "Entry 2", &size);
102 printf("%s\n", ret);
103 ret = eet_read(ef, "Entry 3", &size);
104 printf("%s\n", ret);
105 eet_close(ef);
106
107 eet_shutdown();
108}
109@endcode
110
111@section format What does an Eet file look like?
112
113The file format is very simple. There is a directory block at the start of
114the file listing entries and offsets into the file where they are stored,
115their sizes, compression flags etc. followed by all the entry data strung one
116element after the other.
117
118All Eet files start with t a 4 byte magic number. It is written using network
119byte-order (big endian, or from most significant byte first to least
120significant byte last) and is 0x1ee7ff00 (or byte by byte 0:1e 1:e7 2:ff
1213:00). The next 4 bytes are an integer (in big endian notation) indicating
122how many entries are stored in the Eet file. 0 indicates it is empty. This is
123a signed integer and thus values less than 0 are invalid, limiting the number
124of entries in an Eet file to 0x7fffffff entries at most. The next 4 bytes is
125the size of the directory table, in bytes, encoded in big-endian format. This
126is a signed integer and cannot be less than 0.
127
128The directory table for the file follows immediately, with a continuous list
129of all entries in the Eet file, their offset in the file etc. The order of
130these entries is not important, but convention would have them be from first
131to last entry in the file. Each directory entry consiste of 5 integers, one
132after the other, each stored as a signed, big endian integer. The first is
133the offset in the file that the data for this entry is stored at (based from
134the very start of the file, not relative to the end of the directory block).
135The second integer holds flags for the entry. currently only the least
136significant bit (bit 0) holds any useful information, and it is set to 1 if
137the entry is compressed using zlib compression calls, or 0 if it is not
138compressed. The next integer is the size of the entry in bytes stored in the
139file. The next integer is the size of the data when decompressed (if it was
140compressed) in bytes. This may be the same as the previous integer if the
141entry was not compressed. The final integer is the number of bytes used by
142the string identifier for the entry, without the NUL byte terminator, which
143is not stored. The next series of bytes is the string name of the entry, with
144the number of bytes being the same as specified in the last integer above.
145This list of entries continues until there are no more entries left to list.
146To read an entry from an Eet file, simply find the appropriate entry in the
147directory table, find it's offset and size, and read it into memory. If it is
148compressed, decompress it using zlib and then use that data.
149
150Here is a data map of an Eet file. All integers are encoded using big-endian
151notation (most significant byte first) and are signed. There is no alignment
152of data, so all data types follow immediately on, one after the other. All
153compressed data is compressed using the zlib compress2() function, and
154decompressed using the zlib uncompress() function. Please see zlib
155documentation for more information as to the encoding of compressed data.
156
157@verbatim
158HEADER:
159[INT] Magic number (0x1ee7ff00)
160[INT] Number of entries in the directory table
161[INT] The size of the directory table, in bytes
162
163DIRECTORY TABLE ENTRIES (as many as specified in the header):
164[INT] Offest from file start at which entry is stored (in bytes)
165[INT] Entry flags (1 = compressed, 0 = not compressed)
166[INT] Size of data chunk in file (in bytes)
167[INT] Size of the data chunk once decompressed (or the same as above, if not)
168[INT] The length of the string itendifier, in bytes, without NUL terminator
169[STR] Series of bytes for the string identifier, no NUL terminator
170... more directory entries
171
172DATA STORED, ONE AFTER ANOTHER:
173[DAT] DATA ENTRY 1...
174[DAT] DATA ENTRY 2...
175[DAT] DATA ENTRY 3...
176... more data chunks
177@endverbatim
178
179The contents of each entry in an Eet file has no defined format as such. It
180is an opaque chunk of data, that is up to the application to deocde, unless
181it is an image, ecoded by Eet, or a data structure encoded by Eet. The data
182itself for these entries can be encoded and decoded by Eet with extra helper
183functions in Eet. eet_data_image_read() and eet_data_image_write() are used
184to handle reading and writing image data from a known Eet file entry name.
185eet_data_read() and eet_data_write() are used to decode and encode program
186data structures from an Eet file, making the loading and saving of program
187information stored in data structures a simple 1 function call process.
188
189Please see src/lib/eet_data.c for information on the format of these
190specially encoded data entries in an Eet file (for now).
191
192
193@section compiling How to compile using Eet ?
194
195Eet is a library your application links to. The procedure for this is very
196simple. You simply have to compile your application with the appropriate
197compiler flags that the @p pkg-config script outputs. For example:
198
199Compiling C or C++ files into object files:
200
201@verbatim
202gcc -c -o main.o main.c `pkg-config --cflags eet`
203@endverbatim
204
205Linking object files into a binary executable:
206
207@verbatim
208gcc -o my_application main.o `pkg-config --libs eet`
209@endverbatim
210
211You simply have to make sure that pkg-config is in your shell's PATH (see
212the manual page for your appropriate shell) and eet.pc in /usr/lib/pkgconfig
213or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
214to link and use Eet once you have written your code to use it.
215
216Since the program is linked to Eet, it is now able to use any advertised
217API calls to serialize your data.
218
219You should make sure you add any extra compile and link flags to your
220compile commands that your application may need as well. The above example
221is only guaranteed to make Eet add it's own requirements.
222
223
224@section install How is it installed?
225
226Simple:
227
228@verbatim
229./configure
230make
231su -
232...
233make install
234@endverbatim
235
236@section next_steps Next Steps
237
238After you understood what Eet is and installed it in your system you
239should proceed understanding the programming interface. We'd recommend
240you to take a while to learn Eina
241(http://docs.enlightenment.org/auto/eina/) as it is very convenient
242and optimized, and Eet provides integration with it.
243
244Recommended reading:
245
246@li @ref Eet_File_Group to know the basics to open and save files.
247@li @ref Eet_Data_Group to know the convenient way to serialize and
248 parse your data structures automatically. Just create your
249 descriptors and let Eet do the work for you.
250
251@section intro_example Introductory Examples
252
253@ref Examples
254
255@todo Document data format for images and data structures.
256
257*/