Compression

The following is a description of the aPLib compression functionality.

Compression Functions

size_t aP_pack( const void *source,
                void *destination,
                size_t length,
                void *workmem,
                int (*callback)(size_tsize_tsize_tvoid *),
                void *cbparam );

Compresses length bytes of data from source[] into destination[], using workmem[] for temporary storage.

The destination[] buffer should be large enough to hold aP_max_packed_size(length) bytes.

The workmem[] buffer should be aP_workmem_size(length) bytes large.

The callback function, callback, must take four parameters. The first is length, the second is the number of input bytes that has been compressed, the third is how many output bytes they have been compressed to, and the fourth is cbparam. This function is called every 128th time the main compression loop is run. If you do not have a callback, use NULL instead. If the callback returns a non-zero value then aP_pack will continue compressing -- if it returns zero, aP_pack will stop and return APLIB_ERROR.

Parameters:
source - pointer to the data to be compressed.
destination - pointer to where the compressed data should be stored.
length - the length of the uncompressed data in bytes.
workmem - pointer to the work memory which is used during compression.
callback - pointer to the callback function (or NULL).
cbparam - callback argument.
Returns:
the length of the compressed data, or APLIB_ERROR on error.
 
size_t aP_workmem_size( size_t input_size );

Computes the required size of the workmem[] buffer used by aP_pack for compressing input_size bytes of data.

The current code always returns 640k (640*1024).

Parameters:
input_size - the length of the uncompressed data in bytes.
Returns:
the required length of the work buffer.
 
size_t aP_max_packed_size( size_t input_size );

Computes the maximum possible compressed size possible when compressing input_size bytes of incompressible data.

The current code returns (input_size + (input_size / 8) + 64).

Parameters:
input_size - the length of the uncompressed data in bytes.
Returns:
the maximum possible size of the compressed data.
 

Safe Wrapper Functions

size_t aPsafe_pack( const void *source,
                    void *destination,
                    size_t length,
                    void *workmem,
                    int (*callback)(size_tsize_tsize_tvoid *),


                    void *cbparam );

Wrapper function for aP_pack, which adds a header to the compressed data containing the length of the original data, and CRC32 checksums of the original and compressed data.

Parameters:
source - pointer to the data to be compressed.
destination - pointer to where the compressed data should be stored.
length - the length of the uncompressed data in bytes.
workmem - pointer to the work memory which is used during compression.
callback - pointer to the callback function (or NULL).
cbparam - callback argument.
Returns:
the length of the compressed data, or APLIB_ERROR on error.
See Also:
aP_pack
 

Example

   /* allocate workmem and destination memory */
   char *workmem    = malloc(aP_workmem_size(length));
   char *compressed = malloc(aP_max_packed_size(length));

   /* compress data[] to compressed[] */
   size_t outlength = aPsafe_pack(data, compressed, length, workmem, NULL, NULL);

   /* if APLIB_ERROR is returned, and error occured */
   if (outlength == APLIB_ERROR)
   {
      printf("An error occured!\n");
   } else {
      printf("Compressed %u bytes to %u bytes\n", length, outlength);
   }