|
ZLib
Introduction and Overview
The ZLib module provides a shared interface to the ZLib compression library. It provides a simple SWI interface, and a direct library replacement interface. The simple SWI interface looks the same as that for Squash and will act in a similar manner. The direct replacement interface provides a number of SWIs which may be accessed as is they were the original C routines.
To complement the SWI interface a C library is also provided as a set of veneer functions to allow the ZLib library to be called as if it had been statically linked.
The 'zlib' compression library provides lossless in-memory compression and decompression functions, including integrity checks of the uncompressed data. Compression can be done in a single step if the buffers are large enough, or can be done by repeated calls of the compression function. In the latter case the caller must provide more input and/or consume the output, providing more output space, before each call.
Terminology
ZLib (q.v. RFC 1950) is a standard, freely available library produced by Jean-loup Gailly and Mark Adler which provides compression based on the standard 'deflate' algorithm (q.v. RFC 1951). In addition, the ZLib library (and module) supports the GZip compression algorithm (q.v. RFC 1952) with extensions for RISC OS file information.
Technical Details
The ZLib module provides two primary interfaces for the programmer. The first of these is a Squash-like interface to the ZLib library. Applications which already support the use of Squash can be changed to use ZLib by simply changing the SWIs that are called.
The second interface that the module provides is that of a direct replacement for the ZLib C library. Because this is provided as a SWI interface this means that it is accessible to applications written in any language. At the present time the module uses ZLib 1.1.4 with backports for double-free fault.
Applications and modules
The ZLib module was originally intended to be used by application clients. Because of this it was decided that the streams should be discarded if the application terminated before closing the streams. This is the default behaviour of the module. However, if the ZLib module is used by other module clients (for example the Zipper module and the PNG module), it is desireable that the stream be entirely under the control of the module. It is therefore required for module clients to change the 'association' between the task and the stream to prevent this automatic closure from occurring. Consult the ZLib_TaskAssociate SWI for more details.
ZLib SWI interface
This SWIs that the module provides have equivalent (or similar) names to those of the C interface. A C interface library is provided to interact with the ZLib module such that it should not be necessary to use these calls directly from C.
Informational SWIs
The informational calls are not related to providing compression. These SWIs are the CRC32, Adler32 and Version SWIs.
GZip SWIs
The GZip calls provide GZip file compression. GZip files are compressed containers for a single file of data. GZip files contain additional information about the file they contain. This additional information is used to store RISC OS-specific file data such as the filetype, and datestamp.
ZLib SWIs
The ZLib calls provide deflate format data compression. Data compressed by the deflate algorithm is extractable by equivalent deflate decompressors. No additional data is included within the compressed data about its source. If further meta-data is required, it should be included in the output format in some application specific format. Zip files are one such example of a deflate format encapsulation.
Data formats
Stream Control Block
In order to function, a 'stream control block' must be provided to the ZLib SWIs. This control block is a private structure which can be manipulated by both the client and the ZLib module. Initially, the table should be set to 0 before being called (except where indicated).
+0 next_in Pointer to the next available input byte. This
value should be zero initially, and be updated by
both the client and the ZLib module as data is
processed.
+4 avail_in Amount of input data available for use by the ZLib
module. This value should be zero initially, and be
updated by both the client and the ZLib module as
data is processed.
+8 total_out Total number of bytes read so far.
+12 next_out Pointer to the next output byte. This value should
be zero initially, and be updated by both the
client and the ZLib module as data is processed.
+16 avail_out Amount of space in the output buffer for use by the
ZLib module. This value should be zero initially,
and be updated by both the client and the ZLib
module as data is processed.
+20 total_out Total number of bytes output so far.
+24 msg Pointer to the last error message, or 0 if no error
has been generated.
+28 state Private value, controlled by the ZLib module. The
client should not modify this value.
+32 zalloc Address of memory allocator function, or 0 for ZLib
to control memory allocation.
+36 zfree Address of memory free function, or 0 for ZLib to
control memory allocation.
+40 opaque Opaque handle to pass to allocator and free
functions.
+44 data_type ZLib module's guess of the type of the data :
Value Meaning
0 Binary
1 ASCII
2 Unknown
+48 adler Adler-32 value for uncompressed data processed so
far.
+52 reserved Reserved for future expansion. Must be zero.
Flush types
Where data is being written to a stream, a 'flush type' is provided to describe what sort of operations should be performed on writing the data. Flushing may degrade compression for some compression algorithms and so it should be used only when necessary.
Type Name Meaning
0 Z_NO_FLUSH Do not flush data, but just write data as
normal to the output buffer. This is the normal
way in which data is written to the output
buffer.
1 Z_PARTIAL_FLUSH Obsolete. You should use Z_SYNC_FLUSH instead.
2 Z_SYNC_FLUSH All pending output is flushed to the output
buffer and the output is aligned on a byte
boundary, so that the decompressor can get all
input data available so far.
3 Z_FULL_FLUSH All output is flushed as with Z_SYNC_FLUSH, and
the compression state is reset so that
decompression can restart from this point if
previous compressed data has been damaged or if
random access is desired. Using Z_FULL_FLUSH
too often can seriously degrade the
compression. ZLib_InflateSync will locate
points in the compression string where a full
has been performed.
4 Z_FINISH Notifies the module that the input has now been
exhausted. Pending input is processed, pending
output is flushed and calls return with
Z_STREAM_END if there was enough output space.
Compression levels
For compression calls, the compression level can be specified. This determines how much work is performed on trying to compress the input data. Lower compression levels indicate lesser compression, and greater speed. Higher levels indicate greater compression, but lesser speed.
Level Name Meaning
0 Z_NO_COMPRESSION No compression should be used at all.
1 Z_BEST_SPEED Minimal compression, but greatest speed.
9 Z_BEST_COMPRESSION Maximum compression, but slowest.
-1 Z_DEFAULT_COMPRESSION Select default compression level.
Compression strategy
For compression calls, the compression strategy can be specified. This determines what type of processing is performed on the input data. If set incorrectly, the compression strategy will produce lesser compression ratios, but does not affect the correctness of the data.
Strategy Name Meaning
0 Z_DEFAULT_STRATEGY The default strategy is the most
commonly used. With this strategy,
string matching and huffman compression
are balanced.
1 Z_FILTERED This strategy is designed for filtered
data. Data which consists of mostly
small values, with random distribution
should use Z_FILTERED. With this
strategy, less string matching is
performed.
2 Z_HUFFMAN_ONLY This strategy performs no string
matching, only the huffman encoding is
performed.
The compression method determines what algorithm is used to perform the compression. Presently only Z_DEFLATED is supported.
Method Name Meaning
8 Z_DEFLATED Use deflate algorithm
Memory level
The memory level determines how much memory should be allocated for the internal compression state. The default value is 8.
Level Meaning
1 Uses minimal memory, but is slow and reduces the compression ratio.
9 Uses maximum memory for optimal speed.
Window bits
Whilst searching for matching strings in the input data, a 'window' is used on to the previous data. This window is used to determine where matches occur. The value of the 'window bits' parameter is the base two logarithm of the size of the window. It should be in the range 9 to 15 for this version of the library. Larger values result in better compression at the expense of memory usage.
ZLib return code
Most ZLib SWIs return a 'return code'. This declares the state that the SWI encountered during the operation.
Code Name Meaning
0 Z_OK No failure was encountered, the operation
completed without problem.
1 Z_STREAM_END No failure was encountered, and the input has
been exhausted.
2 Z_NEED_DICT A preset dictionary is required for the
decompression of the data.
-1 Z_ERRNO An internal error occurred
-2 Z_STREAM_ERROR The stream structure was inconsistent
-3 Z_DATA_ERROR Input data has been corrupted (for
decompression).
-4 Z_MEM_ERROR Memory allocation failed.
-5 Z_BUF_ERROR There was not enough space in the output
buffer.
-6 Z_VERSION_ERROR The version supplied does not match that
supported by the ZLib module.
SWI calls
ZLib_Compress (SWI &53AC0)
Simple Squash-like compression
On entry
R0 = Flags :
bit 0 = Continue previously started operation
bit 1 = More input remains after this call
bit 2 = Reserved, must be 0
bit 3 = Return workspace required
bit 4= Workspace is not bound to an application
bits 5-10 Reserved, must be 0
R1-R5 = dependent on flags
On exit
R0-R5 = dependent on flags
This SWI is similar to Squash_Compress, providing a drop in replacement for the Squash module but using ZLib compression. There are two variants of this SWI - with bit 3 set, and with bit 3 clear. Normally, this call will be made first with bit 3 set to read the workspace size, and then with bit 3 clear to perform the decompression.
ZLib_Compress bit 3 set (SWI &53AC0)
Simple Squash-like compression
On entry
R0 = Flags :
bit 3 = Return workspace required
R1 = input size, or -1 to omit maximum output size
On exit
R0 = required workspace size
R1 = maximum output size, or -1 if it cannot be determined or was not asked for
This SWI is used to read the size of the buffers to use for ZLib compression via the Squash-like interface.
ZLib_Compress bit 3 clear (SWI &53AC0)
Simple Squash-like compression
On entry
R0 = Flags :
bit 0 = Continue previously started operation
bit 1 = More input remains after this call
bit 3 = Return workspace required
bit 4 = Workspace is not bound to an application
R1 = pointer to workspace
R2 = pointer to input data
R3 = length of input data
R4 = pointer to output buffer
R5 = length of output buffer
On exit
R0 = status of decompression process :
0 = Operation is complete
1 = Input has been exhausted
2 = Output space has been exhausted
R1 preserved
R2 = pointer to first unused byte of input data
R3 = size of unused data in input buffer
R4 = pointer to first unused byte of output buffer
R5 = size of unused data in output buffer
This SWI is used to compress data to a buffer.
ZLib_Decompress (SWI &53AC1)
Simple Squash-like decompression
On entry
R0 = Flags :
bit 0 = Continue previously started operation
bit 1 = More input remains after this call
bit 2 = Assume all output will fit into the buffer
bit 3 = Return workspace required
bit 4 = Workspace is not bound to an application
bits 5-10 Reserved, must be 0
R1-R5 = dependent on flags
On exit
R0-R5 = dependent on flags
This SWI is similar to Squash_Compress, providing a drop in replacement for the Squash module but using ZLib decompression. There are two variants of this SWI - with bit 3 set, and with bit 3 clear. Normally, this call will be made first with bit 3 set to read the workspace size and then with bit 3 clear to perform the decompression.
ZLib_Decompress bit 3 set (SWI &53AC1)
Simple Squash-like decompression
On entry
R0 = Flags :
bit 3 = Return workspace required
R1 = input size, or -1 to omit maximum output size
On exit
R0 = required workspace size
R1 = maximum output size, or -1 if it cannot be determined or was not asked for
This SWI is used to read the size of the buffers to use for ZLib decompression via the Squash-like interface.
ZLib_Decompress bit 3 clear (SWI &53AC1)
Simple Squash-like decompression
On entry
R0 = Flags :
bit 0 = Continue previously started operation
bit 1 = More input remains after this call
bit 3 = Return workspace required
bit 4 = Workspace is not bound to an application
R1 = pointer to workspace
R2 = pointer to input data
R3 = length of input data
R4 = pointer to output buffer
R5 = length of output buffer
On exit
R0 = status of decompression process :
0 = Operation is complete
1 = Input has been exhausted
2 = Output space has been exhausted
R1 preserved
R2 = pointer to first unused byte of input data
R3 = size of unused data in input buffer
R4 = pointer to first unused byte of output buffer
R5 = size of unused data in output buffer
This SWI is used to decompress data from a buffer.
ZLib_CRC32 (SWI &53AC2)
Calculate a CRC32 checksum for a given data buffer (crc32)
On entry
R0 = CRC-32 continuation value
R1 = pointer to start of block, or 0 to read the initial value to supply as a continuation value.
R2 = pointer to end of block
On exit
R0 = CRC-32 value for block
R1-R2 preserved
This SWI is used to update a running CRC-32 checksum with data from a buffer. The returned CRC-32 value should be passed back to the this SWI if the checksum needs to be updated further. ZLib_CRC32 is a slower call than OS_CRC, but more reliable.
ZLib_Adler32 (SWI &53AC3)
Calculate an Adler32 checksum for a given data buffer (adler32)
On entry
R0 = Adler-32 continuation value
R1 = pointer to start of block, or 0 to read the initial value to supply as a continuation value.
R2 = pointer to end of block
On exit
R0 = Adler-32 value for block
R1-R2 preserved
This SWI is used to update a running Adler-32 checksum with data from a buffer. The returned Adler-32 value should be passed back to the this SWI if the checksum needs to be updated further. Adler-32 is a faster checksum to calculate than CRC-32.
ZLib_Version (SWI &53AC4)
Return the version of ZLib in use (zlib_version)
On entry
None
On exit
R0 = pointer to read only version string
This SWI is used to read the version number of the ZLib library in use.
ZLib_ZCompress (SWI &53AC5)
Compress a source buffer (compress)
On entry
R0 = pointer to output buffer for compressed data
R1 = length of output buffer
R2 = pointer to input buffer of uncompressed data
R3 = length of input buffer
On exit
R0 = ZLib return code
R1 = length of output buffer used
This SWI is used to compress a block of data in a single call. The output buffer must be at least 0.1% larger than the input, plus 12 bytes.
ZLib_ZCompress2 (SWI &53AC6)
Compress a source buffer (compress2)
On entry
R0 = pointer to output buffer for compressed data
R1 = length of output buffer
R2 = pointer to input buffer of uncompressed data
R3 = length of input buffer
R4 = compression level
On exit
R0 = ZLib return code
R1 = length of output buffer used
This SWI is equivalent to ZLib_Compress but allows the compression level to be specified.
ZLib_ZUncompress (SWI &53AC7)
Compress a source buffer (uncompress)
On entry
R0 = pointer to output buffer for uncompressed data
R1 = length of output buffer
R2 = pointer to input buffer of compressed data
R3 = length of input buffer
On exit
R0 = ZLib return code
R1 = length of output buffer used
This SWI decompresses a buffer of data in a single call. The destination buffer must be large enough for the decompressed data.
ZLib_DeflateInit (SWI &53AC8)
Initialise a stream for compression (deflateInit)
On entry
R0 = pointer to Stream Control Block
R1 = compression level
R2 = pointer to ZLib version string expected ("1.1.4" at time of writing)
R3 = length of control block
On exit
R0 = ZLib return code
This SWI is used to initialise the ZLib compression algorithm. You should clear the workspace block to zeros. zalloc and zfree may point to routines to allocate and free memory. If these are not set then memory is allocated on a per application basis in the global dynamic area. zalloc and zfree will be entered within a C environment (ie APCS applies) with a small stack, in SVC mode. Because of this you cannot use longjmp, use functions that require large amounts of stack space, or perform any non-SVC mode operation.
ZLib_InflateInit (SWI &53AC9)
Initialise a stream for decompression (inflateInit)
On entry
R0 = pointer to Stream Control Block
R1 = pointer to ZLib version string expected ("1.1.4" at time of writing)
R2 = length of control block
On exit
R0 = ZLib return code
This SWI is used to initialise the ZLib stream decompression algorithm. You should clear the workspace block to zeros. zalloc and zfree may point to routines to allocate and free memory. If these are not set then memory is allocated on a per application basis in the global dynamic area. zalloc and zfree will be entered within a C environment (ie APCS applies) with a small stack, in SVC mode. Because of this you cannot use longjmp, use functions that require large amounts of stack space, or perform any non-SVC mode operation.
ZLib_DeflateInit2 (SWI &53ACA)
Initialise a stream for compression with control over parameters (deflateInit2)
On entry
R0 = pointer to Stream Control Block
R1 = compression level
R2 = compression method
R3 = window bits for history buffer
R4 = memory level
R5 = compression strategy
R6 = pointer to ZLib version string expected ("1.1.4" at time of writing)
R7 = length of control block
On exit
R0 = ZLib return code
This SWI is similar to ZLib_DeflateInit, but provides much greater control than that SWI.
ZLib_InflateInit2 (SWI &53ACB)
Initialise a stream for decompression with control over parameters (inflateInit2)
On entry
R0 = pointer to Stream Control Block
R1 = window bits
R2 = pointer to ZLib version string expected ("1.1.4" at time of writing)
R3 = length of control block
On exit
R0 = ZLib return code
This SWI is similar to ZLib_InflateInit but provides much greater control than that SWI.
ZLib_Deflate (SWI &53ACC)
Continue a stream compression (deflate)
On entry
R0 = pointer to Stream Control Block
R1 = flush type
On exit
R0 = ZLib return code
This SWI compresses as much data as possible and stops when the input buffer becomes empty or the output buffer becomes full. <next_in> and <avail_in> are read and updated after data has been processed. You should empty the output buffer when data appears there (<next_out> and <avail_out> will have been updated).
ZLib_Deflate performs one or both of the following actions:
- Compress more input starting at <next_in> and update <next_in> and <avail_in> accordingly. If not all input can be processed (because there is not enough room in the output buffer), <next_in> and <avail_in> are updated and processing will resume at this point for the next call of ZLib_Deflate.
- Provide more output starting at <next_out> and update <next_out> and <avail_out> accordingly. This action is forced if the parameter flush is non zero. Forcing flush frequently degrades the compression ratio, so this parameter should be set only when necessary (in interactive applications). Some output may be provided even if flush is not set.
Before calling ZLib_Deflate the client should ensure that at least one of the actions is possible by providing more input and/or consuming more output, and updating <avail_in> or <avail_out> accordingly; <avail_out> should never be zero before the call. The client may consume the compressed output when it wants, for example when the output buffer is full (<avail_out> == 0) or after each call of ZLib_Deflate. If deflate returns Z_OK and with zero <avail_out> it must be called again after making room in the output buffer because there might be more output pending.
If the flush type is set to Z_SYNC_FLUSH all pending output is flushed to the output buffer and the output is aligned on a byte boundary so that the decompressor can get all input data available so far. In particular <avail_in> is zero after the call if enough output space has been provided before the call. Flushing may degrade compression for some compression algorithms and so it should be used only when necessary.
If the flush type is set to Z_FULL_FLUSH, all output is flushed as with Z_SYNC_FLUSH and the compression state is reset so that decompression can restart from this point if previous compressed data has been damaged or if random access is desired. Using Z_FULL_FLUSH too often can seriously degrade the compression.
If deflate returns with <avail_out> == 0 this function must be called again with the same value of the flush parameter and more output space (updated <avail_out>) until the flush is complete (ZLib_Deflate returns with non-zero <avail_out>).
If the flush type is set to Z_FINISH pending input is processed, pending output is flushed and ZLib_Deflate returns with Z_STREAM_END if there was enough output space; if ZLib_Deflate returns with Z_OK this function must be called again with Z_FINISH and more output space (updated <avail_out>) but no more input data until it returns with Z_STREAM_END or an error. After ZLib_Deflate has returned Z_STREAM_END the only possible operations on the stream are ZLib_DeflateReset or ZLib_DeflateEnd.
Z_FINISH can be used immediately after ZLib_DeflateInit if all the compression is to be done in a single step. In this case, <avail_out> must be at least 0.1% larger than avail_in plus 12 bytes. If ZLib_Deflate does not return Z_STREAM_END then it must be called again as described above.
ZLib_Deflate sets <adler> to the adler32 checksum of all input read so far (that is, <total_in> bytes).
ZLib_Deflate may update <data_type> if it can make a good guess about the input data type (Z_ASCII or Z_BINARY). If in doubt the data is considered to be binary. This field is only for information purposes and does not affect the compression algorithm in any manner.
ZLib_Deflate returns Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if all input has been consumed and all output has been produced (only when the flush type is set to Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example if <next_in> or <next_out> was NULL), Z_BUF_ERROR if no progress is possible (for example <avail_in> or <avail_out> was zero).
ZLib_DeflateEnd (SWI &53ACD)
Terminate a stream compression (deflateEnd)
On entry
R0 = pointer to Stream Control Block
On exit
R0 = ZLib return code
This SWI frees all the memory used by the compression algorithm, discarding any unprocessed input or output.
ZLib_Inflate (SWI &53ACE)
Continue decompressing a stream (inflate)
On entry
R0 = pointer to Stream Control Block
R1 = flush type
On exit
R0 = ZLib return code
This SWI decompresses as much data as possible and stops when the input buffer becomes empty or the output buffer becomes full. <next_in> and <avail_in> are read and updated after data has been processed. You should empty the output buffer when data appears there (<next_out> and <avail_out> will have been updated).
ZLib_Inflate performs one or both of the following actions:
- Decompress more input starting at next_in and update next_in and avail_in accordingly. If not all input can be processed (because there is not enough room in the output buffer), next_in is updated and processing will resume at this point for the next call of ZLib_Inflate.
- Provide more output starting at <next_out> and update <next_out> and avail_out accordingly. ZLib_Inflate provides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter).
Before the call of ZLib_Inflate the application should ensure that at least one of the actions is possible by providing more input and /or consuming more output and updating the <next_in>/<next_out> and <avail_in>/<avail_out> values accordingly. The application can consume the uncompressed output when it wants, for example when the output buffer is full (<avail_out> == 0), or after each call of ZLib_Inflate. If this SWI returns Z_OK and with zero <avail_out> it must be called again after making room in the output buffer because there might be more output pending.
If R1 is set to Z_SYNC_FLUSH ZLib_Inflate flushes as much output as possible to the output buffer. The flushing behaviour of inflate is not specified for values of the flush parameter other than Z_SYNC_FLUSH and Z_FINISH but the current implementation actually flushes as much output as possible anyway.
ZLib_Inflate should normally be called until it returns Z_STREAM_END or an error. However if all decompression is to be performed in a single step (a single call of ZLib_Inflate) the parameter flush should be set to Z_FINISH. In this case all pending input is processed and all pending output is flushed; <avail_out> must be large enough to hold all the uncompressed data. (The size of the uncompressed data may have been saved by the compressor for this purpose.) The next operation on this stream must be inflateEnd to deallocate the decompression state. The use of Z_FINISH is never required but can be used to inform inflate that a faster routine may be used for the single ZLib_Inflate call.
If a preset dictionary is needed at this point (see ZLib_InflateSetDictionary below) ZLib_Inflate sets <adler> to the Adler-32 checksum of the dictionary chosen by the compressor and returns Z_NEED_DICT otherwise it sets <adler> to the Adler-32 checksum of all output produced so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described below. At the end of the stream ZLib_Inflate checks that its computed Adler-32 checksum is equal to that saved by the compressor and returns Z_STREAM_END only if the checksum is correct.
ZLib_Inflate returns Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if the end of the compressed data has been reached and all uncompressed output has been produced, Z_NEED_DICT if a preset dictionary is needed at this point, Z_DATA_ERROR if the input data was corrupted (input stream not conforming to the ZLib format or incorrect Adler-32 checksum), Z_STREAM_ERROR if the stream structure was inconsistent (for example if next_in or next_out was NULL), Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if no progress is possible or if there was not enough room in the output buffer when Z_FINISH is used. In the Z_DATA_ERROR case the application may then call ZLib_InflateSync to look for a good compression block.
ZLib_InflateEnd (SWI &53ACF)
Terminate a decompression stream (inflateEnd)
On entry
R0 = pointer to Stream Control Block
On exit
R0 = ZLib return code
This SWI frees all the memory used by the decompression algorithm, discarding any unprocessed input or output.
ZLib_DeflateSetDictionary (SWI &53AD0)
Initialise a string dictionary for a stream compression (deflateSetDictionary)
On entry
R0 = pointer to Stream Control Block
R1 = pointer to dictionary block (a stream of bytes)
R2 = length of dictionary block
On exit
R0 = ZLib return code
This SWI is used to initialise a compression dictionary. The dictionary should consist of strings (byte sequences) that are likely to be encountered later in the data to be compressed, with the most commonly used strings preferably put towards the end of the dictionary. Using a dictionary is most useful when the data to be compressed is short and can be predicted with good accuracy, the data can then be compressed better than with the default empty dictionary.
Depending on the size of the compression data structures selected by ZLib_DeflateInit or ZLib_DeflateInit2 a part of the dictionary may in effect be discarded, for example if the dictionary is larger than the window size in ZLib_Deflate or ZLib_Deflate2. Thus the strings most likely to be useful should be put at the end of the dictionary, not at the front.
Upon return of this function, <adler> is set to the Adler-32 value of the dictionary; the decompressor may later use this value to determine which dictionary has been used by the compressor. (The Adler32 value applies to the whole dictionary even if only a subset of the dictionary is actually used by the compressor.)
ZLib_DeflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a parameter is invalid (such as NULL dictionary) or the stream state is inconsistent (for example if ZLib_Deflate has already been called for this stream). ZLib_DeflateSetDictionary does not perform any compression: this will be done by ZLib_Deflate.
ZLib_DeflateCopy (SWI &53AD1)
Copy the compression state (deflateCopy)
On entry
R0 = pointer to destination Stream Control Block
R1 = pointer to source Stream Control Block
On exit
R0 = ZLib return code
This SWI is used to take a copy of the current compression state. This might be useful if you are attempting to filter the data in one of a number of ways.
ZLib_DeflateReset (SWI &53AD2)
Reset the internal compression state (deflateReset)
On entry
R0 = pointer to Stream Control Block
On exit
R0 = ZLib return code
This SWI is equivalent to ZLib_DeflateEnd followed by ZLib_DeflateInit.
ZLib_DeflateParams (SWI &53AD3)
Modifies the compression parameters (deflateParams)
On entry
R0 = pointer to Stream Control Block
R1 = compression level
R2 = compression strategy
On exit
R0 = ZLib return code
This SWI is updates the compression level and strategy. You may do this part way through compression.
ZLib_InflateSetDictionary (SWI &53AD4)
Initialise a string dictionary for a decompression stream (inflateSetDictionary)
On entry
R0 = pointer to Stream Control Block
R1 = pointer to dictionary block (a stream of bytes)
R2 = length of dictionary block
On exit
R0 = ZLib return code
This SWI is used to initialise a decompression dictionary. The dictionary must be the same as that used to compress the data (ZLib_DeflateSetDictionary).
ZLib_InflateSync (SWI &53AD5)
Re-synchronise decompression stream (inflateSync)
On entry
R0 = pointer to Stream Control Block
On exit
R0 = ZLib return code
This SWI will skip invalid data until a full flush point is found. This may be useful if you have data which is likely to be corrupted or is periodically synchronised and the data 'lost' is unimportant. An example might be a stream of graphical or audio data.
ZLib_InflateReset (SWI &53AD6)
Reset the decompression stream state (inflateReset)
On entry
R0 = pointer to Stream Control Block
On exit
R0 = ZLib return code
This SWI is equivalent to ZLib_InflateEnd followed by ZLib_InflateInit.
ZLib_GZOpen (SWI &53AD7)
Open a GZip file for reading or writing (gzopen)
On entry
R0 = pointer to filename
R1 = pointer to the 'mode' of file operation. This consists of two parts; the access type and the modifiers. Only one access type may be used, but multiple modifiers may be added to the end.
Access type Meaning
rb Open for reading
wb Open for writing
Modifier Meaning
0-9 compression level
h Huffman compression only
f Data is 'filtered' (small values, randomly distributed)
R RISC OS type information attached
R2 = load address of file (if 'R' and 'wb' used)
R3 = exec address of file (if 'R' and 'wb' used)
R4 = length address of file (if 'R' and 'wb' used)
R5 = attributes address of file (if 'R' and 'wb' used)
On exit
R0 = opaque GZip handle
R2 = load address of file (if 'R' and 'rb' used)
R3 = exec address of file (if 'R' and 'rb' used)
R4 = length address of file (if 'R' and 'rb' used)
R5 = attributes address of file (if 'R' and 'rb' used)
This SWI opens a file for accessing GZip compressed data. The 'R' extension is intended for compressing RISC OS files completely losslessly. Expanding such files on other systems will result in the loss of RISC OS type information only, the file data itself will be intact.
ZLib_GZRead (SWI &53AD8)
Read data from a GZip file (gzread)
On entry
R0 = opaque GZip handle
R1 = pointer to destination buffer
R2 = amount of data to read
On exit
R0 = number of bytes read
This SWI reads data from a previously opened GZip file.
ZLib_GZWrite (SWI &53AD9)
Write data to a GZip file (gzwrite)
On entry
R0 = opaque GZip handle
R1 = pointer to source buffer
R2 = amount of data to write
On exit
R0 = number of bytes written
This SWI writes data to a previously opened GZip file.
ZLib_GZFlush (SWI &53ADA)
Flush all pending data to a GZip file (gzflush)
On entry
R0 = opaque GZip handle
R1 = flush type
On exit
R0 = ZLib return code
This SWI writes data to a previously opened GZip file.
ZLib_GZClose (SWI &53ADB)
Close a GZip file (gzclose)
On entry
R0 = opaque GZip handle
On exit
R0 = ZLib return code
This SWI closes a previously opened GZip file.
ZLib_GZError (SWI &53ADC)
Return the last error from a GZip operation (gzerror)
On entry
R0 = opaque GZip handle
On exit
R0 = pointer to last error message string
R1 = ZLib return code
This SWI returns the last error message returned by a GZip operation.
ZLib_GZSeek (SWI &53ADD)
Move to a specific location in a GZip file (gzseek)
On entry
R0 = opaque GZip handle
R1 = position in decompressed data in bytes
R2 = type of seek to perform :
0 = Set absolute position (position = R1)
1 = Set relative position (position = R1 + current position)
On exit
R0 = new position in file
This SWI changes the pointer within a GZip file. The position specified is located such that byte number R1 had just been read from the file. The operation cannot be performed on files being written.
ZLib_GZTell (SWI &53ADE)
Return the current position in a GZip file (gztell)
On entry
R0 = opaque GZip handle
On exit
R0 = current position in decompressed data in bytes
This SWI returns the current position in the decompressed data in bytes as an offset from the start of the data.
ZLib_GZEOF (SWI &53ADF)
Check whether the end of file has been reached (gztell)
On entry
R0 = opaque GZip handle
On exit
R0 = 1 if EOF condition has been reached, 0 otherwise
This SWI checks whether the end of the file has been reached.
ZLib_TaskAssociate (SWI &53AE0)
Change Wimp Task association for a stream
On entry
R0 = pointer to Stream Control Block
R1 = association:
1 = associate with the current task
0 = dissociate with the current task
On exit
R0,R1 preserved
This SWI is used to change the association of a ZLib stream with the current task. When associated, the task's death will cause the memory allocated to the stream to be released automatically. If dissociated, the stream will never be freed unless the deflateEnd or inflateEnd calls are issued. This allows ZLib operations to be used safely in circumstances when the client may be terminated abnormally - if the application crashes and the ZLib stream is associated then the ZLib streams will be automatically closed first.
By default all streams are associated with the task with which they were created and destroyed automatically should that task terminate. You may wish to disable this operation using this SWI. In particular module clients of the ZLib module must dissociate from the current task if they wish to operate outside the bounds of a single task.
|
![[Select]](../imgs/seldoc.png)
