X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=cf47751ab5bcc218cc0fb54caac004804e7d4f46;hb=9899681e667c07db9a286c38fa76f53cfa726b73;hp=f4b0dc5acdc1762de1ab6ac190d31a2f6a805f61;hpb=239adf84c95212272cef9a1d281bd5b8723ee86d;p=wimlib diff --git a/include/wimlib.h b/include/wimlib.h index f4b0dc5a..cf47751a 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -425,6 +425,13 @@ enum wimlib_compression_type { /** Compressed resources in the WIM use XPRESS compression. */ WIMLIB_COMPRESSION_TYPE_XPRESS = 2, + + /** Compressed resources in the WIM use LZMS compression. Currently, + * wimlib has a decompressor for this format but not a compressor. LZMS + * compression is only compatible with wimlib v1.6.0 and later and with + * WIMGAPI Windows 8 and later (and some restrictions apply on the + * latter). */ + WIMLIB_COMPRESSION_TYPE_LZMS = 3, }; /** @} */ @@ -944,48 +951,64 @@ struct wimlib_wim_info { uint32_t reserved[9]; }; -/** Information about a unique resource in the WIM file. - */ +/** Information about a unique stream in the WIM file. (A stream is the same + * thing as a "resource", except in the case of packed resources.) */ struct wimlib_resource_entry { - /** Uncompressed size of the resource in bytes. */ + /** Uncompressed size of the stream in bytes. */ uint64_t uncompressed_size; - /** Compressed size of the resource in bytes. This will be the same as - * @p uncompressed_size if the resource is uncompressed. */ + /** Compressed size of the stream in bytes. This will be the same as @p + * uncompressed_size if the stream is uncompressed. Or, if @p + * is_packed_streams is 1, this will be 0. */ uint64_t compressed_size; - /** Offset, in bytes, of this resource from the start of the WIM file. + /** Offset, in bytes, of this stream from the start of the WIM file. Or + * if @p packed is 1, then this is actually the offset at which this + * stream begins in the uncompressed contents of the packed resource. */ uint64_t offset; - /** SHA1 message digest of the resource's uncompressed contents. */ + /** SHA1 message digest of the stream's uncompressed contents. */ uint8_t sha1_hash[20]; - /** Which part number of the split WIM this resource is in. This should + /** Which part number of the split WIM this stream is in. This should * be the same as the part number provided by wimlib_get_wim_info(). */ uint32_t part_number; - /** Number of times this resource is referenced over all WIM images. */ + /** Number of times this stream is referenced over all WIM images. */ uint32_t reference_count; - /** 1 if this resource is compressed. */ + /** 1 if this stream is compressed. */ uint32_t is_compressed : 1; - /** 1 if this resource is a metadata resource rather than a file - * resource. */ + /** 1 if this stream is a metadata resource rather than a file resource. + * */ uint32_t is_metadata : 1; uint32_t is_free : 1; uint32_t is_spanned : 1; - /** 1 if this resource was not found in the lookup table of the + /** 1 if this stream was not found in the lookup table of the * ::WIMStruct. This normally implies a missing call to * wimlib_reference_resource_files() or wimlib_reference_resources(). - */ + * */ uint32_t is_missing : 1; - uint32_t reserved_flags : 27; - uint64_t reserved[4]; + /** 1 if this stream is located in a packed resource which may contain + * other streams (all compressed together) as well. */ + uint32_t packed : 1; + + uint32_t reserved_flags : 26; + + /** If @p packed is 1, then this will specify the offset of the packed + * resource in the WIM. */ + uint64_t raw_resource_offset_in_wim; + + /** If @p is_packed_streams is 1, then this will specify the compressed + * size of the packed resource in the WIM. */ + uint64_t raw_resource_compressed_size; + + uint64_t reserved[2]; }; /** A stream of a file in the WIM. */ @@ -1503,6 +1526,12 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_RESERVED 0x00000800 +/** TODO */ +#define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000 + +/** TODO */ +#define WIMLIB_WRITE_FLAG_NO_PACK_STREAMS 0x00002000 + /** @} */ /** @ingroup G_general * @{ */ @@ -2714,6 +2743,45 @@ wimlib_join(const wimlib_tchar * const *swms, int wim_write_flags, wimlib_progress_func_t progress_func); +/** + * @ingroup G_compression + * + * Decompresses a block of LZMS-compressed data. + * + * This function is exported for convenience only and should only be used by + * library clients looking to make use of wimlib's compression code for another + * purpose. + * + * This decompressor only implements "raw" decompression, which decompresses a + * single LZMS-compressed block. This behavior is the same as that of + * Decompress() in the Windows 8 compression API when using a compression handle + * created with CreateDecompressor() with the Algorithm parameter specified as + * COMPRESS_ALGORITHM_LZMS | COMPRESS_RAW. Presumably, non-raw LZMS data + * is a container format from which the locations and sizes (both compressed and + * uncompressed) of the constituent blocks can be determined. + * + * This function should not be called for blocks with compressed size equal to + * uncompressed size, since such blocks are actually stored uncompressed. + * + * @param compressed_data + * Pointer to the compressed data. + * + * @param compressed_len + * Length of the compressed data, in bytes. + * + * @param uncompressed_data + * Pointer to the buffer into which to write the uncompressed data. + * + * @param uncompressed_len + * Length of the uncompressed data. + * + * @return + * 0 on success; non-zero on failure. + */ +extern int +wimlib_lzms_decompress(const void *compressed_data, unsigned compressed_len, + void *uncompressed_data, unsigned uncompressed_len); + /** * @ingroup G_compression * @@ -2760,6 +2828,10 @@ wimlib_lzx_compress2(const void *chunk, unsigned chunk_size, void *out, * library clients looking to make use of wimlib's compression code for another * purpose. * + * @param window_size + * Size of the LZX window. Must be a power of 2 between 2^15 and 2^21, + * inclusively. + * * @param params * Compression parameters to use, or @c NULL to use the default parameters. * @@ -2773,12 +2845,13 @@ wimlib_lzx_compress2(const void *chunk, unsigned chunk_size, void *out, * @return 0 on success; nonzero on error. * * @retval ::WIMLIB_ERR_INVALID_PARAM - * The compression parameters were invalid. + * The window size or compression parameters were invalid. * @retval ::WIMLIB_ERR_NOMEM * Not enough memory to allocate the compression context. */ extern int -wimlib_lzx_alloc_context(const struct wimlib_lzx_params *params, +wimlib_lzx_alloc_context(uint32_t window_size, + const struct wimlib_lzx_params *params, struct wimlib_lzx_context **ctx_pp); /** @@ -2812,6 +2885,18 @@ extern int wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, void *uncompressed_data, unsigned uncompressed_len); +/** + * @ingroup G_compression + * + * Equivalent to wimlib_lzx_decompress(), except the window size is specified in + * @p max_window_size as any power of 2 between 2^15 and 2^21, inclusively, and + * @p uncompressed_len may be any size less than or equal to @p max_window_size. + */ +extern int +wimlib_lzx_decompress2(const void *compressed_data, unsigned compressed_len, + void *uncompressed_data, unsigned uncompressed_len, + uint32_t max_window_size); + /** * @ingroup G_compression * @@ -2973,7 +3058,8 @@ wimlib_mount_image(WIMStruct *wim, * chunk of the WIM does not match the corresponding message digest given * in the integrity table. * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * Resources in @p wim_file are compressed, but the chunk size is not 32768. + * Resources in @p wim_file are compressed, but the chunk size was invalid + * for the WIM's compression format. * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE * The header of @p wim_file says that resources in the WIM are compressed, * but the header flag indicating LZX or XPRESS compression is not set. @@ -3359,15 +3445,49 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, /** * @ingroup G_writing_and_overwriting_wims * - * Set the compression type of a WIM to use in subsequent calls to + * Set the compression chunk size of a WIM to use in subsequent calls to * wimlib_write() or wimlib_overwrite(). * + * A compression chunk size will result in a greater compression ratio, but the + * speed of random access to the WIM will be reduced, and the effect of an + * increased compression chunk size is limited by the size of each file being + * compressed. + * + * WARNING: Changing the compression chunk size to any value other than the + * default of 32768 bytes eliminates compatibility with Microsoft's software, + * except when increasing the XPRESS chunk size before Windows 8. Chunk sizes + * other than 32768 are also incompatible with wimlib v1.5.3 and earlier. + * + * @param wim + * ::WIMStruct for a WIM. + * @param out_chunk_size + * The chunk size (in bytes) to set. The valid chunk sizes are dependent + * on the compression format. The XPRESS compression format supports chunk + * sizes that are powers of 2 with exponents between 15 and 26 inclusively, + * whereas the LZX compression format supports chunk sizes that are powers + * of 2 with exponents between 15 and 21 inclusively. + * * @return 0 on success; nonzero on error. * + * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE + * @p ctype is not a supported chunk size. + */ +extern int +wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Set the compression type of a WIM to use in subsequent calls to + * wimlib_write() or wimlib_overwrite(). + * * @param wim * ::WIMStruct for a WIM. * @param ctype - * The compression type to set (one of ::wimlib_compression_type). + * The compression type to set (one of ::wimlib_compression_type). If this + * compression type is incompatible with the current output chunk size + * (either the default or as set with wimlib_set_output_chunk_size()), the + * output chunk size is reset to the default for that compression type. * * @return 0 on success; nonzero on error. * @@ -3871,8 +3991,28 @@ wimlib_write_to_fd(WIMStruct *wim, /** * @ingroup G_compression * - * This function is equivalent to wimlib_lzx_compress(), but instead compresses - * the data using "XPRESS" compression. + * Compress a chunk of data using XPRESS compression. + * + * This function is exported for convenience only and should only be used by + * library clients looking to make use of wimlib's compression code for another + * purpose. + * + * As of wimlib v1.6.0, this function can be used with @p chunk_size greater + * than 32768 bytes and is only limited by available memory. However, the + * XPRESS format itself still caps match offsets to 65535, so if a larger chunk + * size is chosen, then the matching will effectively occur in a sliding window + * over it. + * + * @param chunk + * Uncompressed data of the chunk. + * @param chunk_size + * Size of the uncompressed chunk, in bytes. + * @param out + * Pointer to output buffer of size at least (@p chunk_size - 1) bytes. + * + * @return + * The size of the compressed data written to @p out in bytes, or 0 if the + * data could not be compressed to (@p chunk_size - 1) bytes or fewer. */ extern unsigned wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out); @@ -3880,8 +4020,26 @@ wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out); /** * @ingroup G_compression * - * This function is equivalent to wimlib_lzx_decompress(), but instead assumes - * the data is compressed using "XPRESS" compression. + * Decompresses a chunk of XPRESS-compressed data. + * + * This function is exported for convenience only and should only be used by + * library clients looking to make use of wimlib's compression code for another + * purpose. + * + * @param compressed_data + * Pointer to the compressed data. + * + * @param compressed_len + * Length of the compressed data, in bytes. + * + * @param uncompressed_data + * Pointer to the buffer into which to write the uncompressed data. + * + * @param uncompressed_len + * Length of the uncompressed data. + * + * @return + * 0 on success; non-zero on failure. */ extern int wimlib_xpress_decompress(const void *compressed_data, unsigned compressed_len,