*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.6.0, a C
+ * This is the documentation for the library interface of wimlib 1.6.1, a C
* library for creating, modifying, extracting, and mounting files in the
* Windows Imaging Format. This documentation is intended for developers only.
* If you have installed wimlib and want to know how to use the @b wimlib-imagex
#define WIMLIB_MINOR_VERSION 6
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 1
#ifdef __cplusplus
extern "C" {
* ::wimlib_progress_info.scan. */
WIMLIB_PROGRESS_MSG_SCAN_END,
- /**
- * File resources are currently being written to the WIM.
- * @p info will point to ::wimlib_progress_info.write_streams. */
+ /** File resources ("streams") are currently being written to the WIM.
+ * @p info will point to ::wimlib_progress_info.write_streams. */
WIMLIB_PROGRESS_MSG_WRITE_STREAMS,
/**
/* N.B. I wanted these to be anonymous structs, but Doxygen won't
* document them if they aren't given a name... */
- /** Valid on messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. */
+ /** Valid on the message ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. This is
+ * the primary message for tracking the progress of writing a WIM file.
+ */
struct wimlib_progress_info_write_streams {
- /** Number of bytes that are going to be written for all the
- * streams combined. This is the amount in uncompressed data.
- * (The actual number of bytes will be less if the data is being
- * written compressed.) */
+ /** Total number of uncompressed bytes of stream data being
+ * written. This can be thought of as the total uncompressed
+ * size of the files being archived, with some caveats. WIM
+ * files use single-instance streams, so the size provided here
+ * only counts distinct streams, except for the following
+ * exception: the size provided here may include the sizes of
+ * all newly added (e.g. with wimlib_add_image() streams,
+ * pending automatic de-duplication during the write operation
+ * itself. When each such stream de-duplication occurs, this
+ * number will be decreased by the size of the duplicate stream
+ * that need not be written.
+ *
+ * In the case of a wimlib_overwrite() that the library opted to
+ * perform in-place, both @p total_streams and @p total_bytes
+ * will only count the streams actually being written and not
+ * pre-existing streams in the WIM file. */
uint64_t total_bytes;
- /** Number of streams that are going to be written. */
+ /** Total number of streams being written. This can be thought
+ * of as the total number of files being archived, with some
+ * caveats. In general, a single file or directory may contain
+ * multiple data streams, each of which will be represented
+ * separately in this number. Furthermore, WIM files use
+ * single-instance streams, so the stream count provided here
+ * only counts distinct streams, except for the following
+ * exception: the stream count provided here may include newly
+ * added (e.g. with wimlib_add_image() streams, pending
+ * automatic de-duplication during the write operation itself.
+ * When each such stream de-duplication occurs, this number will
+ * be decreased by 1 to account for the duplicate stream that
+ * need not be written. */
uint64_t total_streams;
- /** Number of uncompressed bytes that have been written so far.
- * Will be 0 initially, and equal to @p total_bytes at the end.
- * */
+ /** Number of uncompressed bytes of stream data that have been
+ * written so far. This number be 0 initially, and will be
+ * equal to @p total_bytes at the end of the write operation.
+ * Note that @p total_bytes (but not @p completed_bytes) may
+ * decrease throughout the write operation due to the discovery
+ * of stream duplications. */
uint64_t completed_bytes;
- /** Number of streams that have been written. Will be 0
- * initially, and equal to @p total_streams at the end. */
+ /** Number of streams that have been written so far. This
+ * number will be 0 initially, and will be equal to @p
+ * total_streams at the end of the write operation. Note that
+ * @p total_streams (but not @p completed_streams) may decrease
+ * throughout the write operation due to the discovery of stream
+ * duplications.
+ *
+ * For applications that wish to calculate a simple "percent
+ * complete" for the write operation, it will likely be more
+ * accurate to calculate the percentage from @p completed_bytes
+ * and @p total_bytes rather than @p completed_streams and
+ * @p total_streams because the time for the operation to
+ * complete is mainly determined by the number of bytes that
+ * need to be read, compressed, and written, not just the number
+ * of files being archived. */
uint64_t completed_streams;
- /** Number of threads that are being used to compress resources
- * (if applicable). */
- unsigned num_threads;
+ /** Number of threads that are being used to compress streams,
+ * or 1 if streams are being written uncompressed. */
+ uint32_t num_threads;
- /** The compression type being used to write the streams; either
- * ::WIMLIB_COMPRESSION_TYPE_NONE,
- * ::WIMLIB_COMPRESSION_TYPE_XPRESS, or
- * ::WIMLIB_COMPRESSION_TYPE_LZX. */
- int compression_type;
+ /** The compression type being used to write the streams, as one
+ * of the ::wimlib_compression_type constants. */
+ int32_t compression_type;
/** Number of split WIM parts from which streams are being
* written (may be 0 if irrelevant). */
- unsigned total_parts;
+ uint32_t total_parts;
/** Number of split WIM parts from which streams have been
* written (may be 0 if irrelevant). */
- unsigned completed_parts;
+ uint32_t completed_parts;
} write_streams;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
const wimlib_tchar *wim_target_path;
/** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
- * of ::WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is the
- * target of the absolute symbolic link or junction
+ * of @p WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is
+ * the target of the absolute symbolic link or junction
* point. */
const wimlib_tchar *symlink_target;
};
* one of the provided globs did not match a file. */
#define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000
+/** Do not extract Windows file attributes such as readonly, hidden, etc. */
+#define WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES 0x00100000
+
/** @} */
/** @ingroup G_mounting_wim_images
* @{ */
/** Used to specify all images in the WIM. */
#define WIMLIB_ALL_IMAGES (-1)
+/** @} */
+
/**
* @ingroup G_modifying_wims
*
* images. No on-disk file is created until wimlib_write() is called.
*
* @param ctype
- * The type of compression to be used in the new WIM file. Must be
- * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX, or
- * ::WIMLIB_COMPRESSION_TYPE_XPRESS.
+ * The type of compression to be used in the new WIM file, as one of the
+ * ::wimlib_compression_type constants.
* @param wim_ret
* On success, a pointer to an opaque ::WIMStruct for the new WIM file is
* written to the memory location pointed to by this paramater. The
* it.
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
- * @p ctype was not ::WIMLIB_COMPRESSION_TYPE_NONE,
- * ::WIMLIB_COMPRESSION_TYPE_LZX, or ::WIMLIB_COMPRESSION_TYPE_XPRESS.
+ * @p ctype was not a supported compression type.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate needed memory.
*/
wimlib_progress_func_t progress_func);
/**
- * Similar to wimlib_extract_paths(), but the paths to extract from the WIM
- * image specified in the UTF-8 text file named by @p path_list_file which
- * itself contains the list of paths to use, one per line. Leading and trailing
- * whitespace, and otherwise empty lines and lines beginning with the ';'
- * character are ignored. No quotes are needed as paths are otherwise delimited
- * by the newline character.
+ * @ingroup G_extracting_wims
+ *
+ * Since wimlib v1.6.0: Similar to wimlib_extract_paths(), but the paths to
+ * extract from the WIM image are specified in the UTF-8 text file named by @p
+ * path_list_file which itself contains the list of paths to use, one per line.
+ * Leading and trailing whitespace, and otherwise empty lines and lines
+ * beginning with the ';' character are ignored. No quotes are needed as paths
+ * are otherwise delimited by the newline character.
*/
extern int
wimlib_extract_pathlist(WIMStruct *wim, int image,
wimlib_progress_func_t progress_func);
/**
- * Similar to wimlib_extract_files(), but the files or directories to extract
- * from the WIM image are specified as an array of paths.
+ * @ingroup G_extracting_wims
+ *
+ * Since wimlib v1.6.0: Similar to wimlib_extract_files(), but the files or
+ * directories to extract from the WIM image are specified as an array of paths.
*
* Each path will be extracted to a corresponding subdirectory of the @p target
* based on its location in the WIM image. For example, if one of the paths to
* Converts a ::wimlib_compression_type value into a string.
*
* @param ctype
- * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX,
- * ::WIMLIB_COMPRESSION_TYPE_XPRESS, or another value.
+ * The ::wimlib_compression_type value to convert.
*
* @return
- * A statically allocated string: "None", "LZX", "XPRESS", or "Invalid",
- * respectively.
+ * A statically allocated string naming the compression algorithm,
+ * such as "None", "LZX", "XPRESS", or "Invalid".
*/
extern const wimlib_tchar *
wimlib_get_compression_type_string(int ctype);
* in the integrity table.
* @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE
* Resources in @p wim_file are compressed, but the chunk size was invalid
- * for the WIM's compression format.
+ * for the WIM's compression type.
* @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.
+ * but the header flag for a recognized compression type is not set.
* @retval ::WIMLIB_ERR_INVALID_HEADER
* The header of @p wim_file was otherwise invalid.
* @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE
* wim_file contains an integrity table, but the integrity table is
* invalid.
* @retval ::WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY
- * The lookup table for the WIM contained duplicate entries that are not
- * for metadata resources, or it contained an entry with a SHA1 message
- * digest of all 0's.
+ * The lookup table for the WIM was invalid.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p wim_ret was @c NULL.
* @retval ::WIMLIB_ERR_IS_SPLIT_WIM
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
* Unexpected end-of-file while reading data from @p wim_file.
* @retval ::WIMLIB_ERR_UNKNOWN_VERSION
- * A number other than 0x10d00 is written in the version field of the WIM
- * header of @p wim_file. (May be a pre-Vista WIM.)
+ * The WIM version number was not recognized. (May be a pre-Vista WIM.)
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
* considered read-only because of any of the reasons mentioned in the
extern void
wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated;
-/**
- * @ingroup G_wim_information
- *
- * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the
- * information in a way that can be accessed programatically.
- */
-extern int
-wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated;
-
/**
* @ingroup G_nonstandalone_wims
*
* 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.
+ * For compatibility reasons, using this function is not generally recommended.
+ * See the documentation for the @c --chunk-size option of <b>wimlib-imagex
+ * capture</b> for more information.
*
- * <b>WARNING: Microsoft's software is seemingly incompatible with LZX chunk
- * sizes other than 32768. Chunk sizes other than 32768 (for any format) are
- * also incompatible with wimlib v1.5.3 and earlier.</b>
+ * A larger compression chunk size will likely result in a better compression
+ * ratio, but the speed of random access to the WIM will be reduced.
+ * Furthermore, the effect of a larger compression chunk size is limited by the
+ * size of each stream ("file") being compressed.
*
* @param wim
* ::WIMStruct for a WIM.
- * @param out_chunk_size
+ * @param 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. As a special case,
- * if @p out_chunk_size is specified as 0, the chunk size is set to the
- * default for the currently selected output compression type.
+ * on the compression format; see the documentation for the @c --chunk-size
+ * option of <b>wimlib-imagex capture</b> for more information. As a
+ * special case, if @p chunk_size is specified as 0, the chunk size is set
+ * to the default for the currently selected output compression type.
*
* @return 0 on success; nonzero on error.
*
* @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE
- * @p ctype is not a supported chunk size.
+ * @p chunk_size is not a supported chunk size for the currently selected
+ * output compression type.
*/
extern int
wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size);
* @ingroup G_writing_and_overwriting_wims
*
* Similar to wimlib_set_output_compression_type(), but set the compression type
- * for writing packed streams.
+ * for writing packed streams (solid blocks).
+ *
+ * Note: based on testing, WIMGAPI is seemingly only compatible with LZMS
+ * compression in packed streams. Therefore the use of this function is not
+ * recommended. Also, with large chunk sizes, LZMS gives the best compression
+ * ratio among the alternatives anyway.
*/
extern int
wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
* decompressors currently support sliding windows, and there also exist
* slightly different variants of these formats that are not supported
* unmodified.
- */
-
-/**
- * @ingroup G_compression
+ *
* @{
*/
uint32_t slow_reserved1 : 31;
- /** Matches with length (in bytes) longer than this
- * value are immediately taken without spending time on
- * minimum-cost measurements. Suggested value: 32. */
- uint32_t num_fast_bytes;
+ /** Matches with length (in bytes) greater than or equal
+ * to this value are immediately taken without spending
+ * time on minimum-cost measurements. Suggested value:
+ * 32. */
+ uint32_t nice_match_length;
/** Number of passes to compute a match/literal sequence
* for each LZX block. This is for an iterative
} alg_params;
};
+/** LZMS compression parameters that can optionally be passed to
+ * wimlib_create_compressor() with the compression type
+ * ::WIMLIB_COMPRESSION_TYPE_LZMS. */
+struct wimlib_lzms_compressor_params {
+ /** hdr.size Must be set to the size of this structure, in bytes. */
+ struct wimlib_compressor_params_header hdr;
+
+ /** Minimum match length to output. This must be at least 2. Suggested
+ * value: 2 */
+ uint32_t min_match_length;
+
+ /** Maximum match length to output. This must be at least @p
+ * min_match_length. Suggested value: @p UINT32_MAX. */
+ uint32_t max_match_length;
+
+ /** Matches with length (in bytes) greater than or equal to this value
+ * are immediately taken without spending time on minimum-cost
+ * measurements. The minimum of @p max_match_length and @p
+ * nice_match_length may not exceed 65536. Suggested value: 32. */
+ uint32_t nice_match_length;
+
+ /** Maximum depth to search for matches at each position. Suggested
+ * value: 50. */
+ uint32_t max_search_depth;
+
+ /** Maximum number of potentially good matches to consider at each
+ * position. Suggested value: 3. */
+ uint32_t max_matches_per_pos;
+
+ /** Length of the array for the near-optimal LZ parsing algorithm. This
+ * must be at least 1. Suggested value: 1024. */
+ uint32_t optim_array_length;
+
+ uint64_t reserved2[4];
+};
+
/** Opaque compressor handle. */
struct wimlib_compressor;
*
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
* @p ctype was not a supported compression type.
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p params were invalid.
* @retval ::WIMLIB_ERR_NOMEM
* Not enough memory to duplicate the parameters (perhaps @c params->size
* was invalid).
wimlib_set_default_compressor_params(enum wimlib_compression_type ctype,
const struct wimlib_compressor_params_header *params);
+/**
+ * Returns the approximate number of bytes needed to allocate a compressor with
+ * wimlib_create_compressor() for the specified compression type, block size,
+ * and parameters. @p params may be @c NULL, in which case the current default
+ * parameters for @p ctype are used. Returns 0 if the compression type or
+ * parameters are invalid.
+ */
+extern uint64_t
+wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype,
+ size_t max_block_size,
+ const struct wimlib_compressor_params_header *params);
+
/**
* Allocate a compressor for the specified compression type using the specified
* parameters.
void *udata, unsigned ulen)
_wimlib_deprecated;
-/** @} */
+/**
+ * @}
+ */
+
+/** @ingroup G_wim_information
+ *
+ * Deprecated and will return ::WIMLIB_ERR_UNSUPPORTED. Use
+ * wimlib_iterate_dir_tree() instead. */
+extern int
+wimlib_print_metadata(WIMStruct *wim, int image)
+ _wimlib_deprecated;
#ifdef __cplusplus
git://wimlib.net / wimlib / blobdiff