Squash  0.7.0
Data Structures | Macros | Typedefs | Enumerations | Enumerator | Functions
SquashCodec

A compression/decompression codec. More...

Data Structures

struct  SquashCodec
 A compression/decompression codec. More...
 

Macros

#define SQUASH_CODEC_INFO_INVALID   ((SquashCodecInfo) 0)
 Invalid codec.
 

Typedefs

typedef void(* SquashCodecForeachFunc) (SquashCodec *codec, void *data)
 Squashlback to be invoked on each SquashCodec in a set. More...
 

Enumerations

enum  SquashCodecInfo {
  SQUASH_CODEC_INFO_CAN_FLUSH = 1 << 0, SQUASH_CODEC_INFO_RUN_IN_THREAD = 1 << 1, SQUASH_CODEC_INFO_DECOMPRESS_SAFE = 1 << 2, SQUASH_CODEC_INFO_AUTO_MASK = 0x00ff0000,
  SQUASH_CODEC_INFO_VALID = 1 << 16, SQUASH_CODEC_INFO_KNOWS_UNCOMPRESSED_SIZE = 1 << 17, SQUASH_CODEC_INFO_NATIVE_STREAMING = 1 << 18, SQUASH_CODEC_INFO_MASK = 0xffffffff
}
 Information about the codec. More...
 

Functions

const char * squash_codec_get_name (SquashCodec *codec)
 Get the name of a SquashCodec. More...
 
unsigned int squash_codec_get_priority (SquashCodec *codec)
 Get the priority of a SquashCodec. More...
 
SquashPlugin * squash_codec_get_plugin (SquashCodec *codec)
 Get the plugin associated with a codec. More...
 
SquashStatus squash_codec_init (SquashCodec *codec)
 Initialize a codec. More...
 
SquashCodecImpl * squash_codec_get_impl (SquashCodec *codec)
 Get the codec's function table. More...
 
size_t squash_codec_get_uncompressed_size (SquashCodec *codec, size_t compressed_length, const uint8_t compressed[SQUASH_ARRAY_PARAM(compressed_length)])
 Get the uncompressed size of the compressed buffer. More...
 
size_t squash_get_uncompressed_size (const char *codec, size_t compressed_length, const uint8_t compressed[SQUASH_ARRAY_PARAM(compressed_length)])
 
size_t squash_codec_get_max_compressed_size (SquashCodec *codec, size_t uncompressed_length)
 Get the maximum buffer size necessary to store compressed data. More...
 
size_t squash_get_max_compressed_size (const char *codec, size_t uncompressed_length)
 Get the maximum buffer size necessary to store compressed data. More...
 
SquashStream * squash_codec_create_stream_with_options (SquashCodec *codec, SquashStreamType stream_type, SquashOptions *options)
 Create a new stream with existing SquashOptions. More...
 
SquashStream * squash_codec_create_stream (SquashCodec *codec, SquashStreamType stream_type,...)
 Create a new stream with existing SquashOptions. More...
 
SquashStatus squash_codec_compress_with_options (SquashCodec *codec, size_t *compressed_length, uint8_t compressed[SQUASH_ARRAY_PARAM(*compressed_length)], size_t uncompressed_length, const uint8_t uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)], SquashOptions *options)
 Compress a buffer with an existing SquashOptions. More...
 
SquashStatus squash_codec_compress (SquashCodec *codec, size_t *compressed_length, uint8_t compressed[SQUASH_ARRAY_PARAM(*compressed_length)], size_t uncompressed_length, const uint8_t uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)],...)
 Compress a buffer. More...
 
SquashStatus squash_codec_decompress_with_options (SquashCodec *codec, size_t *decompressed_length, uint8_t decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)], size_t compressed_length, const uint8_t compressed[SQUASH_ARRAY_PARAM(compressed_length)], SquashOptions *options)
 Decompress a buffer with an existing SquashOptions. More...
 
SquashStatus squash_codec_decompress (SquashCodec *codec, size_t *decompressed_length, uint8_t decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)], size_t compressed_length, const uint8_t compressed[SQUASH_ARRAY_PARAM(compressed_length)],...)
 Decompress a buffer. More...
 
SquashStatus squash_compress (const char *codec, size_t *compressed_length, uint8_t compressed[SQUASH_ARRAY_PARAM(*compressed_length)], size_t uncompressed_length, const uint8_t uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)],...)
 Compress a buffer. More...
 
