![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction and Overview
The Zipper module provides a simple interface for creating and readingZip 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.
Technical Details
The Zipper module provides two different APIs; one for creating Zip archives, and one for extracting data.
File name conventions
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.
Passwords
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.
SWI calls
| R0 | = | Flags :
| |||||||||
| R1 | = | Pointer to filename of archive to read | |||||||||
| R0 | = | 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.
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Unzip handle |
This SWI is used to close an archive previously opened for extraction.
| R0 | = | Flags :
| |||||||||||||||
| R1 | = | Unzip handle | |||||||||||||||
| R2 - R3 | = | dependent on request type | |||||||||||||||
| R0 - R3 | = | dependent on request type |
This SWI is used to read miscellaneous information about an open archive.
| R0 | = | Flags :
| |||||||||
| R1 | = | Unzip handle | |||||||||
| R0 | = | number of objects in archive |
This SWI is used to read the number of objects in the archive. 'Objects' includes both files and directories.
| R0 | = | Flags :
| |||||||||
| R1 | = | Unzip handle | |||||||||
| R2 | = | Pointer to buffer for data | |||||||||
| R3 | = | Length of buffer, or -ve to return buffer size requirements | |||||||||
| R0 | = | 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.
| R0 | = | Flags :
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| R1 | = | Unzip handle | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| R2 | = | pointer to output buffer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| R3 | = | number of objects to read | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| R4 | = | opaque offset of object to start at, or 0 for first object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| R5 | = | length of output buffer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| R3 | = | number of objects read |
| R4 | = | next opaque offset to use for enumerate |
| R5 | = | 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.
| R0 | = | Flags |
| R1 | = | Unzip handle |
| R2 - R3 | = | 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.
| R0 | = | Flags :
| ||||||
| R1 | = | Unzip handle | ||||||
| R2 | = | pointer to filename to read | ||||||
| R3 | = | pointer to buffer for data | ||||||
| R4 | = | length of buffer | ||||||
| R3 | = | pointer to end of data |
| R4 | = | 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.
| R0 | = | 0 (no flags set) |
| R1 | = | Unzip handle |
| R2 | = | pointer to filename to read |
| R0 | = | object type (1 = file, 2 = directory) |
| R2 | = | load address |
| R3 | = | exec address |
| R4 | = | object length when decompressed |
| R5 | = | file attributes |
This SWI is used to read information on a object, using a similar interface to OS_File 5.
| R0 | = | Flags :
| |||||||||
| R1 | = | Unzip handle | |||||||||
| R2 | = | Pointer to filename of file to read | |||||||||
| R3 | = | Pointer to password to use, if bit 6 set | |||||||||
This SWI is used to open a file in an archive for reading.
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | 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.
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Unzip handle |
| R2 | = | Pointer to buffer to write in to |
| R3 | = | Length of buffer |
| R0 | = | 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.
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Unzip handle |
| R0 | = | 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.
| R0 | = | Flags :
| ||||||||||||
| R1 | = | Pointer to filename of archive to create or append to | ||||||||||||
| R0 | = | 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.
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Zip handle |
This SWI is used to close an archive previously opened for writing.
| R0 | = | Flags :
| ||||||||||||||||||||||||||||||||
| R1 | = | Zip handle | ||||||||||||||||||||||||||||||||
| R2 | = | Pointer to filename of file to write in archive | ||||||||||||||||||||||||||||||||
| R3 | = | Compression method and level :
| ||||||||||||||||||||||||||||||||
| R4 | = | Pointer to time specifier block; if bit 0 set :
| ||||||||||||||||||||||||||||||||
| R5 | = | Pointer to extra field data, if bit 3 set | ||||||||||||||||||||||||||||||||
| R6 | = | Length of extra field, if bit 3 set | ||||||||||||||||||||||||||||||||
| R7 | = | Pointer to zero terminated comment field, if bit 3 set | ||||||||||||||||||||||||||||||||
| R8 | = | Pointer to block of zip file attributes :
| ||||||||||||||||||||||||||||||||
| R9 | = | 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.
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Zip handle |
| R0 | = | Original (uncompressed) size of file |
| R1 | = | New (compressed) size of file in archive |
This SWI is used to close a file in an archive opened for writing.
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Zip handle |
| R2 | = | Pointer to buffer of data to write |
| R3 | = | Length of buffer |
This SWI is used to write data to the currently opened file in the archive.