doc/eet.dox.in

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