Class Documentation

Name:Compression
Version:1.0
ID:ID_COMPRESSION
Status:Stable
Category:Data
Date:April 2004
Author:Rocklyte Systems, based on work from Jean-loup Gailly and Mark Adler.
Copyright:  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:

CompressBuffer  Compresses a plain memory area into an empty buffer.
CompressFile  Add files to a compression object.
DecompressBuffer  Decompresses data originating from the CompressBuffer method.
DecompressFile  Extracts one or more files from a compression object.
RemoveFile  Deletes one or more files from a compression object.

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.
Method:CompressBuffer()
Short:Compresses a plain memory area into an empty buffer.
Arguments:
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.

Result
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.

Method:CompressFile()
Short:Add files to a compression object.
Arguments:
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.

Result
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.

Method:DecompressBuffer()
Short:Decompresses data originating from the CompressBuffer method.
Arguments:
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.

Result
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.

Method:DecompressFile()
Short:Extracts one or more files from a compression object.
Arguments:
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.

Result
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.

Method:RemoveFile()
Short:Deletes one or more files from a compression object.
Arguments:
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.

Result
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:

FlagDescription
PASSWORDThis 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.
NEWIf 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.
READONLYIf 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.