Class Documentation
Compression |
1.0 |
ID_COMPRESSION |
Stable |
Data |
April 2004 |
Rocklyte Systems, based on work from Jean-loup Gailly and Mark Adler. |
Rocklyte Systems (c) 2001-2004. All rights reserved. |
Description
The Compression class provides the necessary means to compress and
decompress your data. It provides support for file based compression
as well as memory based compression routines. The base class uses zip
algorithms to support pkzip files, while other forms of compressed data can
be supported by installing extra compression sub-classes.
The Compression class is compatible with the Dynamic Markup Language.
Here are some examples that demonstrate the use of compression objects in
DML:
<!-- Extract all data from a zip file to the athene: directory -->
<compression src="athene:data.zip">
<action method="decompressfile" &path="*" &destination="athene:"/>
</compression>
<!-- Delete the readme.txt file from a zip file -->
<compression src="athene:data.zip">
<action method="removefile" &path="readme.txt"/>
</compression>
<!-- Add the readme.txt file back to the zip file -->
<compression src="athene:data.zip">
<action method="compressfile" &location="readme.txt" &path=""/>
</compression>
If data is to be encyrpted or decrypted then you will need to set the
Password field so that it refers to a null-terminated
encryption string. If you don't know the password for an encrypted file,
errors will be returned when trying to decompress the information.
To peruse the contents of a compressed file, use the
FileList field to retrieve a list of files available
in the object. This will give you information on the name, time stamp and
size of each individual file.
To adjust the level of compression used to pack each file, set the
CompressionLevel field to a value between 0
and 100%.
Actions
The Compression class supports the following actions:
ClosingTag | If the object is non-static, this action will start the execution process and then the object will self-destruct. |
Init | Prepares a compression object for usage. |
Methods
The Compression class implements the following methods:
Structure
The Compression object consists of the following public fields:
CompressionLevel | The compression level to use when compressing data. |
FileList | A chained list of all files in a compression object. |
Flags | Special flags. |
Header | The first 32 bytes of a compression object's file header. |
Location | Set this field if the compression data originates from, or is to be saved to a file source. |
Output | Resulting messages will be sent to the object referred to in this field. |
Password | Required if the compressed data uses a password. |
Size | The byte size of a compressed file. |
UncompressedSize | Indicates the total uncompressed size of all files in a compression object. |
CompressBuffer() |
Compresses a plain memory area into an empty buffer. |
APTR Input | Pointer to the source data. |
LONG InputSize | Byte length of the source data. |
APTR Output | Pointer to a destination buffer. |
LONG OutputSize | Available space in the destination buffer. |
LONG Result | The size of the compressed data will be returned in this parameter. |
|
This method provides a simple way of compressing a memory area into a
buffer. You need to provide a reference to the source data and a buffer
large enough to accept the compressed information. Generally your
destination buffer should be no smaller than 75% of the size of the
source data. If the destination buffer is not large enough, an error of
ERR_BufferOverflow will be returned. The size of the compressed data
will be returned in the Result parameter.
You can decompress the data that is output by this function by using the
DecompressBuffer method.
ERR_Okay | The data was compressed successfully. The Result parameter indicates the size of the compressed data. |
ERR_Args | Invalid arguments were detected. |
ERR_BufferOverflow | The output buffer is not large enough. |
|
|
CompressFile() |
Add files to a compression object. |
STRING Location | The location of the file(s) to add. |
STRING Path | The path that you want to use for this file when it is added to the compression object. May be NULL for no path. |
|
The CompressFile method is used to add new files and folders to a compression object.
You need to supply the location of the file that you wish to add, as well
as the path that you want the file to use when it is in the compression
object. The Location parameter accepts wildcards, which gives you the ability
to add multiple files in a single function call if you require this
convenience. If you want to add an entire directory, specify its complete
path in the Location parameter and ensure that it ends with a trailing
slash or assignment character. The Path parameter must end with a forward
slash in all cases in order to indicate a directory name, unless your intention
is to archive a single file using a name that is different to its own.
ERR_Okay | The file was added to the compression object. |
ERR_Args | Invalid arguments were detected. |
ERR_File | An error was encountered while trying to open the source file. |
ERR_NoPermission | The CMF_READONLY flag has been set on the compression object. |
|
|
DecompressBuffer() |
Decompresses data originating from the CompressBuffer method. |
APTR Input | Pointer to the compressed data. |
APTR Output | Pointer to the decompression buffer. |
LONG OutputSize | Size of the decompression buffer. |
LONG Result | The amount of bytes decompressed will be returned in this parameter. |
|
This method is used to decompress data that has been packed using the
CompressBuffer method. You need to provide
a pointer to the compressed information and an output buffer large enough to
accept the decompressed information. If the output buffer is not large enough
to contain the data, the method will write out as much information as it can
and then return with an error code of ERR_BufferOverflow.
ERR_Okay | The data was decompressed successfully. |
ERR_Args | Invalid arguments were detected. |
ERR_BufferOverflow | The output buffer is not large enough to hold the decompressed information. |
|
|
DecompressFile() |
Extracts one or more files from a compression object. |
STRING Path | The full path name of the file to extract from the archive. |
STRING Destination | The destination to extract the file to. |
LONG Flags | Optional flags. |
|
Use the DecompressFile method to decompress a file or files to a destination
directory. You need to know the exact path name of the file that you want
to extract, unless you wish to use wildcards. A single asterisk in the Path
parameter will extract all files in a compression object.
When specifing the Destination parameter, it is recommended that you
specify a directory location by using a forward slash at the end of the
string. Otherwise the Destination will be interpreted as a specific file
name. If the destination file already exists, it will be overwritten
by the decompressed data.
ERR_Okay | The file was successfully extracted. |
ERR_Args | Invalid arguments were detected. |
ERR_File | A destination file could not be created. |
ERR_Seek | A seek error occurred |
ERR_Write | Failed to write uncompressed information to a destination file. |
ERR_Cancelled | The decompression process was cancelled by the feedback mechanism. |
ERR_Failed | General decompression error. |
|
|
RemoveFile() |
Deletes one or more files from a compression object. |
STRING Path | The full path name of the file to delete from the archive. |
|
This method deletes compressed files from a compression object. If the
file is in a directory then you must specify the complete path in conjunction
with the file name. Wild cards are accepted if you want to delete multiple
files. A Path setting of "*" will delete an archive's entire
contents, while a more conservative Path of "documents/ *" would
delete all files and directories under the documents path. Directories
can be declared using either the back-slash or the forward-slash
characters.
Depending on internal optimisation techniques, the compressed file may not
shrink from deletions until the compression object is closed or the Flush
action is called.
ERR_Okay | The file was successfully deleted. |
ERR_Args | Invalid arguments were detected. |
|
|
Field: | CompressionLevel |
Short: | The compression level to use when compressing data. |
Type: | LONG |
Status: | Read/Write |
The level of compression that is used when compressing data is determined
by the value in this field. Values range between 0 for no compression and
100 for maximum compression. The speed of compression decreases with higher
values but this will give you improved size reduction.
|
|
Field: | FileList |
Short: | A chained list of all files in a compression object. |
Type: | struct CompressedFile * |
Status: | Read |
The FileList field provides a list of all the files that are contained
in a compresion object, including details such as the date and original
size of each file. The FileList structure is arranged as follows:
struct CompressedFile {
struct CompressedFile *Next;
struct CompressedFile *Prev;
STRING Name;
ULONG CompressedSize;
ULONG OriginalSize;
LONG Year;
UBYTE Month;
UBYTE Day;
UBYTE Hour;
UBYTE Minute;
};
The field names are self explanatory. To peruse the file list, use the
Next and Prev fields to move between each record. The list ends when the
Next field is set to NULL and the first record is indicated with a Prev
field of NULL.
|
|
Field: | Flags |
Short: | Special flags. |
Type: | LONG |
Status: | Read/Init |
You can specify flags in this field that will affect the way that a
compression object is managed. Valid flags are:
PASSWORD | This flag is automatically set when it is possible to detect compression files that have been encrypted. You can test it to see if a compression object requires a password to decompress the data. |
NEW | If a compression file is being created from scratch (i.e. you will not be loading any compression data), set the NEW flag so that the initialisation process will create a compression file from scratch. |
READONLY | If you are opening an existing compression file and do not intend to add new files to it, we recommend setting the READONLY flag. If this flag is not set, opening the compression file is more likely to fail if the user does not have write access to it. |
|
|
Field: | Header |
Short: | The first 32 bytes of a compression object's file header. |
Type: | UBYTE * |
Status: | Read |
This field is only of use to sub-classes that need to examine the first
32 bytes of a compressed file's header.
|
|
Field: | Location |
Synonyms: | Src |
Short: | Set this field if the compression data originates from, or is to be saved to a file source. |
Type: | STRING |
Status: | Read/Write |
When using a compression object to load or create a new compressed file,
you must set the Location field. If for example you wish to examine the
contents of a zip file in the root directory, you might set this field to
"athene:data.zip".
|
|
Field: | Output |
Short: | Resulting messages will be sent to the object referred to in this field. |
Type: | OBJECTID |
Status: | Read/Write |
If this field is set to a valid ObjectID, text messages will be sent to
that object when the compression object is used. This can be helpful for
notifying the user of the results of compression, decompression and removal
of files.
The object receiving the message must be capable of understanding text
sent via data channels. In most cases it is recommended that a Text
object is used for this purpose.
|
|
Field: | Password |
Short: | Required if the compressed data uses a password. |
Type: | STRING |
Status: | Get/Set |
If you would like to set a Password for a new compression object, or if
an existing compression object requires a password, you will need to set the
Password field. The string that you supply must be null-terminated and not
more than 128 bytes in length.
It is recommended that you set the Password before or immediately after
initialisation. If want to change the password or add a password to an
existing compression object, you will need to create a new compresion object
and transfer the existing data across to it.
|
|
Field: | Size |
Short: | The byte size of a compressed file. |
Type: | LARGE |
Status: | Get |
You can learn the compressed size of a compression object's associated
data file by reading the Size field. The total includes the size of each
compressed file as well as the size of headers and other associated data
that may be included in the archive.
|
|
Field: | UncompressedSize |
Short: | Indicates the total uncompressed size of all files in a compression object. |
Type: | LARGE |
Status: | Get |
If you would like to know the total number of bytes that have been
compressed into a compression object, read this field. This will tell you
the maximium byte count used if every file were to be decompressed. Header
and tail information that may identify the compressed data is not included
in the total.
|
|