PACKFILE *pack_fopen_chunk(PACKFILE *f, int pack);
DESCRIPTION
Opens a sub-chunk of a file. Chunks are primarily intended for use by the
datafile code, but they may also be useful for your own file routines. A
chunk provides a logical view of part of a file, which can be compressed
as an individual entity and will automatically insert and check length
counts to prevent reading past the end of the chunk. To write a chunk to
the file f, use the code:
/* assumes f is a PACKFILE * which has been opened */
f = pack_fopen_chunk(f, pack); /* in write mode */
write some data to f
f = pack_fclose_chunk(f);
The data written to the chunk will be prefixed with two length counts
(32-bit, a.k.a. big-endian). For uncompressed chunks these will both be
set to the size of the data in the chunk. For compressed chunks (created
by setting the pack flag), the first length will be the raw size of the
chunk, and the second will be the negative size of the uncompressed data.
To read the chunk, use the code:
/* assumes f is a PACKFILE * which has been opened */
f = pack_fopen_chunk(f, FALSE); */ in read mode */
read data from f
f = pack_fclose_chunk(f);
This sequence will read the length counts created when the chunk was
written, and automatically decompress the contents of the chunk if it
was compressed. The length will also be used to prevent reading past the
end of the chunk (Allegro will return EOF if you attempt this), and to
automatically skip past any unread chunk data when you call
pack_fclose_chunk().
Chunks can be nested inside each other by making repeated calls to
pack_fopen_chunk(). When writing a file, the compression status is
inherited from the parent file, so you only need to set the pack flag if
the parent is not compressed but you want to pack the chunk data. If the
parent file is already open in packed mode, setting the pack flag will
result in data being compressed twice: once as it is written to the
chunk, and again as the chunk passes it on to the parent file.