SquashStatus squash_compress_with_options (const char *codec, size_t *compressed_length, uint8_t compressed[SQUASH_ARRAY_PARAM(*compressed_length)], size_t uncompressed_length, const uint8_t uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)], SquashOptions *options)
 Compress a buffer with an existing SquashOptions. More...
 
SquashStatus squash_decompress (const char *codec, size_t *decompressed_length, uint8_t decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)], size_t compressed_length, const uint8_t compressed[SQUASH_ARRAY_PARAM(compressed_length)],...)
 Decompress a buffer with an existing SquashOptions. More...
 
SquashStatus squash_decompress_with_options (const char *codec, size_t *decompressed_length, uint8_t decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)], size_t compressed_length, const uint8_t compressed[SQUASH_ARRAY_PARAM(compressed_length)], SquashOptions *options)
 Decompress a buffer. More...
 
const char * squash_codec_get_extension (SquashCodec *codec)
 Get the codec's extension. More...
 
SquashCodecInfo squash_codec_get_info (SquashCodec *codec)
 Get a bitmask of information about the codec. More...
 
SquashCodecInfo squash_get_info (const char *codec)
 Get a bitmask of information about the codec. More...
 
const SquashOptionInfo * squash_codec_get_option_info (SquashCodec *codec)
 Get a list of options applicable to the codec. More...
 
const SquashOptionInfo * squash_get_option_info (const char *codec)
 Get a list of options applicable to the codec. More...
 
const char * squash_codec_get_option_string (SquashCodec *codec, SquashOptions *options, const char *key)
 Get the string value for an option. More...
 
const char * squash_codec_get_option_string_index (SquashCodec *codec, SquashOptions *options, size_t index)
 Get the string value for an option by index. More...
 
bool squash_codec_get_option_bool (SquashCodec *codec, SquashOptions *options, const char *key)
 Get the boolean value for an option. More...
 
bool squash_codec_get_option_bool_index (SquashCodec *codec, SquashOptions *options, size_t index)
 Get the boolean value for an option by index. More...
 
int squash_codec_get_option_int (SquashCodec *codec, SquashOptions *options, const char *key)
 Get the integer value for an option. More...
 
int squash_codec_get_option_int_index (SquashCodec *codec, SquashOptions *options, size_t index)
 Get the integer value for an option by index. More...
 
size_t squash_codec_get_option_size (SquashCodec *codec, SquashOptions *options, const char *key)
 Get the size value for an option. More...
 
size_t squash_codec_get_option_size_index (SquashCodec *codec, SquashOptions *options, size_t index)
 Get the size value for an option by index. More...
 

Detailed Description

A compression/decompression codec.

Typedef Documentation

SquashCodecForeachFunc

Squashlback to be invoked on each SquashCodec in a set.

Parameters
codecA codec
dataUser-supplied data

Definition at line 97 of file codec.h.

Enumeration Type Documentation

Information about the codec.

This is a bitmask describing characteristics and features of the codec.

Enumerator
SQUASH_CODEC_INFO_CAN_FLUSH 

Flushing is supported.

SQUASH_CODEC_INFO_RUN_IN_THREAD 

The data is processed in a background thread.

This is an implementation detail for Squash—it should not be important for anyone but plugin authors or Squash maintainers.

SQUASH_CODEC_INFO_DECOMPRESS_SAFE 

The codec will not write outside of the buffer supplied to it during decompression.

SQUASH_CODEC_INFO_AUTO_MASK 

Mask of flags which are automatically set based on which callbacks are provided.

SQUASH_CODEC_INFO_VALID 

The codec is valid.

SQUASH_CODEC_INFO_KNOWS_UNCOMPRESSED_SIZE 

The compressed data encodes the length of the uncompressed data without having to decompress it.

SQUASH_CODEC_INFO_NATIVE_STREAMING 

The codec natively supports a streaming interface.

Definition at line 36 of file codec.h.

Function Documentation

SquashStatus squash_codec_compress ( SquashCodec *  codec,
size_t *  compressed_length,
uint8_t  compressed[SQUASH_ARRAY_PARAM(*compressed_length)],
size_t  uncompressed_length,
const uint8_t  uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)],
  ... 
)

Compress a buffer.

