This method provides a simple way of compressing a memory area into a buffer. It requires a reference to the source data and a buffer large enough to accept the compressed information. Generally the 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.

To decompress the data that is output by this function, use the DecompressBuffer() method.

The compression method used to compress the data will be identified in the first 32 bits of output, for example, ZLIB. The following 32 bits will indicate the length of the compressed data section, followed by the data itself.

Error Codes

The CompressFile method is used to add new files and folders to a compression object. The client must supply the Location of the file to compress, as well as the Path that is prefixed to the file name when it is in the compression object. The Location parameter accepts wildcards, allowing multiple files to be processed in a single function call.

To compress all contents of a folder, specify its path in the Location parameter and ensure that it is fully qualified by appending a forward slash or colon character.

The Path parameter must include a trailing slash when targeting a folder, otherwise the source file will be renamed to suit the target path. If the Path starts with a forward slash and the source is a folder, the name of that folder will be used in the target path for the compressed files and folders.

Error Codes

Use the CompressStream method to compress incoming streams of data whilst using a minimal amount of memory. The compression process is handled in three phases of Start, Compress and End. The methods provided for each phase are CompressStreamStart(), CompressStream() and CompressStreamEnd().

A compression object can manage only one compression stream at any given time. If it is necessary to compress multiple streams at once, create a compression object for each individual stream.

No meta-information is written to the stream, so the client will need a way to record the total number of bytes that have been output during the compression process. This value must be stored somewhere in order to decompress the stream correctly. There is also no header information recorded to identify the type of algorithm used to compress the stream. We recommend that the compression object's sub-class ID is stored for future reference.

The following C code illustrates a simple means of compressing a file to another file using a stream:

if (auto error = mtCompressStreamStart(compress); error IS ERR::Okay) {
   LONG len;
   LONG cmpsize = 0;
   UBYTE input[4096];
   while ((error = acRead(file, input, sizeof(input), &len)) IS ERR::Okay) {
      if (!len) break; // No more data to read.

      error = mtCompressStream(compress, input, len, &callback, NULL, 0);
      if (error != ERR::Okay) break;

      if (result > 0) {
         cmpsize += result;
         error = acWrite(outfile, output, result, &len);
         if (error != ERR::Okay) break;
      }
   }

   if (error IS ERR::Okay) {
      if ((error = mtCompressStreamEnd(compress, NULL, 0)) IS ERR::Okay) {
         cmpsize += result;
         error = acWrite(outfile, output, result, &len);
      }
   }
}

Please note that, depending on the type of algorithm, this method will not always write data to the output buffer. The algorithm may store a copy of the input and wait for more data for efficiency reasons. Any unwritten data will be resolved when the stream is terminated with CompressStreamEnd(). To check if data was output by this function, either set a flag in the callback function or compare the TotalOutput value to its original setting before CompressStream was called.

Error Codes

To end the compression process, this method must be called to write any final blocks of data and remove the resources that were allocated.

The expected format of the Callback function is specified in the CompressStream() method.

Error Codes

The level of compression is determined by the CompressionLevel field value.

Error Codes

This method is used to decompress data that has been packed using the CompressBuffer() method. A pointer to the compressed data and an output buffer large enough to contain the decompressed data are required. 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.

Error Codes

Use the DecompressFile() method to decompress a file or files to a destination folder. The exact path name of the compressed file is required for extraction unless using wildcards. A single asterisk in the Path parameter will extract all files in a compression object.

When specifying the Dest parameter, it is recommended that you specify a folder location by using a forward slash at the end of the string. If this is omitted, the destination will be interpreted as a file name. If the destination file already exists, it will be overwritten by the decompressed data.

This method sends feedback at regular intervals during decompression. For further information on receiving feedback, please refer to the Feedback field.

Error Codes

The DecompressObject method will decompress a file to a target object, using a series of Write() calls.

This method sends feedback at regular intervals during decompression. For further information on receiving feedback, please refer to the Feedback field.

Note that if decompressing to a File object, the seek position will point to the end of the file after this method returns. Reset the seek position to zero if the decompressed data needs to be read back.

Error Codes

Call DecompressStream repeatedly to decompress a data stream and process the results in a callback routine. The client will need to provide a pointer to the data in the Input parameter and indicate its size in Length. The decompression routine will call the routine that was specified in Callback for each block that is decompressed.

The format of the Callback routine is ERR Function(*Compression, APTR Buffer, LONG Length)

The Buffer will refer to the start of the decompressed data and its size will be indicated in Length. If the Callback routine returns an error of any kind, the decompression process will be stopped and the error code will be immediately returned by the method.

Optionally, the client can specify an output buffer in the Output parameter. This can be a valuable optimisation technique, as it will eliminate the need to copy data out of the compression object's internal buffer.

When there is no more data in the decompression stream or if an error has occurred, the client must call DecompressStreamEnd().

Error Codes

To end the decompression process, this method must be called to write any final blocks of data and remove the resources that were allocated during decompression.

Error Codes

Use the DecompressStreamStart method to initialise a new decompression stream. No parameters are required.

If a decompression stream is already active at the time that this method is called, all resources associated with that stream will be deallocated so that the new stream can be initiated.

To decompress the data stream, follow this call with repeated calls to DecompressStream() until all the data has been processed, then call DecompressStreamEnd().

Error Codes

Use the Find() method to search for a specific item in an archive. The algorithm will return the first item that matches the Path string in conjunction with the Case and Wildcard options.

If successful, the discovered item is returned as a !CompressedItem. The result is temporary and values will be discarded on the next call to this method. If persistent values are required, copy the resulting structure immediately after the call.

Error Codes

This method deletes compressed files from a compression object. If the file is in a folder then the client 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.

Error Codes

Use the Scan() method to search an archive's list of items. Optional filtering can be applied using the Folder parameter to limit results to those within a folder, and Filter parameter to apply wildcard matching to item names. Each item that is discovered during the scan will be passed to the function referenced in the Callback parameter. If the Callback function returns ERR::Terminate, the scan will stop immediately. The prototype of the Callback function is ERR Function(*Compression, *CompressedItem).

The CompressedItem structure consists of the following fields:

To search for a single item with a path and name already known, use the Find() method instead.

Error Codes