|
wimlib
|
Macros | |
| #define | WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE 0x80000000 |
Functions | |
| WIMLIBAPI int | wimlib_set_default_compression_level (int ctype, unsigned int compression_level) |
| Set the default compression level for the specified compression type. | |
| WIMLIBAPI uint64_t | wimlib_get_compressor_needed_memory (enum wimlib_compression_type ctype, size_t max_block_size, unsigned int compression_level) |
| Return the approximate number of bytes needed to allocate a compressor with wimlib_create_compressor() for the specified compression type, maximum block size, and compression level. | |
| WIMLIBAPI int | wimlib_create_compressor (enum wimlib_compression_type ctype, size_t max_block_size, unsigned int compression_level, struct wimlib_compressor **compressor_ret) |
| Allocate a compressor for the specified compression type using the specified parameters. | |
| WIMLIBAPI size_t | wimlib_compress (const void *uncompressed_data, size_t uncompressed_size, void *compressed_data, size_t compressed_size_avail, struct wimlib_compressor *compressor) |
| Compress a buffer of data. | |
| WIMLIBAPI void | wimlib_free_compressor (struct wimlib_compressor *compressor) |
| Free a compressor previously allocated with wimlib_create_compressor(). | |
| WIMLIBAPI int | wimlib_create_decompressor (enum wimlib_compression_type ctype, size_t max_block_size, struct wimlib_decompressor **decompressor_ret) |
| Allocate a decompressor for the specified compression type. | |
| WIMLIBAPI int | wimlib_decompress (const void *compressed_data, size_t compressed_size, void *uncompressed_data, size_t uncompressed_size, struct wimlib_decompressor *decompressor) |
| Decompress a buffer of data. | |
| WIMLIBAPI void | wimlib_free_decompressor (struct wimlib_decompressor *decompressor) |
| Free a decompressor previously allocated with wimlib_create_decompressor(). | |
Functions for XPRESS, LZX, and LZMS compression and decompression.
These functions are already used by wimlib internally when appropriate for reading and writing WIM archives. But they are exported and documented so that they can be used in other applications or libraries for general-purpose lossless data compression. They are implemented in highly optimized C code, using state-of-the-art compression techniques. The main limitation is the lack of sliding window support; this has, however, allowed the algorithms to be optimized for block-based compression.
| #define WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE 0x80000000 |
| WIMLIBAPI int wimlib_set_default_compression_level | ( | int | ctype, |
| unsigned int | compression_level ) |
Set the default compression level for the specified compression type.
This is the compression level that wimlib_create_compressor() assumes if it is called with compression_level specified as 0.
wimlib's WIM writing code (e.g. wimlib_write()) will pass 0 to wimlib_create_compressor() internally. Therefore, calling this function will affect the compression level of any data later written to WIM files using the specified compression type.
The initial state, before this function is called, is that all compression types have a default compression level of 50.
| ctype | Compression type for which to set the default compression level, as one of the wimlib_compression_type constants. Or, if this is the special value -1, the default compression levels for all compression types will be set. |
| compression_level | The default compression level to set. If 0, the "default default" level of 50 is restored. Otherwise, a higher value indicates higher compression, whereas a lower value indicates lower compression. See wimlib_create_compressor() for more information. |
| WIMLIB_ERR_INVALID_COMPRESSION_TYPE | ctype was neither a supported compression type nor -1. |
| WIMLIBAPI uint64_t wimlib_get_compressor_needed_memory | ( | enum wimlib_compression_type | ctype, |
| size_t | max_block_size, | ||
| unsigned int | compression_level ) |
Return the approximate number of bytes needed to allocate a compressor with wimlib_create_compressor() for the specified compression type, maximum block size, and compression level.
compression_level may be 0, in which case the current default compression level for ctype is used. Returns 0 if the compression type is invalid, or the max_block_size for that compression type is invalid.
| WIMLIBAPI int wimlib_create_compressor | ( | enum wimlib_compression_type | ctype, |
| size_t | max_block_size, | ||
| unsigned int | compression_level, | ||
| struct wimlib_compressor ** | compressor_ret ) |
Allocate a compressor for the specified compression type using the specified parameters.
This function is part of wimlib's compression API; it is not necessary to call this to process a WIM file.
| ctype | Compression type for which to create the compressor, as one of the wimlib_compression_type constants. |
| max_block_size | The maximum compression block size to support. This specifies the maximum allowed value for the uncompressed_size parameter of wimlib_compress() when called using this compressor. Usually, the amount of memory used by the compressor will scale in proportion to the max_block_size parameter. wimlib_get_compressor_needed_memory() can be used to query the specific amount of memory that will be required. This parameter must be at least 1 and must be less than or equal to a compression-type-specific limit. In general, the same value of max_block_size must be passed to wimlib_create_decompressor() when the data is later decompressed. However, some compression types have looser requirements regarding this. |
| compression_level | The compression level to use. If 0, the default compression level (50, or another value as set through wimlib_set_default_compression_level()) is used. Otherwise, a higher value indicates higher compression. The values are scaled so that 10 is low compression, 50 is medium compression, and 100 is high compression. This is not a percentage; values above 100 are also valid. Using a higher-than-default compression level can result in a better compression ratio, but can significantly reduce performance. Similarly, using a lower-than-default compression level can result in better performance, but can significantly worsen the compression ratio. The exact results will depend heavily on the compression type and what algorithms are implemented for it. If you are considering using a non-default compression level, you should run benchmarks to see if it is worthwhile for your application. The compression level does not affect the format of the compressed data. Therefore, it is a compressor-only parameter and does not need to be passed to the decompressor. Since wimlib v1.8.0, this parameter can be OR-ed with the flag WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE. This creates the compressor in a mode where it is allowed to modify the input buffer. Specifically, in this mode, if compression succeeds, the input buffer may have been modified, whereas if compression does not succeed the input buffer still may have been written to but will have been restored exactly to its original state. This mode is designed to save some memory when using large buffer sizes. |
| compressor_ret | A location into which to return the pointer to the allocated compressor. The allocated compressor can be used for any number of calls to wimlib_compress() before being freed with wimlib_free_compressor(). |
| WIMLIB_ERR_INVALID_COMPRESSION_TYPE | ctype was not a supported compression type. |
| WIMLIB_ERR_INVALID_PARAM | max_block_size was invalid for the compression type, or compressor_ret was NULL. |
| WIMLIB_ERR_NOMEM | Insufficient memory to allocate the compressor. |
| WIMLIBAPI size_t wimlib_compress | ( | const void * | uncompressed_data, |
| size_t | uncompressed_size, | ||
| void * | compressed_data, | ||
| size_t | compressed_size_avail, | ||
| struct wimlib_compressor * | compressor ) |
Compress a buffer of data.
| uncompressed_data | Buffer containing the data to compress. |
| uncompressed_size | Size, in bytes, of the data to compress. This cannot be greater than the max_block_size with which wimlib_create_compressor() was called. (If it is, the data will not be compressed and 0 will be returned.) |
| compressed_data | Buffer into which to write the compressed data. |
| compressed_size_avail | Number of bytes available in compressed_data. |
| compressor | A compressor previously allocated with wimlib_create_compressor(). |
compressed_size_avail or fewer bytes. | WIMLIBAPI void wimlib_free_compressor | ( | struct wimlib_compressor * | compressor | ) |
Free a compressor previously allocated with wimlib_create_compressor().
| compressor | The compressor to free. If NULL, no action is taken. |
| WIMLIBAPI int wimlib_create_decompressor | ( | enum wimlib_compression_type | ctype, |
| size_t | max_block_size, | ||
| struct wimlib_decompressor ** | decompressor_ret ) |
Allocate a decompressor for the specified compression type.
This function is part of wimlib's compression API; it is not necessary to call this to process a WIM file.
| ctype | Compression type for which to create the decompressor, as one of the wimlib_compression_type constants. |
| max_block_size | The maximum compression block size to support. This specifies the maximum allowed value for the uncompressed_size parameter of wimlib_decompress(). In general, this parameter must be the same as the max_block_size that was passed to wimlib_create_compressor() when the data was compressed. However, some compression types have looser requirements regarding this. |
| decompressor_ret | A location into which to return the pointer to the allocated decompressor. The allocated decompressor can be used for any number of calls to wimlib_decompress() before being freed with wimlib_free_decompressor(). |
| WIMLIB_ERR_INVALID_COMPRESSION_TYPE | ctype was not a supported compression type. |
| WIMLIB_ERR_INVALID_PARAM | max_block_size was invalid for the compression type, or decompressor_ret was NULL. |
| WIMLIB_ERR_NOMEM | Insufficient memory to allocate the decompressor. |
| WIMLIBAPI int wimlib_decompress | ( | const void * | compressed_data, |
| size_t | compressed_size, | ||
| void * | uncompressed_data, | ||
| size_t | uncompressed_size, | ||
| struct wimlib_decompressor * | decompressor ) |
Decompress a buffer of data.
| compressed_data | Buffer containing the data to decompress. |
| compressed_size | Size, in bytes, of the data to decompress. |
| uncompressed_data | Buffer into which to write the uncompressed data. |
| uncompressed_size | Size, in bytes, of the data when uncompressed. This cannot exceed the max_block_size with which wimlib_create_decompressor() was called. (If it does, the data will not be decompressed and a nonzero value will be returned.) |
| decompressor | A decompressor previously allocated with wimlib_create_decompressor(). |
No specific error codes are defined; any nonzero value indicates that the decompression failed. This can only occur if the data is truly invalid; there will never be transient errors like "out of memory", for example.
This function requires that the exact uncompressed size of the data be passed as the uncompressed_size parameter. If this is not done correctly, decompression may fail or the data may be decompressed incorrectly.
| WIMLIBAPI void wimlib_free_decompressor | ( | struct wimlib_decompressor * | decompressor | ) |
Free a decompressor previously allocated with wimlib_create_decompressor().
| decompressor | The decompressor to free. If NULL, no action is taken. |
1.10.0