Parameters
codecThe codec to use
[out]compressedLocation to store the compressed data
[in,out]compressed_lengthLocation storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
uncompressedThe uncompressed data
uncompressed_lengthLength of the uncompressed data (in bytes)
...A variadic list of key/value option pairs, followed by NULL
Returns
A status code

Definition at line 663 of file codec.c.

SquashStatus squash_codec_compress_with_options ( SquashCodec *  codec,
size_t *  compressed_length,
uint8_t  compressed[SQUASH_ARRAY_PARAM(*compressed_length)],
size_t  uncompressed_length,
const uint8_t  uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)],
SquashOptions *  options 
)

Compress a buffer with an existing SquashOptions.

Parameters
codecThe codec to use
[out]compressedLocation to store the compressed data
[in,out]compressed_lengthLocation storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
uncompressedThe uncompressed data
uncompressed_lengthLength of the uncompressed data (in bytes)
optionsCompression options
Returns
A status code

Definition at line 545 of file codec.c.

SquashStream* squash_codec_create_stream ( SquashCodec *  codec,
SquashStreamType  stream_type,
  ... 
)

Create a new stream with existing SquashOptions.

Parameters
codecThe codec
stream_typeThe direction of the stream
...A variadic list of key/value option pairs, followed by NULL
Returns
A new stream, or NULL on failure

Definition at line 517 of file codec.c.

SquashStream* squash_codec_create_stream_with_options ( SquashCodec *  codec,
SquashStreamType  stream_type,
SquashOptions *  options 
)

Create a new stream with existing SquashOptions.

Parameters
codecThe codec
stream_typeThe direction of the stream
optionsThe options for the stream, or NULL to use the defaults
Returns
A new stream, or NULL on failure

Definition at line 485 of file codec.c.

SquashStatus squash_codec_decompress ( SquashCodec *  codec,
size_t *  decompressed_length,
uint8_t  decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)],
size_t  compressed_length,
const uint8_t  compressed[SQUASH_ARRAY_PARAM(compressed_length)],
  ... 
)

Decompress a buffer.

Parameters
codecThe codec to use
[out]decompressedThe decompressed data
[in,out]decompressed_lengthLength of the decompressed data (in bytes)
compressedLocation to store the compressed data
[in,out]compressed_lengthLocation storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
...A variadic list of key/value option pairs, followed by NULL
Returns
A status code

Definition at line 772 of file codec.c.

SquashStatus squash_codec_decompress_with_options ( SquashCodec *  codec,
size_t *  decompressed_length,
uint8_t  decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)],
size_t  compressed_length,
const uint8_t  compressed[SQUASH_ARRAY_PARAM(compressed_length)],
SquashOptions *  options 
)

Decompress a buffer with an existing SquashOptions.

Parameters
codecThe codec to use
[out]decompressedLocation to store the decompressed data
[in,out]decompressed_lengthLocation storing the size of the decompressed buffer on input, replaced with the actual size of the decompressed data
compressedThe compressed data
compressed_lengthLength of the compressed data (in bytes)
optionsCompression options
Returns
A status code

Definition at line 698 of file codec.c.

const char* squash_codec_get_extension ( SquashCodec *  codec)

Get the codec's extension.

Parameters
codecThe codec
Returns
The extension, or NULL if none is known

Definition at line 979 of file codec.c.

SquashCodecImpl* squash_codec_get_impl ( SquashCodec *  codec)

Get the codec's function table.

Parameters
codecThe codec.
Returns
The function table.

Definition at line 358 of file codec.c.

SquashCodecInfo squash_codec_get_info ( SquashCodec *  codec)

Get a bitmask of information about the codec.

Parameters
codecThe codec
Returns
the codec info

Definition at line 1002 of file codec.c.

size_t squash_codec_get_max_compressed_size ( SquashCodec *  codec,
size_t  uncompressed_length 
)

Get the maximum buffer size necessary to store compressed data.

Typically the return value will be some percentage larger than the uncompressed length, plus a few bytes. For example, for bzip2 it is the uncompressed length plus 1%, plus an additional 600 bytes.

Warning
The result of this function is not guaranteed to be correct for use with the SquashStream API—it should only be used with the single-squashl buffer-to-buffer functions such as squash_codec_compress and squash_codec_compress_with_options.
Parameters
codecThe codec
uncompressed_lengthSize of the uncompressed data in bytes
Returns
The maximum size required to store a compressed buffer representing uncompressed_length of uncompressed data.

