doc/eet.dox.in

   1 /**
   2 @file eet.c
   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 @image html  eet.png
  12 @version @PACKAGE_VERSION@
  13 @author Carsten Haitzler <raster\@rasterman.com>
  14 @date 2000-2008
  15
  16
  17
  18
  19
  20 @section intro What is Eet?
  21
  22 It is a tiny library designed to write an arbitary set of chunks of data
  23 to a file and optionally compress each chunk (very much like a zip file)
  24 and allow fast random-access reading of the file later on. It does not
  25 do zip as a zip itself has more complexity than is needed, and it was much
  26 simpler to impliment this once here.
  27
  28 Eet is extremely fast, small and simple. Eet files can be very small and
  29 highly compressed, making them very optimal for just sending across the
  30 internet without having to archive, compress or decompress and install them.
  31 They allow for lightning-fast random-acess reads once created, making them
  32 perfect for storing data that is written once (or rarely) and read many
  33 times, but the program does not want to have to read it all in at once.
  34
  35 It also can encode and decode data structures in memory, as well as image
  36 data for saving to Eet files or sending across the network to other
  37 machines, or just writing to arbitary files on the system. All data is
  38 encoded in a platform independant way and can be written and read by any
  39 architecture.
  40
  41
  42
  43
  44
  45 @section example A simple example on using Eet
  46
  47 Here is a simple example on how to use Eet to save a series of strings to a
  48 file and load them again. The advantage of using Eet over just fprintf() and
  49 fscanf() is that not only can these entries be strings, they need no special
  50 parsing to handle delimiter characters or escaping, they can be binary data,
  51 image data, data structures containing integers, strings, other data
  52 structures, linked lists and much more, without the programmer having to
  53 worry about parsing, and best of all, Eet is very fast.
  54
  55 @code
  56 #include <Eet.h>
  57
  58 int
  59 main(int argc, char **argv)
  60 {
  61   Eet_File *ef;
  62   int       i;
  63   char      buf[32];
  64   char     *ret;
  65   int       size;
  66   char    **entries =
  67     {
  68       "Entry 1",
  69       "Big text string here compared to others",
  70       "Eet is cool"
  71     };
  72
  73   eet_init();
  74
  75   // blindly open an file for output and write strings with their NUL char
  76   ef = eet_open("test.eet", EET_FILE_MODE_WRITE);
  77   eet_write(ef, "Entry 1", entries[0], strlen(entries[0]) + 1, 0);
  78   eet_write(ef, "Entry 2", entries[1], strlen(entries[1]) + 1, 1);
  79   eet_write(ef, "Entry 3", entries[2], strlen(entries[2]) + 1, 0);
  80   eet_close(ef);
  81
  82   // open the file again and blindly get the entries we wrote
  83   ef = eet_open("test.eet", EET_FILE_MODE_READ);
  84   ret = eet_read(ef, "Entry 1", &size);
  85   printf("%s\n", ret);
  86   ret = eet_read(ef, "Entry 2", &size);
  87   printf("%s\n", ret);
  88   ret = eet_read(ef, "Entry 3", &size);
  89   printf("%s\n", ret);
  90   eet_close(ef);
  91
  92   eet_shutdown();
  93 }
  94 @endcode
  95
  96
  97
  98
  99
 100 @section format What does an Eet file look like?
 101
 102 The file format is very simple. There is a directory block at the start of
 103 the file listing entries and offsets into the file where they are stored,
 104 their sizes, compression flags etc. followed by all the entry data strung one
 105 element after the other.
 106
 107 All Eet files start with t a 4 byte magic number. It is written using network
 108 byte-order (big endian, or from most significant byte first to least
 109 significant byte last) and is 0x1ee7ff00 (or byte by byte 0:1e 1:e7 2:ff
 110 3:00). The next 4 bytes are an integer (in big endian notation) indicating
 111 how many entries are stored in the Eet file. 0 indicates it is empty. This is
 112 a signed integer and thus values less than 0 are invalid, limiting the number
 113 of entries in an Eet file to 0x7fffffff entries at most. The next 4 bytes is
 114 the size of the directory table, in bytes, encoded in big-endian format. This
 115 is a signed integer and cannot be less than 0.
 116
 117 The directory table for the file follows immediately, with a continuous list
 118 of all entries in the Eet file, their offset in the file etc. The order of
 119 these entries is not important, but convention would have them be from first
 120 to last entry in the file. Each directory entry consiste of 5 integers, one
 121 after the other, each stored as a signed, big endian integer. The first is
 122 the offset in the file that the data for this entry is stored at (based from
 123 the very start of the file, not relative to the end of the directory block).
 124 The second integer holds flags for the entry. currently only the least
 125 significant bit (bit 0) holds any useful information, and it is set to 1 if
 126 the entry is compressed using zlib compression calls, or 0 if it is not
 127 compressed. The next integer is the size of the entry in bytes stored in the
 128 file. The next integer is the size of the data when decompressed (if it was
 129 compressed) in bytes. This may be the same as the previous integer if the
 130 entry was not compressed. The final integer is the number of bytes used by
 131 the string identifier for the entry, without the NUL byte terminator, which
 132 is not stored. The next series of bytes is the string name of the entry, with
 133 the number of bytes being the same as specified in the last integer above.
 134 This list of entries continues until there are no more entries left to list.
 135 To read an entry from an Eet file, simply find the appropriate entry in the
 136 directory table, find it's offset and size, and read it into memory. If it is
 137 compressed, decompress it using zlib and then use that data.
 138
 139 Here is a data map of an Eet file. All integers are encoded using big-endian
 140 notation (most significant byte first) and are signed. There is no alignment
 141 of data, so all data types follow immediately on, one after the other. All
 142 compressed data is compressed using the zlib compress2() function, and
 143 decompressed using the zlib uncompress() function. Please see zlib
 144 documentation for more information as to the encoding of compressed data.
 145
 146 @verbatim
 147 HEADER:
 148 [INT] Magic number (0x1ee7ff00)
 149 [INT] Number of entries in the directory table
 150 [INT] The size of the directory table, in bytes
 151
 152 DIRECTORY TABLE ENTRIES (as many as specified in the header):
 153 [INT] Offest from file start at which entry is stored (in bytes)
 154 [INT] Entry flags (1 = compressed, 0 = not compressed)
 155 [INT] Size of data chunk in file (in bytes)
 156 [INT] Size of the data chunk once decompressed (or the same as above, if not)
 157 [INT] The length of the string itendifier, in bytes, without NUL terminator
 158 [STR] Series of bytes for the string identifier, no NUL terminator
 159 ... more directory entries
 160
 161 DATA STORED, ONE AFTER ANOTHER:
 162 [DAT] DATA ENTRY 1...
 163 [DAT] DATA ENTRY 2...
 164 [DAT] DATA ENTRY 3...
 165 ... more data chunks
 166 @endverbatim
 167
 168 The contents of each entry in an Eet file has no defined format as such. It
 169 is an opaque chunk of data, that is up to the application to deocde, unless
 170 it is an image, ecoded by Eet, or a data structure encoded by Eet. The data
 171 itself for these entries can be encoded and decoded by Eet with extra helper
 172 functions in Eet. eet_data_image_read() and eet_data_image_write() are used
 173 to handle reading and writing image data from a known Eet file entry name.
 174 eet_data_read() and eet_data_write() are used to decode and encode program
 175 data structures from an Eet file, making the loading and saving of program
 176 information stored in data structures a simple 1 function call process.
 177
 178 Please see src/lib/eet_data.c for information on the format of these
 179 specially encoded data entries in an Eet file (for now).
 180
 181
 182
 183
 184
 185 @todo Add hash table, fixed and variable array encode/decode support.
 186 @todo Document data format for images and data structures.
 187
 188 */