summaryrefslogtreecommitdiff
path: root/Build/source/libs/zziplib/zziplib-src/docs/fseeko.htm
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/zziplib/zziplib-src/docs/fseeko.htm')
-rw-r--r--Build/source/libs/zziplib/zziplib-src/docs/fseeko.htm193
1 files changed, 0 insertions, 193 deletions
diff --git a/Build/source/libs/zziplib/zziplib-src/docs/fseeko.htm b/Build/source/libs/zziplib/zziplib-src/docs/fseeko.htm
deleted file mode 100644
index 89c3195e36d..00000000000
--- a/Build/source/libs/zziplib/zziplib-src/docs/fseeko.htm
+++ /dev/null
@@ -1,193 +0,0 @@
-<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>