Definition at line 433 of file codec.c.

const char* squash_codec_get_name ( SquashCodec *  codec)

Get the name of a SquashCodec.

Parameters
codecThe codec
Returns
The codec's name

Definition at line 298 of file codec.c.

bool squash_codec_get_option_bool ( SquashCodec *  codec,
SquashOptions *  options,
const char *  key 
)

Get the boolean value for an option.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not a boolean the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
keythe name of the option to retrieve the value of
Returns
the value of the option

Definition at line 1141 of file codec.c.

bool squash_codec_get_option_bool_index ( SquashCodec *  codec,
SquashOptions *  options,
size_t  index 
)

Get the boolean value for an option by index.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not a boolean the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
indexthe index of the option to retrieve the value of
Returns
the value of the option

Definition at line 1167 of file codec.c.

const SquashOptionInfo* squash_codec_get_option_info ( SquashCodec *  codec)

Get a list of options applicable to the codec.

Parameters
codecThe codec
Returns
a list of options, terminated by an option with a NULL name

Definition at line 1032 of file codec.c.

int squash_codec_get_option_int ( SquashCodec *  codec,
SquashOptions *  options,
const char *  key 
)

Get the integer value for an option.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not an integer the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
keythe name of the option to retrieve the value of
Returns
the value of the option

Definition at line 1189 of file codec.c.

int squash_codec_get_option_int_index ( SquashCodec *  codec,
SquashOptions *  options,
size_t  index 
)

Get the integer value for an option by index.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not an integer the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
indexthe index of the option to retrieve the value of
Returns
the value of the option

Definition at line 1217 of file codec.c.

size_t squash_codec_get_option_size ( SquashCodec *  codec,
SquashOptions *  options,
const char *  key 
)

Get the size value for an option.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not a size the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
keythe name of the option to retrieve the value of
Returns
the value of the option

Definition at line 1239 of file codec.c.

size_t squash_codec_get_option_size_index ( SquashCodec *  codec,
SquashOptions *  options,
size_t  index 
)

Get the size value for an option by index.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not a size the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
indexthe index of the option to retrieve the value of
Returns
the value of the option

Definition at line 1266 of file codec.c.

const char* squash_codec_get_option_string ( SquashCodec *  codec,
SquashOptions *  options,
const char *  key 
)

Get the string value for an option.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not a string the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
keythe name of the option to retrieve the value of
Returns
the value of the option

Definition at line 1093 of file codec.c.

const char* squash_codec_get_option_string_index ( SquashCodec *  codec,
SquashOptions *  options,
size_t  index 
)

Get the string value for an option by index.

Note that this function will not perform a conversion—if you use it to request the value of an option which is not a string the result is undefined.

Parameters
codecthe relevant codec
optionsthe options instance to retrieve the value from
indexthe index of the option to retrieve the value of
Returns
the value of the option

Definition at line 1119 of file codec.c.

SquashPlugin* squash_codec_get_plugin ( SquashCodec *  codec)

Get the plugin associated with a codec.

Parameters
codecThe codec
Returns
The plugin to which the codec belongs

Definition at line 324 of file codec.c.

unsigned int squash_codec_get_priority ( SquashCodec *  codec)

Get the priority of a SquashCodec.

Parameters
codecThe codec
Returns
The codec's priority

Definition at line 311 of file codec.c.

size_t squash_codec_get_uncompressed_size ( SquashCodec *  codec,
size_t  compressed_length,
const uint8_t  compressed[SQUASH_ARRAY_PARAM(compressed_length)] 
)

Get the uncompressed size of the compressed buffer.

This function is only useful for codecs with the SQUASH_CODEC_INFO_KNOWS_UNCOMPRESSED_SIZE flag set. For situations where the codec does not know the uncompressed size, 0 will be returned.

Parameters
codecThe codec
compressedThe compressed data
compressed_lengthThe length of the compressed data
Returns
The uncompressed size, or 0 if unknown

Definition at line 383 of file codec.c.

SquashStatus squash_codec_init ( SquashCodec *  codec)

Initialize a codec.

Note
This function is generally only useful inside of a callback passed to squash_foreach_codec or squash_plugin_foreach_codec. Every other way to get a codec (such as squash_get_codec or squash_plugin_get_codec) will initialize the codec as well (and return NULL instead of the codec if initialization fails). The foreach functions, however, do not initialize the codec since doing so requires actually loading the plugin.
Parameters
codecThe codec.
Returns
A status code.
Return values
SQUASH_OKCodec successfully initialized.
SQUASH_UNABLE_TO_LOADFailed to load the codec.

