summaryrefslogtreecommitdiff
path: root/Build/source/libs/zziplib/zziplib-0.13.62/docs/fseeko.htm
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/zziplib/zziplib-0.13.62/docs/fseeko.htm')
-rw-r--r--Build/source/libs/zziplib/zziplib-0.13.62/docs/fseeko.htm193
1 files changed, 193 insertions, 0 deletions
diff --git a/Build/source/libs/zziplib/zziplib-0.13.62/docs/fseeko.htm b/Build/source/libs/zziplib/zziplib-0.13.62/docs/fseeko.htm
new file mode 100644
index 00000000000..89c3195e36d
--- /dev/null
+++ b/Build/source/libs/zziplib/zziplib-0.13.62/docs/fseeko.htm
@@ -0,0 +1,193 @@
+<section> <date> 2005 </date>
+<H2> zzip/fseeko </H2> zip access for stdio handle
+
+<BLOCKQUOTE>
+ These routines are fully independent from the traditional zzip
+ implementation. They assume a readonly seekable stdio handle
+ representing a complete zip file. The functions show how to
+ parse the structure, find files and return a decoded bytestream.
+</BLOCKQUOTE>
+
+<section>
+<H3> stdio disk handle </H3>
+
+<P>
+ Other than with the <a href="mmapped.html">mmapped</a> alternative
+ interface there is no need to build special handle for the zip
+ disk file. The normal stdio file handle (of type <b><code>FILE</code></b>)
+ serves as the disk access representation. You can open that stdio file
+ handle any way you want. Note however that the <code>zzipfseeko</code>
+ routines modify the access state of that file handle, especially the
+ read position.
+</P>
+
+<P>
+ To get access to a zipped file, you need a zip archive entry known
+ under the type <code>ZZIP_ENTRY</code>. This is again modelled after
+ the <code>DIR_ENTRY</code> type in being a representation of a file
+ name inside the zip central directory. To get a fresh zzip entry, use
+ <code>zzip_entry_findfirst</code>, to get the next use
+ <code>zzip_entry_findnext</code>, and do not forget to free the
+ resource with <code>zzip_entry_free</code>.
+</P>
+<PRE>
+ extern ZZIP_ENTRY* zzip_entry_findfirst(FILE* disk);
+ extern ZZIP_ENTRY* zzip_entry_findnext(ZZIP_ENTRY* entry);
+ extern int zzip_entry_free(ZZIP_ENTRY* entry);
+</PRE>
+<P>
+ These three calls will allow to walk all zip archive members in the
+ order listed in the zip central directory. To actually implement a
+ directory lister ("zzipdir"), you need to get the name string of the
+ zzip entry. This is not just a pointer: the zzip disk entry is not
+ null terminated actually. Therefore we have a helper function that
+ will <code>strdup</code> the entry name as a normal C string:
+</P>
+<PRE>
+ #include &lt;zzip/fseeko.h&gt;
+ void _zzip_dir(FILE* disk)
+ {
+ for (ZZIP_ENTRY* entry = zzip_findfirst (disk);
+ entry ; entry = zzip_findnext (entry)) {
+ char* name = zzip_entry_strdup_name (entry);
+ puts (name); free (name);
+ }
+ }
+</PRE>
+
+</section><section>
+<H3> find a zipped file </H3>
+
+<P>
+ The central directory walk can be used to find any file in the
+ zip archive. The <code>zzipfseeko</code> library however provides
+ two convenience functions that allow to jump directly to the
+ zip disk entry of a given name or pattern. You are free to use
+ the newly allocated <code>ZZIP_ENTRY</code> for later calls on
+ that handle type. Do not forget to <code>zzip_entry_free</code>
+ the handle unless the handle is consumed by a routine, e.g.
+ <code>zzip_entry_findnext</code> to hit the end of directory.
+</P>
+<PRE>
+ extern ZZIP_ENTRY* zzip_entry_findfile(FILE* disk, char* filename,
+ ZZIP_ENTRY* _zzip_restrict entry,
+ zzip_strcmp_fn_t compare);
+
+ extern ZZIP_ENTRY* zzip_entry_findmatch(FILE* disk, char* filespec,
+ ZZIP_ENTRY* _zzip_restrict entry,
+ zzip_fnmatch_fn_t compare, int flags);
+</PRE>
+<P>
+ In general only the first two arguments are non-null pointing to the
+ stdio disk handle and the file name to look for. The "entry" argument
+ is an old value and allows you to walk the zip directory similar to
+ <code>zzip_entry_findnext</code> but actually leaping forward. The
+ compare function can be used for alternate match behavior: the default
+ of <code>strcmp</code> might be changed to <code>strncmp</code> for
+ a caseless match. The "flags" of the second call are forwarded to the
+ posix <code>fnmatch</code> which we use as the default function.
+</P>
+<P>
+ If you do know a specific filename then you can just use
+ <code>zzip_entry_findfile</code> and supply the return value to
+ <code>zzip_entry_fopen</code> with the second argument set to "1"
+ to tell the function to actually consume whichever entry was given.
+ That allows you to skip an explicit <code>zzip_entry_free</code>
+ as it is included in a later <code>zzip_entry_fclose</code>.
+</P>
+<PRE>
+ #include &lt;zzip/fseeko.h&gt;
+<small>
+ /* zzipfseeko already exports this convenience function: */</small>
+ ZZIP_ENTRY_FILE* zzip_entry_ffile(FILE* disk, char* filename) {
+ return zzip_entry_fopen (zzip_entry_findfile (filename, 0, 0), 1);
+ }
+
+ int _zzip_read(FILE* disk, char* filename, void* buffer, int bytes)
+ {
+ ZZIP_ENTRY_FILE* file = zzip_entry_ffile (disk, filename);
+ if (! file) return -1;
+ int bytes = zzip_entry_fread (buffer, 1, bytes, file);
+ zzip_entry_fclose (file);
+ return bytes;
+ }
+</PRE>
+
+</section><section>
+<H3> reading bytes </H3>
+
+<P>
+ The example has shown already how to read some bytes off the head of
+ a zipped file. In general the zzipfseeko api is used to replace a few
+ stdio routines that access a file. For that purpose we provide three
+ functions that look very similar to the stdio functions of
+ <code>fopen()</code>, <code>fread()</code> and <code>fclose()</code>.
+ These work on an active file descriptor of type <code>ZZIP_ENTRY_FILE</code>.
+ Note that this <code>zzip_entry_fopen()</code> uses <code>ZZIP_ENTRY</code>
+ argument as returned by the findfile api. To open a new reader handle from
+ a disk archive and file name you can use the <code>zzip_entry_ffile()</code>
+ convenience call.
+</P>
+
+<PRE>
+ ZZIP_ENTRY_FILE* zzip_entry_ffile (FILE* disk, char* filename);
+ ZZIP_ENTRY_FILE* zzip_entry_fopen (ZZIP_ENTRY* entry, int takeover);
+ zzip_size_t zzip_entry_fread (void* ptr,
+ zzip_size_t sized, zzip_size_t nmemb,
+ ZZIP_ENTRY_FILE* file);
+ int zzip_entry_fclose (ZZIP_ENTRY_FILE* file);
+ int zzip_entry_feof (ZZIP_ENTRY_FILE* file);
+</PRE>
+
+<P>
+ In all of the examples you need to remember that you provide a single
+ stdio <code>FILE</code> descriptor which is in reality a virtual
+ filesystem on its own. Per default filenames are matched case
+ sensitive also on win32 systems. The findnext function will walk all
+ files on the zip virtual filesystem table and return a name entry
+ with the full pathname, i.e. including any directory names to the
+ root of the zip disk <code>FILE</code>.
+</P>
+
+</section><section>
+<H3> ZZIP_ENTRY inspection </H3>
+
+<P>
+ The <code>ZZIP_ENTRY_FILE</code> is a special file descriptor handle
+ of the <code>zzipfseeko</code> library - but the <code>ZZIP_ENTRY</code>
+ is not so special. It is actually a bytewise copy of the data inside the
+ zip disk archive (plus some internal hints appended). While
+ <code>zzip/fseeko.h</code> will not reveal the structure on its own,
+ you can include <code>zzip/format.h</code> to get access to the actual
+ structure content of a <code>ZZIP_ENTRY</code> by (up)casting it to
+<br><b><code>&nbsp;&nbsp;&nbsp;&nbsp;struct zzip_disk_entry</code></b>.
+</P>
+
+<P>
+ In reality however it is not a good idea to actually read the bytes
+ in the <code>zzip_disk_entry</code> structure unless you seriously know
+ the internals of a zip archive entry. That includes any byteswapping
+ needed on bigendian platforms. Instead you want to take advantage of
+ helper macros defined in <code>zzip/fetch.h</code>. These will take
+ care to convert any struct data member to the host native format.
+</P>
+<PRE>
+extern uint16_t zzip_disk_entry_get_flags( zzip_disk_entry* entry);
+extern uint16_t zzip_disk_entry_get_compr( zzip_disk_entry* entry);
+extern uint32_t zzip_disk_entry_get_crc32( zzip_disk_entry* entry);
+
+extern zzip_size_t zzip_disk_entry_csize( zzip_disk_entry* entry);
+extern zzip_size_t zzip_disk_entry_usize( zzip_disk_entry* entry);
+extern zzip_size_t zzip_disk_entry_namlen( zzip_disk_entry* entry);
+extern zzip_size_t zzip_disk_entry_extras( zzip_disk_entry* entry);
+extern zzip_size_t zzip_disk_entry_comment( zzip_disk_entry* entry);
+extern int zzip_disk_entry_diskstart( zzip_disk_entry* entry);
+extern int zzip_disk_entry_filetype( zzip_disk_entry* entry);
+extern int zzip_disk_entry_filemode( zzip_disk_entry* entry);
+
+extern zzip_off_t zzip_disk_entry_fileoffset( zzip_disk_entry* entry);
+extern zzip_size_t zzip_disk_entry_sizeof_tail( zzip_disk_entry* entry);
+extern zzip_size_t zzip_disk_entry_sizeto_end( zzip_disk_entry* entry);
+extern char* zzip_disk_entry_skipto_end( zzip_disk_entry* entry);
+</PRE>
+</section></section>