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

codec	A codec
data	User-supplied data

Definition at line 97 of file codec.h.

Enumeration Type Documentation

enum SquashCodecInfo

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

	codec	The codec to use
[out]	compressed	Location to store the compressed data
[in,out]	compressed_length	Location storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
	uncompressed	The uncompressed data
	uncompressed_length	Length 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

	codec	The codec to use
[out]	compressed	Location to store the compressed data
[in,out]	compressed_length	Location storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
	uncompressed	The uncompressed data
	uncompressed_length	Length of the uncompressed data (in bytes)
	options	Compression 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

codec	The codec
stream_type	The 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

codec	The codec
stream_type	The direction of the stream
options	The 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

	codec	The codec to use
[out]	decompressed	The decompressed data
[in,out]	decompressed_length	Length of the decompressed data (in bytes)
	compressed	Location to store the compressed data
[in,out]	compressed_length	Location 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

	codec	The codec to use
[out]	decompressed	Location to store the decompressed data
[in,out]	decompressed_length	Location storing the size of the decompressed buffer on input, replaced with the actual size of the decompressed data
	compressed	The compressed data
	compressed_length	Length of the compressed data (in bytes)
	options	Compression 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

codec The 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

codec The 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

codec The 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

codec	The codec
uncompressed_length	Size 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

codec The 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

codec	the relevant codec
options	the options instance to retrieve the value from
key	the 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

codec	the relevant codec
options	the options instance to retrieve the value from
index	the 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

codec The 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

codec	the relevant codec
options	the options instance to retrieve the value from
key	the 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

codec	the relevant codec
options	the options instance to retrieve the value from
index	the 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

codec	the relevant codec
options	the options instance to retrieve the value from
key	the 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

codec	the relevant codec
options	the options instance to retrieve the value from
index	the 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

codec	the relevant codec
options	the options instance to retrieve the value from
key	the 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

codec	the relevant codec
options	the options instance to retrieve the value from
index	the 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

codec The 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

codec The 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

codec	The codec
compressed	The compressed data
compressed_length	The 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

codec The codec.

Returns: A status code.

Return values

SQUASH_OK	Codec successfully initialized.
SQUASH_UNABLE_TO_LOAD	Failed 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

	codec	The name of the codec to use
[out]	compressed	Location to store the compressed data
[in,out]	compressed_length	Location storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
	uncompressed	The uncompressed data
	uncompressed_length	Length 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

	codec	The name of the codec to use
[out]	compressed	Location to store the compressed data
[in,out]	compressed_length	Location storing the size of the compressed buffer on input, replaced with the actual size of the compressed data
	uncompressed	The uncompressed data
	uncompressed_length	Length of the uncompressed data (in bytes)
	options	Compression 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

	codec	The name of the codec to use
[out]	decompressed	Location to store the decompressed data
[in,out]	decompressed_length	Location storing the size of the decompressed buffer on input, replaced with the actual size of the decompressed data
	compressed	The compressed data
	compressed_length	Length 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

	codec	The name of the codec to use
[out]	decompressed	Location to store the decompressed data
[in,out]	decompressed_length	Location storing the size of the decompressed buffer on input, replaced with the actual size of the decompressed data
	compressed	The compressed data
	compressed_length	Length of the compressed data (in bytes)
	options	Decompression 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

codec The 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

codec	The name of the codec
uncompressed_length	Size 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

codec name of the codec

Returns: a list of options, terminated by an option with a NULL name

Definition at line 1044 of file codec.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation