X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=4ef32ac2c50ff429dc506549a1294d8c32b8d5b5;hb=5d3d469e410dc5f4a28814ad231336fc174cba56;hp=b73eb00156f2395a1a2eb52aea776de4a5ad7fa2;hpb=d65879dcf517ee6cd5256b48e3ac2525b1d1c0e8;p=wimlib diff --git a/include/wimlib.h b/include/wimlib.h index b73eb001..4ef32ac2 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -264,7 +264,7 @@ * * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a set * of paths from a WIM image in a manner that may be easier to use than - * wimlib_extract_files(), and also can wildcard characters. + * wimlib_extract_files(), and also allow wildcard patterns. * * wimlib_extract_image_from_pipe() allows an image to be extracted from a * pipable WIM sent over a pipe; see @ref subsec_pipable_wims. @@ -453,8 +453,8 @@ enum wimlib_progress_msg { * extracted. @p info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - /** The WIM image's files resources are currently being extracted. @p - * info will point to ::wimlib_progress_info.extract. */ + /** File data is currently being extracted. @p info will point to + * ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, /** Starting to read a new part of a split pipable WIM over the pipe. @@ -491,9 +491,8 @@ enum wimlib_progress_msg { * ::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, /** @@ -525,9 +524,7 @@ enum wimlib_progress_msg { * ::wimlib_progress_info.integrity. */ WIMLIB_PROGRESS_MSG_CALC_INTEGRITY, - /** Reserved. (Previously used for WIMLIB_PROGRESS_MSG_JOIN_STREAMS, - * but in wimlib v1.5.0 this was removed to simplify the code and now - * you'll get ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages instead.) */ + /** Reserved. */ WIMLIB_PROGRESS_MSG_RESERVED, /** A wimlib_split() operation is in progress, and a new split part is @@ -563,43 +560,83 @@ union wimlib_progress_info { /* 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, @@ -651,8 +688,8 @@ union wimlib_progress_info { 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; }; @@ -698,55 +735,80 @@ union wimlib_progress_info { uint64_t num_bytes_scanned; } scan; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, + /** Valid on messages + * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN, * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, and - * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. */ + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END, and + * ::WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS. + * + * Note: most of the time of an extraction operation will be spent + * extracting streams, and the application will receive + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS during this time. Using @p + * completed_bytes and @p total_bytes, the application can calculate a + * percentage complete. However, note that this message does not, in + * general, actually provide information about which "file" is currently + * being extracted. This is because wimlib, by default, extracts the + * individual data streams in whichever order it determines to be the + * most efficient. */ struct wimlib_progress_info_extract { - /** Number of the image being extracted (1-based). */ + /** Number of the image from which files are being extracted + * (1-based). */ int image; - /** Flags passed to to wimlib_extract_image() */ + /** Extraction flags being used. */ int extract_flags; - /** Full path to the WIM file being extracted. */ + /** Full path to the WIM file from which files are being + * extracted, or @c NULL if the WIMStruct has no associated + * on-disk file. */ const wimlib_tchar *wimfile_name; - /** Name of the image being extracted. */ + /** Name of the image from which files are being extracted, or + * the empty string if the image is unnamed. */ const wimlib_tchar *image_name; - /** Directory or NTFS volume to which the image is being - * extracted. */ + /** Path to the directory or NTFS volume to which the files are + * being extracted. */ const wimlib_tchar *target; /** Reserved. */ - const wimlib_tchar *cur_path; + const wimlib_tchar *reserved; /** Number of bytes of uncompressed data that will be extracted. - * Takes into account hard links (they are not counted for each - * link.) */ + * If a file has multiple names (hard links), its size (or + * sizes, in the case of named data streams) is only counted one + * time. For "reparse points" and symbolic links, the size to + * be extracted is the size of the reparse data buffer. + * + * This number will stay constant throughout the extraction. */ uint64_t total_bytes; - /** Number of bytes that have been written so far. Will be 0 - * initially, and equal to @p total_bytes at the end. */ + /** Number of bytes of uncompressed data that have been + * extracted so far. This initially be 0 and will equal to @p + * total_bytes at the end of the extraction. */ uint64_t completed_bytes; - /** Number of streams that will be extracted. This may more or - * less than the number of "files" to be extracted due to - * special cases (hard links, symbolic links, and alternate data - * streams.) */ + /** Number of (not necessarily unique) streams that will be + * extracted. This may be more or less than the number of + * "files" to be extracted due to hard links as well as + * potentially multiple streams per file (named data streams). + * A "stream" may be the default contents of a file, a named + * data stream, or a reparse data buffer. */ uint64_t num_streams; - /** Path to the root dentry within the WIM for the tree that is - * being extracted. Will be the empty string when extracting a - * full image, or when extracting a set of paths using - * wimlib_extract_paths() or wimlib_extract_pathlist(). */ + /** When extracting files using wimlib_extract_files(), this + * will be the path within the WIM image to the file or + * directory tree currently being extracted. Otherwise, this + * will be the empty string. */ const wimlib_tchar *extract_root_wim_source_path; /** Currently only used for * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ - unsigned part_number; /** Currently only used for @@ -1863,6 +1925,7 @@ enum wimlib_error_code { WIMLIB_ERR_WIM_IS_READONLY, WIMLIB_ERR_WRITE, WIMLIB_ERR_XML, + WIMLIB_ERR_WIM_IS_ENCRYPTED, }; @@ -1872,6 +1935,8 @@ enum wimlib_error_code { /** Used to specify all images in the WIM. */ #define WIMLIB_ALL_IMAGES (-1) +/** @} */ + /** * @ingroup G_modifying_wims * @@ -2006,9 +2071,8 @@ wimlib_add_image_multisource(WIMStruct *wim, * 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 @@ -2016,8 +2080,7 @@ wimlib_add_image_multisource(WIMStruct *wim, * 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. */ @@ -2407,12 +2470,14 @@ wimlib_extract_image_from_pipe(int pipe_fd, 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, @@ -2422,8 +2487,10 @@ 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 @@ -2503,12 +2570,11 @@ wimlib_free(WIMStruct *wim); * 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); @@ -2931,10 +2997,10 @@ wimlib_mount_image(WIMStruct *wim, * 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 @@ -2942,9 +3008,7 @@ wimlib_mount_image(WIMStruct *wim, * 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 @@ -2961,8 +3025,7 @@ wimlib_mount_image(WIMStruct *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 @@ -3331,19 +3394,20 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * * @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. The XPRESS and LZMS compression formats + * support 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 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); @@ -3888,10 +3952,7 @@ wimlib_write_to_fd(WIMStruct *wim, * decompressors currently support sliding windows, and there also exist * slightly different variants of these formats that are not supported * unmodified. - */ - -/** - * @ingroup G_compression + * * @{ */ @@ -3950,10 +4011,11 @@ struct wimlib_lzx_compressor_params { 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 @@ -3996,6 +4058,42 @@ struct wimlib_lzx_compressor_params { } 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; @@ -4017,6 +4115,8 @@ struct wimlib_decompressor; * * @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). @@ -4025,6 +4125,18 @@ extern int 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. @@ -4229,8 +4341,9 @@ wimlib_xpress_decompress(const void *cdata, unsigned clen, void *udata, unsigned ulen) _wimlib_deprecated; -/** @} */ - +/** + * @} + */ #ifdef __cplusplus