|
Zipper
Introduction and Overview
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.
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.
SWI calls
Zipper_UnZipOpen (SWI &559C0)
Open an archive for extraction
On entry
R0 = Flags :
bit 31 = If set, do not discard this archive handle when the application exits
bits 0-30 = Reserved, must be 0
R1 = Pointer to filename of archive to read
On exit
R0 = Opaque unzip handle, guaranteed not to be 0
This SWI opens a Zip archive for reading via the Zipper API. If the file cannot be opened, an error will be returned.
Zipper_UnZipClose (SWI &559C1)
Close a file, previously opened for extraction
On entry
R0 = Flags (reserved, must be 0)
R1 = Unzip handle
On exit
All registers preserved
This SWI is used to close an archive previously opened for extraction.
Zipper_UnZipInfo (SWI &559C2)
Read information about an open archive
On entry
R0 = Flags :
bits 0-7 = Requested information type :
0 = Read number of entries in the archive
1 = Read archive comment
bits 8-31 Reserved, must be 0
R1 = Unzip handle
R2-R3 = dependent on request type
On exit
R0-R3 = dependent on request type
This SWI is used to read miscellaneous information about an open archive.
Zipper_UnZipInfo 0 (SWI &559C2)
Read number of objects in the archive
On entry
R0 = Flags :
bits 0-7 = 0 (reason code)
bits 8-31 = Reserved, must be 0
R1 = Unzip handle
On exit
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.
Zipper_UnZipInfo 1 (SWI &559C2)
Read zip archive comment
On entry
R0 = Flags :
bits 0-7 = 1 (reason code)
bits 8-31 = Reserved, must be 0
R1 = Unzip handle
R2 = Pointer to buffer for data
R3 = Length of buffer, or -ve to return buffer size requirement
On exit
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.
Zipper_UnZipEnumerate (SWI &559C3)
Enumerate the objects in an archive
On entry
R0 = Flags :
bits 0-16 = 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.
bit 0 = Version number of creator, version number required to extract
bit 1 = General purpose flags (refer to Zip specification)
bit 2 = Compression method (refer to Zip specification)
bit 3 = Size of file when compressed
bit 4 = Size of file when expanded
bit 5 = Internal file attributes
bit 6 = External file attributes
bit 7 = Centisecond (0-99)
Second (0-59)
Minute (0-59)
Hour (0-23)
Date (1-31)
Month (1-12)
Year (0...)
bit 8 = RISC OS Load address and RISC OS Exec address
bit 9 = RISC OS Uncompressed length (duplicate of b4)
bit 10 = RISC OS Attributes
bit 11 = RISC OS Object type
bit 12 = RISC OS File type
bit 13 = GBPB-style filename length (aligned to a multiple of 4)
Zero terminated filename, aligned to a word boundary, inline with this data.
bit 14 = Filename length (aligned to a multiple of 4)
Zero terminated filename, aligned to a word boundary will be written after the fixed size options.
bit 15 = Extra information length
Zero terminated extra information, aligned to a word boundary will be written after the filename.
bit 16 = File comment length
Zero terminated comment will be written after the extra information, and will be word aligned.
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
On exit
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 similar to OS_GBPB. This makes simple its use as a direct replacement for OS_GBPB 10.
Zipper_UnZipFileInfo (SWI &559C4) Read information on a file
On entry
R0 = Flags
R1 = Unzip handle
R2-R3 = See sub-reasons
On exit
Dependent on reason code
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.
Zipper_UnZipFileInfo to buffer (SWI &559C4)
Read information on a file to a buffer
On entry
R0 = Flags :
bits 0-16 : Flags as Zipper_UnZipEnumerate
R1 = Unzip handle
R2 = pointer to filename to read
R3 = pointer to buffer for data
R4 = length of buffer
On exit
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.
Zipper_UnZipFileInfo to registers (SWI &559C4)
Read information on a file to registers, like OS_File 5
On entry
R0 = 0 (no flags set)
R1 = Unzip handle
R2 = pointer to filename to read
On exit
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
Zipper_UnZipFileOpen (SWI &559C5)
Open a file in an archive for input
On entry
R0 = Flags (reserved, must be 0)
R1 = Unzip handle
R2 = Pointer to filename of file to read
On exit
All registers preserved
This SWI is used to open a file in an archive for reading. Because of the linear structure of zip files, only a single file within the archive may be opened for reading. If a second file within the archive is opened for writing before the first is closed, an error will be returned.
Zipper_UnZipFileClose (SWI &559C6)
Close the current opened archive file
On entry
R0 = Flags (reserved, must be 0)
R1 = Unzip handle
On exit
All registers preserved
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.
Zipper_UnZipFileRead (SWI &559C7)
Read data from a previously opened input archive
On entry
R0 = Flags (reserved, must be 0)
R1 = Unzip handle
R2 = Pointer to buffer to write in to
R3 = Length of buffer
On exit
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.
Zipper_UnZipFileEOF (SWI &559C8)
Check whether end of file has been reached
On entry
R0 = Flags (reserved, must be 0)
R1 = Unzip handle
On exit
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.
Zipper_ZipOpen (SWI &559D0)
Create an archive
On entry
R0 = Flags :
bit 0 = Append to file, rather than create file (for building self extracting archives
bit 31 = If set, do not discard this archive handle when the application exits
bit 1-30 Reserved, must be 0
R1 = Pointer to filename of archive to create or append to
On exit
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.
Zipper_ZipClose (SWI &559D1)
Close a file, previously opened for writing
On entry
R0 = Flags (reserved, must be 0)
R1 = Zip handle
On exit
All registers preserved
This SWI is used to close an archive previously opened for writing.
Zipper_ZipFileOpen (SWI &559D2)
Open a file in an archive for input
On entry
R0 = Flags :
bit 0 = Time specifier contains RISC OS details (otherwise it contains a Zip-style time specification)
bit 1 = Object is a directory
bit 2 = Object is text-like
bit 3 = Extra field is present
bit 4 = Comment field is present
bit 5 = File attributes are present
bits 6-31 = Reserved, must be 0
R1 = Zip handle
R2 = Pointer to filename of file to write in archive
R3 = Compression method and level :
bits 0-7 = Compression method :
0 = Store data as-is
8 = Apply deflate algorithm to compress data
Others Undefined
bits 8-11 = Compression level :
1 = 'Super fast, little compression'
2 = 'Fast, more compression'
8 = 'Normal speed, normal compression'
9 = 'Slowest, maximum compression'
Other Undefined
bits 12-31 = Reserved (must be zero)
R4 = Pointer to time specifier block; if bit 0 set :
+0 = Load address
+4 = Exec address
+8 = Attributes
If bit 0 clear :
+0 = Centiseconds
+4 = Seconds
+8 = Minutes
+12 = Hours
+16 = Day
+20 = Month
+24 = Year
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 :
+0 = internal file attributes
+4 = external file attributes
On exit
All registers preserved
This SWI is used to open a file in an archive for writing, or to create a directory. Because of the linear structure of zip files, only a single file within the archive may be opened for writing. If a second file within the archive is opened for writing before the first is closed, an error will be returned.
Zipper_ZipFileClose (SWI &559D3)
Close the current opened archive file
On entry
R0 = Flags (reserved, must be 0)
R1 = Zip handle
On exit
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.
Zipper_ZipFileWrite (SWI &559D4)
Write data to a previously opened archive
On entry
R0 = Flags (reserved, must be 0)
R1 = Zip handle
R2 = Pointer to buffer of data to write
R3 = Length of buffer
On exit
All registers preserved
This SWI is used to write data to the currently opened file in the archive.
|
![[Select]](../imgs/seldoc.png)
