This documentation explains how to use the ZLib Newton port Library prototypes. As I'm writing this, the ZLib Newton port isn't complete.
The ZLib Newton port is a partial port for NewtonOS of ZLib 1.1.4 by Jean-loup Gailly & Mark Adler. The reason why it's partial is just that I'm lacking time to finish porting it (i.e. to write NewtonScript wrappers and the documentation). If you need functions that haven't been ported, contact me.
This documentation supposes that you're used to ZLib APIs. I won't describe them here, I'll just describe the wrappers. You can find the documentation for the ZLib APIs here.
The ZLib can only be interfaced from NewtonScript for the moment.
The NewtonScript interface is based on units. For an introduction on units, cf the Kallisys Newton Libraries general documentation.
The Units define a function and two prototypes.
GetZLibVersion
call UR( kZLibSymbol, 'GetZLibVersion ) with ()
Returns the version of the ZLib as string.
| return value | The version of the ZLib library as a NewtonScript (unicode) string. |
ProtoDeflateStream is a prototype to deflate (compress) a stream of data. You use it with the _proto chain of NewtonOS, i.e.:
local frame myDeflateStream := {
_proto: UR( kZLibSymbol, 'ProtoDeflateStream )
};
The deflate stream frame has two slots, zstream and zstreamf. zstream is an integer. It's
a pointer to the stream structure for this prototype. Do not use it, just let the methods set/use/remove it. zstreamf
slot is a frame with the NewtonScript representation of some elements of the zstream structure. It has the following slots:
| bin_in | The binary object to parse data from. This binary can be of any class. |
| next_in | The index (in bytes, zero based) to the data in the binary object. This is an integer, and added to the pointer of the binary object, it is the next_in field of the zstream structure. |
| avail_in | The number of bytes available in the binary object for input. Beware, there is no check that added to next_in, this is smaller than the size of the binary. This value is directly converted to/from the zstream avail_in field. |
| total_in | The number of input bytes processed. This field is read from the zstream total_in field. |
| bin_out | The binary object to store output to. This binary can be of any class. |
| next_out | The index (in bytes, zero based) to the data in the binary object. This is an integer, and added to the pointer of the binary object, it is the next_out field of the zstream structure. |
| avail_out | The number of bytes available in the binary object for output. Beware, there is no check that added to next_out, this is smaller than the size of the binary. This value is directly converted to/from the zstream avail_out field. |
| total_out | The number of output bytes generated. This field is read from the zstream total_out field. |
| msg | The NewtonScript (Unicode) string representation of the zstream msg field. May be NIL or absent if there is no message (cf the discussion of methods below). |
You can access slots of the object as you normally do in NewtonScript and send messages with the
myDeflateStream:Message( parameters ... ) syntax.
The messages are the following:
DeflateInit
deflateStream:DeflateInit(level)
Initialize the deflate stream.
| level | The level of compression to use. This can be NIL, a symbol or an integer (between -1 and 9). Allowed symbols are:
If it's NIL, 'default is assumed. If the input value is an integer, it's passed directly without any check to deflateInit function |
||||||||
| return value | NIL if deflateInit returned Z_OK, an integer otherwise. |
||||||||
| Discussion | If something went wrong in the NS wrapper, an exception is thrown. If deflateInit didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). If the 'zstreamf slot is present, then it's read and values there are set to the zstream structure before being passed to deflateInit. This means that deflateInit may do some initialization process. Otherwise, the zstreamf slot is created. Also, the 'zstream slot will be set to the pointer to the zstream structure and the zstreamf frame will be filled with the output of deflateInit method. |
DeflateInit2
deflateStream:DeflateInit2(level, method, windowBits, memLevel, strategy)
Initialize the deflate stream with advanced options.
| level | The level of compression to use. This is exactly like level parameter of DeflateInit method. |
| method | The method of compression to use. This must be either 8 (Z_DEFLATE_METHOD constant) or NIL (in which case 8 is assumed). |
| windowBits | This must be an integer or NIL. If this is NIL, 15 is assumed (just as with deflateInit function). The value (normally between 8 and 15) is passed directly to the deflateInit2 function. This means that you can pass a negative value (e.g. -15) to use the ZLib undocumented feature and bypass the ZLib header. |
| memLevel | This must be an integer or NIL. If this is NIL, 8 is assumed (just as with deflateInit function). The value (normally between 1 and 9) is passed directly to the deflateInit2 function. Note: Steve's tests showed that you can run out of memory with 8 on an MP2000. Lower memory level means worst compression, but unlike modifications of the windowWidth, it doesn't affect the compatibility. |
| strategy | The strategy of compression to use. This can be NIL, a symbol or an integer. Allowed symbols are:
If it's NIL, 'default is assumed. If the input value is an integer, it's passed directly without any check to the deflateInit2 function |
| return value | NIL if deflateInit2 returned Z_OK, an integer otherwise. |
| Discussion | The discussion about deflateInit applies for deflateInit2 as well. |
Deflate
deflateStream:Deflate(flush)
Compress some bytes.
| flush | Which flush behavior to have. This can be NIL, a symbol or an integer. Allowed symbols are:
If it's NIL, 'no is assumed. If the input value is an integer, it's passed directly without any check to the deflate function |
| return value | NIL if deflate returned Z_OK, an integer otherwise. |
| Discussion | The role of the flush parameter is explained in the ZLib documentation. The role of the zstreamf frame slots is exactly the same as the role of the zstream structure as mentioned in the ZLib documentation. If an error occured in the NS wrapper, an execption is thrown. If deflate didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). Note: this is the only method of this prototype which can return an integer (here 1) with normal operations. Please read the ZLib documentation. |
DeflateEnd
deflateStream:DeflateEnd()
Disposes the deflate stream.
| return value | NIL if deflate returned Z_OK, an integer otherwise. |
| Discussion | deflateEnd function is called. Additionally, the zstream structure is disposed and the 'zstream slot is removed. The zstreamf slot isn't removed, just because you might want to keep it. It will go away with the DeflateStream object at next garbage collection, but you can remove it as well to save some NS Heap bytes. If an error occured in the NS wrapper, an execption is thrown. If deflateEnd didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). |
DeflateReset
deflateStream:DeflateReset()
Resets the deflate stream.
| return value | NIL if deflate returned Z_OK, an integer otherwise. |
| Discussion | deflateReset function is called. This is equivalent to deflateEnd followed by deflateInit. If an error occured in the NS wrapper, an execption is thrown. If deflateReset didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). |
ProtoInflateStream is a prototype to inflate (decompress) a stream of data. You use it with the _proto chain of NewtonOS, i.e.:
local frame myInflateStream := {
_proto: UR( kZLibSymbol, 'ProtoInflateStream )
};
The inflate stream frame has two slots, zstream and zstreamf just like
the deflate stream frame.
You can access slots of the object as you normally do in NewtonScript and send messages with the
myInflateStream:Message( parameters ... ) syntax.
The messages are the following:
InflateInit
inflateStream:InflateInit()
Initialize the inflate stream.
| return value | NIL if inflateInit returned Z_OK, an integer otherwise. |
| Discussion | If something went wrong in the NS wrapper, an exception is thrown. If inflateInit didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). If the 'zstreamf slot is present, then it's read and values there are set to the zstream structure before being passed to inflateInit. This means that inflateInit may do some initialization process. Otherwise, the zstreamf slot is created. Also, the 'zstream slot will be set to the pointer to the zstream structure and the zstreamf frame will be filled with the output of inflateInit method. |
InflateInit2
inflateStream:InflateInit2(windowBits)
Initialize the inflate stream with advanced options.
| windowBits | This must be an integer or NIL. If this is NIL, 15 is assumed (just as with inflateInit function). The value (normally between 8 and 15) is passed directly to the inflateInit2 function. This means that you can pass a negative value (e.g. -15) to use the ZLib undocumented feature and bypass the ZLib header. |
| return value | NIL if inflateInit2 returned Z_OK, an integer otherwise. |
| Discussion | The discussion about inflateInit applies for inflateInit2 as well. |
Inflate
inflateStream:Inflate(flush)
Compress some bytes.
| flush | Which flush behavior to have. This can be NIL, a symbol or an integer. Allowed symbols are:
If it's NIL, 'no is assumed. If the input value is an integer, it's passed directly without any check to the inflate function |
| return value | NIL if inflate returned Z_OK, an integer otherwise. |
| Discussion | The role of the flush parameter is explained in the ZLib documentation. The role of the zstreamf frame slots is exactly the same as the role of the zstream structure as mentioned in the ZLib documentation. If an error occured in the NS wrapper, an execption is thrown. If inflate didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). Note: this is the only method of this prototype which can return an integer (here 1) with normal operations. Please read the ZLib documentation. |
InflateEnd
inflateStream:InflateEnd()
Disposes the inflate stream.
| return value | NIL if inflate returned Z_OK, an integer otherwise. |
| Discussion | inflateEnd function is called. Additionally, the zstream structure is disposed and the 'zstream slot is removed. The zstreamf slot isn't removed, just because you might want to keep it. It will go away with the InflateStream object at next garbage collection, but you can remove it as well to save some NS Heap bytes. If an error occured in the NS wrapper, an execption is thrown. If inflateEnd didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). |
InflateReset
inflateStream:InflateReset()
Resets the inflate stream.
| return value | NIL if inflate returned Z_OK, an integer otherwise. |
| Discussion | inflateReset function is called. This is equivalent to inflateEnd followed by inflateInit. If an error occured in the NS wrapper, an execption is thrown. If inflateReset didn't return Z_OK and if zstream->msg isn't nil, then zstreamf.msg is set to this message (as a NewtonScript string). |