Pyromaniac

Pyromaniac PRM: Zipper

Pyromaniac PRM: Zipper

RISC OS PyromaniacZipper

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.

RISCOS Ltd4.29
Supported
RISC OS Pyromaniac7.21
Supported

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

Zipper_UnZipOpenSWI &559C0
Open an archive for extraction
R0=Flags :
Bit(s)Meaning
31If set, do not discard this archive handle when the application exits
0-30Reserved, must be 0
R1=Pointer to filename of archive to read
R0=Opaque unzip handle, guaranteed not to be 0
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipCloseSWI &559C1
Close a file, previously opened for extraction
R0=Flags (reserved, must be 0)
R1=Unzip handle
None
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipInfoSWI &559C2
Read information about an open archive
R0=Flags :
Bit(s)Meaning
0-7Requested information type :
ValueMeaning
0Read number of entries in the archive
1Read archive comment
8-31Reserved, must be 0
R1=Unzip handle
R2 - R3=dependent on request type
R0 - R3=dependent on request type
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipInfo 0NumberOfObjectsSWI &559C2
Read number of objects in the archive
R0=Flags :
Bit(s)Meaning
0-70 (reason code)
8-31Reserved, must be 0
R1=Unzip handle
R0=number of objects in archive
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipInfo 1ReadCommentSWI &559C2
Read zip archive comment
R0=Flags :
Bit(s)Meaning
0-71 (reason code)
8-31Reserved, must be 0
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
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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_UnZipEnumerateSWI &559C3
Enumerate the objects in an archive
R0=Flags :
Bit(s)Meaning
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(s)Meaning
0Version number of creator
Version number required to extract
1General purpose flags (refer to Zip specification)
2Compression method (refer to Zip specification)
3Size of file when compressed
4Size of file when expanded
5Internal file attributes
6External file attributes
7Centisecond (0-99)
Second (0-59)
Minute (0-59)
Hour (0-23)
Date (1-31)
Month (1-12)
Year (0...)
8RISC OS Load address
RISC OS Exec address
9RISC OS Uncompressed length (duplicate of b4)
10RISC OS Attributes
11RISC OS Object type
12RISC OS File type
13GBPB-style filename length (aligned to a multiple of 4)
Zero terminated filename, aligned to a word boundary, inline with this data.
14Filename length (aligned to a multiple of 4)
Zero terminated filename, aligned to a word boundary will be written after the fixed size options.
15Extra information length
Zero terminated extra information, aligned to a word boundary will be written after the filename.
16File 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
R3=number of objects read
R4=next opaque offset to use for enumerate
R5=size of unused data in output buffer
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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.

Zipper_UnZipFileInfoSWI &559C4
Read information on a file
R0=Flags
R1=Unzip handle
R2 - R3=See sub-reasons
None
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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 bufferToBufferSWI &559C4
Read information on a file to a buffer
R0=Flags :
Bit(s)Meaning
0-16Flags as Zipper_UnZipEnumerate
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
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipFileInfo to registersToRegistersSWI &559C4
Read information on a file to registers, like OS_File 5
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
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipFileOpenSWI &559C5
Open a file in an archive for input
R0=Flags :
Bit(s)Meaning
6Password supplied in R3
otherReserved, must be 0
R1=Unzip handle
R2=Pointer to filename of file to read
R3=Pointer to password to use, if bit 6 set
None
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipFileCloseSWI &559C6
Close the current opened archive file
R0=Flags (reserved, must be 0)
R1=Unzip handle
None
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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_UnZipFileReadSWI &559C7
Read data from a previously opened input archive
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
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_UnZipFileEOFSWI &559C8
Check whether end of file has been reached
R0=Flags (reserved, must be 0)
R1=Unzip handle
R0=1 if 'end of file', 0 if not.
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_ZipOpenSWI &559D0
Create an archive
R0=Flags :
Bit(s)Meaning
0Append to file, rather than create file (for building self extracting archives
31If set, do not discard this archive handle when the application exits
1-30Reserved, must be 0
R1=Pointer to filename of archive to create or append to
R0=Opaque zip handle, guaranteed not to be 0
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_ZipCloseSWI &559D1
Close a file, previously opened for writing
R0=Flags (reserved, must be 0)
R1=Zip handle
None
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_ZipFileOpenSWI &559D2
Open a file in an archive for input
R0=Flags :
Bit(s)Meaning
0Time specifier contains RISC OS details (otherwise it contains a Zip-style time specification)
1Object is a directory
2Object is text-like
3Extra field is present
4Comment field is present
5File attributes are present
6Password supplied in R9
otherReserved, must be 0
R1=Zip handle
R2=Pointer to filename of file to write in archive
R3=Compression method and level :
Bit(s)Meaning
0-7Compression method :
ValueMeaning
0Store data as-is
8Apply deflate algorithm to compress data
otherUndefined
8-11Compression level :
ValueMeaning
1'Super fast, little compression'
2'Fast, more compression'
8'Normal speed, normal compression'
9'Slowest, maximum compression'
otherUndefined
12-31Reserved (must be zero)
R4=Pointer to time specifier block; if bit 0 set :
OffsetContents
0Load address
4Exec address
8Attributes
If bit 0 clear :
OffsetContents
0Centiseconds
4Seconds
8Minutes
12Hours
16Date
20Month
24Year
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 :
OffsetContents
0internal file attributes
4external file attributes
R9=Pointer to password to use, if bit 6 set
None
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_ZipFileCloseSWI &559D3
Close the current opened archive file
R0=Flags (reserved, must be 0)
R1=Zip handle
R0=Original (uncompressed) size of file
R1=New (compressed) size of file in archive
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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

Zipper_ZipFileWriteSWI &559D4
Write data to a previously opened archive
R0=Flags (reserved, must be 0)
R1=Zip handle
R2=Pointer to buffer of data to write
R3=Length of buffer
None
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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