Definition at line 347 of file codec.c.

SquashStatus squash_compress ( const char *  codec,
size_t *  compressed_length,
uint8_t  compressed[SQUASH_ARRAY_PARAM(*compressed_length)],
size_t  uncompressed_length,
const uint8_t  uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)],
  ... 
)

Compress a buffer.

Parameters
codecThe name of the codec to use
[out]compressedLocation to store the compressed data
[in,out]compressed_lengthLocation storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
uncompressedThe uncompressed data
uncompressed_lengthLength of the uncompressed data (in bytes)
...A variadic list of key/value option pairs, followed by NULL
Returns
A status code
Examples:
simple.c.

Definition at line 811 of file codec.c.

SquashStatus squash_compress_with_options ( const char *  codec,
size_t *  compressed_length,
uint8_t  compressed[SQUASH_ARRAY_PARAM(*compressed_length)],
size_t  uncompressed_length,
const uint8_t  uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)],
SquashOptions *  options 
)

Compress a buffer with an existing SquashOptions.

Parameters
codecThe name of the codec to use
[out]compressedLocation to store the compressed data
[in,out]compressed_lengthLocation storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
uncompressedThe uncompressed data
uncompressed_lengthLength of the uncompressed data (in bytes)
optionsCompression options, or NULL to use the defaults
Returns
A status code

Definition at line 848 of file codec.c.

SquashStatus squash_decompress ( const char *  codec,
size_t *  decompressed_length,
uint8_t  decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)],
size_t  compressed_length,
const uint8_t  compressed[SQUASH_ARRAY_PARAM(compressed_length)],
  ... 
)

Decompress a buffer with an existing SquashOptions.

Parameters
codecThe name of the codec to use
[out]decompressedLocation to store the decompressed data
[in,out]decompressed_lengthLocation storing the size of the decompressed buffer on input, replaced with the actual size of the decompressed data
compressedThe compressed data
compressed_lengthLength of the compressed data (in bytes)
...A variadic list of key/value option pairs, followed by NULL
Returns
A status code
Examples:
simple.c.

Definition at line 880 of file codec.c.

SquashStatus squash_decompress_with_options ( const char *  codec,
size_t *  decompressed_length,
uint8_t  decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)],
size_t  compressed_length,
const uint8_t  compressed[SQUASH_ARRAY_PARAM(compressed_length)],
SquashOptions *  options 
)

Decompress a buffer.

Parameters
codecThe name of the codec to use
[out]decompressedLocation to store the decompressed data
[in,out]decompressed_lengthLocation storing the size of the decompressed buffer on input, replaced with the actual size of the decompressed data
compressedThe compressed data
compressed_lengthLength of the compressed data (in bytes)
optionsDecompression options, or NULL to use the defaults
Returns
A status code

Definition at line 916 of file codec.c.

SquashCodecInfo squash_get_info ( const char *  codec)

Get a bitmask of information about the codec.

Parameters
codecThe codec
Returns
the codec info, or SQUASH_CODEC_INFO_INVALID if there is no such codec

Definition at line 1014 of file codec.c.

size_t squash_get_max_compressed_size ( const char *  codec,
size_t  uncompressed_length 
)

Get the maximum buffer size necessary to store compressed data.

Typically the return value will be some percentage larger than the uncompressed length, plus a few bytes. For example, for bzip2 it is the uncompressed length plus 1%, plus an additional 600 bytes.

Warning
The result of this function is not guaranteed to be correct for use with the SquashStream API—it should only be used with the single-squashl buffer-to-buffer functions such as squash_codec_compress and squash_codec_compress_with_options.
Parameters
codecThe name of the codec
uncompressed_lengthSize of the uncompressed data in bytes
Returns
The maximum size required to store a compressed buffer representing uncompressed_length of uncompressed data.
See also
squash_codec_get_max_compressed_size
Examples:
simple.c.

Definition at line 465 of file codec.c.

const SquashOptionInfo* squash_get_option_info ( const char *  codec)

Get a list of options applicable to the codec.

Parameters
codecname of the codec
Returns
a list of options, terminated by an option with a NULL name

Definition at line 1044 of file codec.c.