The Zipper module provides a simple interface for creating and reading Zip archives, using the ZLib module to provide a means of deflating and inflating files.

Zip archives are collections of files, compressed using the deflate algorithm. These files originated with PKWare's PKZip and PKUnzip utilities under DOS. They are now the most widespread means of transferring compressed data. Zip files consist of a catalogue containing information about the objects contained in the file.

The Zip archives created are compatible with PKZip and Info-Zip, which should allow them to be used between operating systems.

The Zipper module provides two different APIs; one for creating Zip archives, and one for extracting data.

Within the Zipper module interface, filenames are referred to with RISC OS semantics. That is, although the archives themselves use period and slash (. and /), these will be reversed when creating or extracting filenames from the archive by the module. Further character translations may occur in future. Unlike RISC OS, filenames are case sensitive.

Although passwords are supported by the Zipper modules API, the implementation has presently been left disabled. Passwords should be a string of characters used to encrypt or decrypt the data in the associated file. Passwords on Zip archives are known to be weak. Further information can be obtained on the Internet regarding the security afforded by such encryption.
Flags : If set, do not discard this archive handle when the application exits Reserved, must be 0 Pointer to filename of archive to read Opaque unzip handle, guaranteed not to be 0

This SWI is opens a Zip archive for reading via the Zipper API. If the file cannot be opened, an error will be returned.

 Flags (reserved, must be 0) Unzip handle

This SWI is used to close an archive previously opened for extraction.

 Flags : Requested information type : Read number of entries in the archive Read archive comment Reserved, must be 0 Unzip handle dependent on request type dependent on request type

This SWI is used to read miscellaneous information about an open archive.

 Flags : 0 (reason code) Reserved, must be 0 Unzip handle number of objects in archive

This SWI is used to read the number of objects in the archive. 'Objects' includes both files and directories.

 Flags : 1 (reason code) Reserved, must be 0 Unzip handle Pointer to buffer for data Length of buffer, or -ve to return buffer size requirements amount of data read, or required

This SWI is used to read the comment from a Zip archive. Zip archives can have a user-readable 'comment' section included which describes the content of the archive. This area can be read through this call.

 Flags :

Elements to return in to the buffer. For each bit set, an integer value will be written into the output buffer (except where stated). Where multiple values are given, they will be stored consecutively.

Version number of creator
Version number required to extract General purpose flags (refer to Zip specification) Compression method (refer to Zip specification) Size of file when compressed Size of file when expanded Internal file attributes External file attributes Centisecond (0-99)
Second (0-59)
Minute (0-59)
Hour (0-23)
Date (1-31)
Month (1-12)
Year (0...) RISC OS Load address
RISC OS Exec address RISC OS Uncompressed length (duplicate of b4) RISC OS Attributes RISC OS Object type RISC OS File type GBPB-style filename length (aligned to a multiple of 4)
Zero terminated filename, aligned to a word boundary, inline with this data. Filename length (aligned to a multiple of 4)
Zero terminated filename, aligned to a word boundary will be written after the fixed size options. Extra information length
Zero terminated extra information, aligned to a word boundary will be written after the filename. File comment length
Zero terminated comment will be written after the extra information, and will be word aligned. Unzip handle pointer to output buffer number of objects to read opaque offset of object to start at, or 0 for first object length of output buffer number of objects read next opaque offset to use for enumerate size of unused data in output buffer

This SWI is used to enumerate the objects in the archive. Data is written in the order given in the flags table above. The interface is intentionally similarly to OS_GBPB. This makes simple its use as a direct replacement for OS_GBPB.

Flags Unzip handle See sub-reasons

This SWI is used to read information on a single object. The call is available in two forms. The first form reads information on the object in the same manner as Enumerate. The second form reads information on the object in a similar manner to OS_File 5.

 Flags : Flags as Zipper_UnZipEnumerate Unzip handle pointer to filename to read pointer to buffer for data length of buffer pointer to end of data space remaining, or -ve length if data would not fit

This SWI is used to read information on a object, using a similar interface to UnZipEnumerate.

 0 (no flags set) Unzip handle pointer to filename to read object type (1 = file, 2 = directory) load address exec address object length when decompressed file attributes

This SWI is used to read information on a object, using a similar interface to OS_File 5.

 Flags : Password supplied in R3 Reserved, must be 0 Unzip handle Pointer to filename of file to read Pointer to password to use, if bit 6 set

This SWI is used to open a file in an archive for reading.

 Flags (reserved, must be 0) Unzip handle

This SWI is used to close a file in an archive opened for reading. An error will be given if a CRC error was encountered.

 Flags (reserved, must be 0) Unzip handle Pointer to buffer to write in to Length of buffer number of bytes read, or 0 if nothing could be read

This SWI is used to read data from the currently opened file in the archive.

 Flags (reserved, must be 0) Unzip handle 1 if 'end of file', 0 if not.

This SWI is used to discover whether the end of the currently opened file in the archive has been reached.

 Flags : Append to file, rather than create file (for building self extracting archives If set, do not discard this archive handle when the application exits Reserved, must be 0 Pointer to filename of archive to create or append to Opaque zip handle, guaranteed not to be 0

This SWI opens a Zip archive for writing via the Zipper API. If the file cannot be opened, an error will be returned.

 Flags (reserved, must be 0) Zip handle

This SWI is used to close an archive previously opened for writing.

 Flags : Time specifier contains RISC OS details (otherwise it contains a Zip-style time specification) Object is a directory Object is text-like Extra field is present Comment field is present File attributes are present Password supplied in R9 Reserved, must be 0 Zip handle Pointer to filename of file to write in archive Compression method and level : Compression method : Store data as-is Apply deflate algorithm to compress data Undefined Compression level : 'Super fast, little compression' 'Fast, more compression' 'Normal speed, normal compression' 'Slowest, maximum compression' Undefined Reserved (must be zero) Pointer to time specifier block; if bit 0 set : Load address Exec address Attributes If bit 0 clear : Centiseconds Seconds Minutes Hours Date Month Year Pointer to extra field data, if bit 3 set Length of extra field, if bit 3 set Pointer to zero terminated comment field, if bit 3 set Pointer to block of zip file attributes : internal file attributes external file attributes Pointer to password to use, if bit 6 set

This SWI is used to open a file in an archive for writing, or to create a directory.

 Flags (reserved, must be 0) Zip handle Original (uncompressed) size of file New (compressed) size of file in archive

This SWI is used to close a file in an archive opened for writing.

 Flags (reserved, must be 0) Zip handle Pointer to buffer of data to write Length of buffer

This SWI is used to write data to the currently opened file in the archive.
Changed some of the wording to be clearer. Corrected a few misspelt words. ZipFileClose now returns relative sizes of data. Password bit now included on UnZipFileOpen and ZipFileOpen. Added new 'Passwords' section to the Technical Details. Included version table for compatibility info.