1 /** 2 * @file wimlib.h 3 * @brief External header for wimlib. 4 * 5 * This file contains comments for generating documentation with Doxygen. The 6 * built HTML documentation can be viewed at https://wimlib.net/apidoc. Make 7 * sure to see the <a href="modules.html">Modules page</a> to make more sense of 8 * the declarations in this header. 9 */ 10 11 /** 12 * @mainpage 13 * 14 * This is the documentation for the library interface of wimlib 1.13.0, a C 15 * library for creating, modifying, extracting, and mounting files in the 16 * Windows Imaging (WIM) format. This documentation is intended for developers 17 * only. If you have installed wimlib and want to know how to use the @b 18 * wimlib-imagex program, please see the manual pages and also the <a 19 * href="https://wimlib.net/git/?p=wimlib;a=blob;f=README">README file</a>. 20 * 21 * @section sec_installing Installing 22 * 23 * @subsection UNIX 24 * 25 * Download the source code from https://wimlib.net. Install the library by 26 * running <c>configure && make && sudo make install</c>. See the README for 27 * information about configuration options. To use wimlib in your program after 28 * installing it, include wimlib.h and link your program with <c>-lwim</c>. 29 * 30 * @subsection Windows 31 * 32 * Download the Windows binary distribution with the appropriate architecture 33 * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from 34 * https://wimlib.net. Link your program with libwim-15.dll. If needed by your 35 * programming language or development environment, the import library 36 * libwim.lib and C/C++ header wimlib.h can be found in the directory "devel" in 37 * the ZIP file. 38 * 39 * If you need to access the DLL from non-C/C++ programming languages, note that 40 * the calling convention is "cdecl". 41 * 42 * If you want to build wimlib from source on Windows, see README.WINDOWS. This 43 * is only needed if you are making modifications to wimlib. 44 * 45 * @section sec_examples Examples 46 * 47 * Several examples are located in the "examples" directory of the source 48 * distribution. Also see @ref sec_basic_wim_handling_concepts below. 49 * 50 * There is also the <a 51 * href="https://wimlib.net/git/?p=wimlib;a=blob;f=programs/imagex.c"> 52 * source code of <b>wimlib-imagex</b></a>, which is complicated but uses most 53 * capabilities of wimlib. 54 * 55 * @section backward_compatibility Backward Compatibility 56 * 57 * New releases of wimlib are intended to be backward compatible with old 58 * releases, except when the libtool "age" is reset. This most recently 59 * occurred for the v1.7.0 (libwim15) release (June 2014). Since the library is 60 * becoming increasingly stable, the goal is to maintain the current API/ABI for 61 * as long as possible unless there is a strong reason not to. 62 * 63 * As with any other library, applications should not rely on internal 64 * implementation details that may be subject to change. 65 * 66 * @section sec_basic_wim_handling_concepts Basic WIM handling concepts 67 * 68 * wimlib wraps up a WIM file in an opaque ::WIMStruct structure. There are 69 * two ways to create such a structure: 70 * 71 * 1. wimlib_open_wim() opens an on-disk WIM file and creates a ::WIMStruct for 72 * it. 73 * 2. wimlib_create_new_wim() creates a new ::WIMStruct that initially contains 74 * no images and does not yet have a backing on-disk file. 75 * 76 * A ::WIMStruct contains zero or more independent directory trees called @a 77 * images. Images may be extracted, added, deleted, exported, and updated using 78 * various API functions. (See @ref G_extracting_wims and @ref G_modifying_wims 79 * for more details.) 80 * 81 * Changes made to a WIM represented by a ::WIMStruct have no persistent effect 82 * until the WIM is actually written to an on-disk file. This can be done using 83 * wimlib_write(), but if the WIM was originally opened using wimlib_open_wim(), 84 * then wimlib_overwrite() can be used instead. (See @ref 85 * G_writing_and_overwriting_wims for more details.) 86 * 87 * wimlib's API is designed to let you combine functions to accomplish tasks in 88 * a flexible way. Here are some example sequences of function calls: 89 * 90 * Apply an image from a WIM file, similar to the command-line program 91 * <b>wimapply</b>: 92 * 93 * 1. wimlib_open_wim() 94 * 2. wimlib_extract_image() 95 * 96 * Capture an image into a new WIM file, similar to <b>wimcapture</b>: 97 * 98 * 1. wimlib_create_new_wim() 99 * 2. wimlib_add_image() 100 * 3. wimlib_write() 101 * 102 * Append an image to an existing WIM file, similar to <b>wimappend</b>: 103 * 104 * 1. wimlib_open_wim() 105 * 2. wimlib_add_image() 106 * 3. wimlib_overwrite() 107 * 108 * Delete an image from an existing WIM file, similar to <b>wimdelete</b>: 109 * 110 * 1. wimlib_open_wim() 111 * 2. wimlib_delete_image() 112 * 3. wimlib_overwrite() 113 * 114 * Export an image from one WIM file to another, similar to <b>wimexport</b>: 115 * 116 * 1. wimlib_open_wim() (on source) 117 * 2. wimlib_open_wim() (on destination) 118 * 3. wimlib_export_image() 119 * 4. wimlib_overwrite() (on destination) 120 * 121 * The API also lets you do things the command-line tools don't directly allow. 122 * For example, you could make multiple changes to a WIM before efficiently 123 * committing the changes with just one call to wimlib_overwrite(). Perhaps you 124 * want to both delete an image and add a new one; or perhaps you want to 125 * customize an image with wimlib_update_image() after adding it. All these use 126 * cases are supported by the API. 127 * 128 * @section sec_cleaning_up Cleaning up 129 * 130 * After you are done with any ::WIMStruct, you can call wimlib_free() to free 131 * all resources associated with it. Also, when you are completely done with 132 * using wimlib in your program, you can call wimlib_global_cleanup() to free 133 * any other resources allocated by the library. 134 * 135 * @section sec_error_handling Error Handling 136 * 137 * Most functions in wimlib return 0 on success and a positive 138 * ::wimlib_error_code value on failure. Use wimlib_get_error_string() to get a 139 * string that describes an error code. wimlib also can print error messages to 140 * standard error or a custom file when an error occurs, and these may be more 141 * informative than the error code; to enable this, call 142 * wimlib_set_print_errors(). Please note that this is for convenience only, 143 * and some errors can occur without a message being printed. Currently, error 144 * messages and strings (as well as all documentation, for that matter) are only 145 * available in English. 146 * 147 * @section sec_encodings Character encoding 148 * 149 * To support Windows as well as UNIX-like systems, wimlib's API typically takes 150 * and returns strings of ::wimlib_tchar which have a platform-dependent type 151 * and encoding. 152 * 153 * On Windows, each ::wimlib_tchar is a 2-byte <tt>wchar_t</tt>. The encoding 154 * is meant to be UTF-16LE. However, unpaired surrogates are permitted because 155 * neither Windows nor the NTFS filesystem forbids them in filenames. 156 * 157 * On UNIX-like systems, each ::wimlib_tchar is a 1 byte <tt>char</tt>. The 158 * encoding is meant to be UTF-8. However, for compatibility with Windows-style 159 * filenames that are not valid UTF-16LE, surrogate codepoints are permitted. 160 * Other multibyte encodings (e.g. ISO-8859-1) or garbage sequences of bytes are 161 * not permitted. 162 * 163 * @section sec_advanced Additional information and features 164 * 165 * 166 * @subsection subsec_mounting_wim_images Mounting WIM images 167 * 168 * See @ref G_mounting_wim_images. 169 * 170 * @subsection subsec_progress_functions Progress Messages 171 * 172 * See @ref G_progress. 173 * 174 * @subsection subsec_non_standalone_wims Non-standalone WIMs 175 * 176 * See @ref G_nonstandalone_wims. 177 * 178 * @subsection subsec_pipable_wims Pipable WIMs 179 * 180 * wimlib supports a special "pipable" WIM format which unfortunately is @b not 181 * compatible with Microsoft's software. To create a pipable WIM, call 182 * wimlib_write(), wimlib_write_to_fd(), or wimlib_overwrite() with 183 * ::WIMLIB_WRITE_FLAG_PIPABLE specified. Pipable WIMs are pipable in both 184 * directions, so wimlib_write_to_fd() can be used to write a pipable WIM to a 185 * pipe, and wimlib_extract_image_from_pipe() can be used to apply an image from 186 * a pipable WIM. wimlib can also transparently open and operate on pipable WIM 187 * s using a seekable file descriptor using the regular function calls (e.g. 188 * wimlib_open_wim(), wimlib_extract_image()). 189 * 190 * See the documentation for the <b>--pipable</b> flag of <b>wimcapture</b> for 191 * more information about pipable WIMs. 192 * 193 * @subsection subsec_thread_safety Thread Safety 194 * 195 * A ::WIMStruct is not thread-safe and cannot be accessed by multiple threads 196 * concurrently, even for "read-only" operations such as extraction. However, 197 * users are free to use <i>different</i> ::WIMStruct's from different threads 198 * concurrently. It is even allowed for multiple ::WIMStruct's to be backed by 199 * the same on-disk WIM file, although "overwrites" should never be done in such 200 * a scenario. 201 * 202 * In addition, several functions change global state and should only be called 203 * when a single thread is active in the library. These functions are: 204 * 205 * - wimlib_global_init() 206 * - wimlib_global_cleanup() 207 * - wimlib_set_memory_allocator() 208 * - wimlib_set_print_errors() 209 * - wimlib_set_error_file() 210 * - wimlib_set_error_file_by_name() 211 * 212 * @subsection subsec_limitations Limitations 213 * 214 * This section documents some technical limitations of wimlib not already 215 * described in the documentation for @b wimlib-imagex. 216 * 217 * - The old WIM format from Vista pre-releases is not supported. 218 * - wimlib does not provide a clone of the @b PEImg tool, or the @b DISM 219 * functionality other than that already present in @b ImageX, that allows you 220 * to make certain Windows-specific modifications to a Windows PE image, such 221 * as adding a driver or Windows component. Such a tool could be implemented 222 * on top of wimlib. 223 * 224 * @subsection more_info More information 225 * 226 * You are advised to read the README as well as the documentation for 227 * <b>wimlib-imagex</b>, since not all relevant information is repeated here in 228 * the API documentation. 229 */ 230 231 /** @defgroup G_general General 232 * 233 * @brief Declarations and structures shared across the library. 234 */ 235 236 /** @defgroup G_creating_and_opening_wims Creating and Opening WIMs 237 * 238 * @brief Open an existing WIM file as a ::WIMStruct, or create a new 239 * ::WIMStruct which can be used to create a new WIM file. 240 */ 241 242 /** @defgroup G_wim_information Retrieving WIM information and directory listings 243 * 244 * @brief Retrieve information about a WIM or WIM image. 245 */ 246 247 /** @defgroup G_modifying_wims Modifying WIMs 248 * 249 * @brief Make changes to a ::WIMStruct, in preparation of persisting the 250 * ::WIMStruct to an on-disk file. 251 * 252 * @section sec_adding_images Capturing and adding WIM images 253 * 254 * As described in @ref sec_basic_wim_handling_concepts, capturing a new WIM or 255 * appending an image to an existing WIM is a multi-step process, but at its 256 * core is wimlib_add_image() or an equivalent function. Normally, 257 * wimlib_add_image() takes an on-disk directory tree and logically adds it to a 258 * ::WIMStruct as a new image. However, when supported by the build of the 259 * library, there is also a special NTFS volume capture mode (entered when 260 * ::WIMLIB_ADD_FLAG_NTFS is specified) that allows adding the image directly 261 * from an unmounted NTFS volume. 262 * 263 * Another function, wimlib_add_image_multisource() is also provided. It 264 * generalizes wimlib_add_image() to allow combining multiple files or directory 265 * trees into a single WIM image in a configurable way. 266 * 267 * For maximum customization of WIM image creation, it is also possible to add a 268 * completely empty WIM image with wimlib_add_empty_image(), then update it with 269 * wimlib_update_image(). (This is in fact what wimlib_add_image() and 270 * wimlib_add_image_multisource() do internally.) 271 * 272 * Note that some details of how image addition/capture works are documented 273 * more fully in the documentation for <b>wimcapture</b>. 274 * 275 * @section sec_deleting_images Deleting WIM images 276 * 277 * wimlib_delete_image() can delete an image from a ::WIMStruct. But as usual, 278 * wimlib_write() or wimlib_overwrite() must be called to cause the changes to 279 * be made persistent in an on-disk WIM file. 280 * 281 * @section sec_exporting_images Exporting WIM images 282 * 283 * wimlib_export_image() can copy, or "export", an image from one WIM to 284 * another. 285 * 286 * @section sec_other_modifications Other modifications 287 * 288 * wimlib_update_image() can add, delete, and rename files in a WIM image. 289 * 290 * wimlib_set_image_property() can change other image metadata. 291 * 292 * wimlib_set_wim_info() can change information about the WIM file itself, such 293 * as the boot index. 294 */ 295 296 /** @defgroup G_extracting_wims Extracting WIMs 297 * 298 * @brief Extract files, directories, and images from a WIM. 299 * 300 * wimlib_extract_image() extracts, or "applies", an image from a WIM, 301 * represented by a ::WIMStruct. This normally extracts the image to a 302 * directory, but when supported by the build of the library there is also a 303 * special NTFS volume extraction mode (entered when ::WIMLIB_EXTRACT_FLAG_NTFS 304 * is specified) that allows extracting a WIM image directly to an unmounted 305 * NTFS volume. Various other flags allow further customization of image 306 * extraction. 307 * 308 * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a list 309 * of (possibly wildcard) paths from a WIM image. 310 * 311 * wimlib_extract_image_from_pipe() extracts an image from a pipable WIM sent 312 * over a pipe; see @ref subsec_pipable_wims. 313 * 314 * Some details of how WIM extraction works are described more fully in the 315 * documentation for <b>wimapply</b> and <b>wimextract</b>. 316 */ 317 318 /** @defgroup G_mounting_wim_images Mounting WIM images 319 * 320 * @brief Mount and unmount WIM images. 321 * 322 * On Linux, wimlib supports mounting images from WIM files either read-only or 323 * read-write. To mount an image, call wimlib_mount_image(). To unmount an 324 * image, call wimlib_unmount_image(). Mounting can be done without root 325 * privileges because it is implemented using FUSE (Filesystem in Userspace). 326 * 327 * If wimlib is compiled using the <c>--without-fuse</c> flag, these functions 328 * will be available but will fail with ::WIMLIB_ERR_UNSUPPORTED. 329 * 330 * Note: if mounting is unsupported, wimlib still provides another way to modify 331 * a WIM image (wimlib_update_image()). 332 */ 333 334 /** 335 * @defgroup G_progress Progress Messages 336 * 337 * @brief Track the progress of long WIM operations. 338 * 339 * Library users can provide a progress function which will be called 340 * periodically during operations such as extracting a WIM image or writing a 341 * WIM image. A ::WIMStruct can have a progress function of type 342 * ::wimlib_progress_func_t associated with it by calling 343 * wimlib_register_progress_function() or by opening the ::WIMStruct using 344 * wimlib_open_wim_with_progress(). Once this is done, the progress function 345 * will be called automatically during many operations, such as 346 * wimlib_extract_image() and wimlib_write(). 347 * 348 * Some functions that do not operate directly on a user-provided ::WIMStruct, 349 * such as wimlib_join(), also take the progress function directly using an 350 * extended version of the function, such as wimlib_join_with_progress(). 351 * 352 * Since wimlib v1.7.0, progress functions are no longer just unidirectional. 353 * You can now return ::WIMLIB_PROGRESS_STATUS_ABORT to cause the current 354 * operation to be aborted. wimlib v1.7.0 also added the third argument to 355 * ::wimlib_progress_func_t, which is a user-supplied context. 356 */ 357 358 /** @defgroup G_writing_and_overwriting_wims Writing and Overwriting WIMs 359 * 360 * @brief Create or update an on-disk WIM file. 361 * 362 * wimlib_write() creates a new on-disk WIM file, whereas wimlib_overwrite() 363 * updates an existing WIM file. See @ref sec_basic_wim_handling_concepts for 364 * more information about the API design. 365 */ 366 367 /** @defgroup G_nonstandalone_wims Creating and handling non-standalone WIMs 368 * 369 * @brief Create and handle non-standalone WIMs, such as split and delta WIMs. 370 * 371 * A ::WIMStruct backed by an on-disk file normally represents a fully 372 * standalone WIM archive. However, WIM archives can also be arranged in 373 * non-standalone ways, such as a set of on-disk files that together form a 374 * single "split WIM" or "delta WIM". Such arrangements are fully supported by 375 * wimlib. However, as a result, in such cases a ::WIMStruct created from one 376 * of these on-disk files initially only partially represents the full WIM and 377 * needs to, in effect, be logically combined with other ::WIMStruct's before 378 * performing certain operations, such as extracting files with 379 * wimlib_extract_image() or wimlib_extract_paths(). This is done by calling 380 * wimlib_reference_resource_files() or wimlib_reference_resources(). Note: if 381 * you fail to do so, you may see the error code 382 * ::WIMLIB_ERR_RESOURCE_NOT_FOUND; this just indicates that data is not 383 * available because the appropriate WIM files have not yet been referenced. 384 * 385 * wimlib_write() can create delta WIMs as well as standalone WIMs, but a 386 * specialized function (wimlib_split()) is needed to create a split WIM. 387 */ 388 389 #ifndef _WIMLIB_H 390 #define _WIMLIB_H 391 392 #include <stdio.h> 393 #include <stddef.h> 394 #ifndef __cplusplus 395 # if defined(_MSC_VER) && _MSC_VER < 1800 /* VS pre-2013? */ 396 typedef unsigned char bool; 397 # else 398 # include <stdbool.h> 399 # endif 400 #endif 401 #include <stdint.h> 402 #include <time.h> 403 404 /** @addtogroup G_general 405 * @{ */ 406 407 /** Major version of the library (for example, the 1 in 1.2.5). */ 408 #define WIMLIB_MAJOR_VERSION 1 409 410 /** Minor version of the library (for example, the 2 in 1.2.5). */ 411 #define WIMLIB_MINOR_VERSION 13 412 413 /** Patch version of the library (for example, the 5 in 1.2.5). */ 414 #define WIMLIB_PATCH_VERSION 0 415 416 #ifdef __cplusplus 417 extern "C" { 418 #endif 419 420 /* 421 * To represent file timestamps, wimlib's API originally used the POSIX 'struct 422 * timespec'. This was a mistake because when building wimlib for 32-bit 423 * Windows with MinGW we ended up originally using 32-bit time_t which isn't 424 * year 2038-safe, and therefore we had to later add fields like 425 * 'creation_time_high' to hold the high 32 bits of each timestamp. Moreover, 426 * old Visual Studio versions did not define struct timespec, while newer ones 427 * define it but with 64-bit tv_sec. So to at least avoid a missing or 428 * incompatible 'struct timespec' definition, define the correct struct 429 * ourselves when this header is included on Windows. 430 */ 431 #ifdef _WIN32 432 struct wimlib_timespec { 433 /* Seconds since start of UNIX epoch (January 1, 1970) */ 434 #ifdef _WIN64 435 int64_t tv_sec; 436 #else 437 int32_t tv_sec; 438 #endif 439 /* Nanoseconds (0-999999999) */ 440 int32_t tv_nsec; 441 }; 442 #else 443 # define wimlib_timespec timespec /* standard definition */ 444 #endif 445 446 /** 447 * Opaque structure that represents a WIM, possibly backed by an on-disk file. 448 * See @ref sec_basic_wim_handling_concepts for more information. 449 */ 450 #ifndef WIMLIB_WIMSTRUCT_DECLARED 451 typedef struct WIMStruct WIMStruct; 452 #define WIMLIB_WIMSTRUCT_DECLARED 453 #endif 454 455 #ifdef _WIN32 456 typedef wchar_t wimlib_tchar; 457 #else 458 /** See @ref sec_encodings */ 459 typedef char wimlib_tchar; 460 #endif 461 462 #ifdef _WIN32 463 /** Path separator for WIM paths passed back to progress callbacks. 464 * This is forward slash on UNIX and backslash on Windows. */ 465 # define WIMLIB_WIM_PATH_SEPARATOR '\\' 466 # define WIMLIB_WIM_PATH_SEPARATOR_STRING L"\\" 467 #else 468 /** Path separator for WIM paths passed back to progress callbacks. 469 * This is forward slash on UNIX and backslash on Windows. */ 470 # define WIMLIB_WIM_PATH_SEPARATOR '/' 471 # define WIMLIB_WIM_PATH_SEPARATOR_STRING "/" 472 #endif 473 474 /** A string containing a single path separator; use this to specify the root 475 * directory of a WIM image. */ 476 #define WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING 477 478 /** Use this to test if the specified path refers to the root directory of the 479 * WIM image. */ 480 #define WIMLIB_IS_WIM_ROOT_PATH(path) \ 481 ((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \ 482 (path)[1] == 0) 483 484 /** Length of a Globally Unique Identifier (GUID), in bytes. */ 485 #define WIMLIB_GUID_LEN 16 486 487 /** 488 * Specifies a compression type. 489 * 490 * A WIM file has a default compression type, indicated by its file header. 491 * Normally, each resource in the WIM file is compressed with this compression 492 * type. However, resources may be stored as uncompressed; for example, wimlib 493 * may do so if a resource does not compress to less than its original size. In 494 * addition, a WIM with the new version number of 3584, or "ESD file", might 495 * contain solid resources with different compression types. 496 */ 497 enum wimlib_compression_type { 498 /** 499 * No compression. 500 * 501 * This is a valid argument to wimlib_create_new_wim() and 502 * wimlib_set_output_compression_type(), but not to the functions in the 503 * compression API such as wimlib_create_compressor(). 504 */ 505 WIMLIB_COMPRESSION_TYPE_NONE = 0, 506 507 /** 508 * The XPRESS compression format. This format combines Lempel-Ziv 509 * factorization with Huffman encoding. Compression and decompression 510 * are both fast. This format supports chunk sizes that are powers of 2 511 * between <c>2^12</c> and <c>2^16</c>, inclusively. 512 * 513 * wimlib's XPRESS compressor will, with the default settings, usually 514 * produce a better compression ratio, and work more quickly, than the 515 * implementation in Microsoft's WIMGAPI (as of Windows 8.1). 516 * Non-default compression levels are also supported. For example, 517 * level 80 will enable two-pass optimal parsing, which is significantly 518 * slower but usually improves compression by several percent over the 519 * default level of 50. 520 * 521 * If using wimlib_create_compressor() to create an XPRESS compressor 522 * directly, the @p max_block_size parameter may be any positive value 523 * up to and including <c>2^16</c>. 524 */ 525 WIMLIB_COMPRESSION_TYPE_XPRESS = 1, 526 527 /** 528 * The LZX compression format. This format combines Lempel-Ziv 529 * factorization with Huffman encoding, but with more features and 530 * complexity than XPRESS. Compression is slow to somewhat fast, 531 * depending on the settings. Decompression is fast but slower than 532 * XPRESS. This format supports chunk sizes that are powers of 2 533 * between <c>2^15</c> and <c>2^21</c>, inclusively. Note: chunk sizes 534 * other than <c>2^15</c> are not compatible with the Microsoft 535 * implementation. 536 * 537 * wimlib's LZX compressor will, with the default settings, usually 538 * produce a better compression ratio, and work more quickly, than the 539 * implementation in Microsoft's WIMGAPI (as of Windows 8.1). 540 * Non-default compression levels are also supported. For example, 541 * level 20 will provide fast compression, almost as fast as XPRESS. 542 * 543 * If using wimlib_create_compressor() to create an LZX compressor 544 * directly, the @p max_block_size parameter may be any positive value 545 * up to and including <c>2^21</c>. 546 */ 547 WIMLIB_COMPRESSION_TYPE_LZX = 2, 548 549 /** 550 * The LZMS compression format. This format combines Lempel-Ziv 551 * factorization with adaptive Huffman encoding and range coding. 552 * Compression and decompression are both fairly slow. This format 553 * supports chunk sizes that are powers of 2 between <c>2^15</c> and 554 * <c>2^30</c>, inclusively. This format is best used for large chunk 555 * sizes. Note: LZMS compression is only compatible with wimlib v1.6.0 556 * and later, WIMGAPI Windows 8 and later, and DISM Windows 8.1 and 557 * later. Also, chunk sizes larger than <c>2^26</c> are not compatible 558 * with the Microsoft implementation. 559 * 560 * wimlib's LZMS compressor will, with the default settings, usually 561 * produce a better compression ratio, and work more quickly, than the 562 * implementation in Microsoft's WIMGAPI (as of Windows 8.1). There is 563 * limited support for non-default compression levels, but compression 564 * will be noticeably faster if you choose a level < 35. 565 * 566 * If using wimlib_create_compressor() to create an LZMS compressor 567 * directly, the @p max_block_size parameter may be any positive value 568 * up to and including <c>2^30</c>. 569 */ 570 WIMLIB_COMPRESSION_TYPE_LZMS = 3, 571 }; 572 573 /** @} */ 574 /** @addtogroup G_progress 575 * @{ */ 576 577 /** Possible values of the first parameter to the user-supplied 578 * ::wimlib_progress_func_t progress function */ 579 enum wimlib_progress_msg { 580 581 /** A WIM image is about to be extracted. @p info will point to 582 * ::wimlib_progress_info.extract. This message is received once per 583 * image for calls to wimlib_extract_image() and 584 * wimlib_extract_image_from_pipe(). */ 585 WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0, 586 587 /** One or more file or directory trees within a WIM image is about to 588 * be extracted. @p info will point to ::wimlib_progress_info.extract. 589 * This message is received only once per wimlib_extract_paths() and 590 * wimlib_extract_pathlist(), since wimlib combines all paths into a 591 * single extraction operation for optimization purposes. */ 592 WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN = 1, 593 594 /** This message may be sent periodically (not for every file) while 595 * files and directories are being created, prior to file data 596 * extraction. @p info will point to ::wimlib_progress_info.extract. 597 * In particular, the @p current_file_count and @p end_file_count 598 * members may be used to track the progress of this phase of 599 * extraction. */ 600 WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE = 3, 601 602 /** File data is currently being extracted. @p info will point to 603 * ::wimlib_progress_info.extract. This is the main message to track 604 * the progress of an extraction operation. */ 605 WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS = 4, 606 607 /** Starting to read a new part of a split pipable WIM over the pipe. 608 * @p info will point to ::wimlib_progress_info.extract. */ 609 WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN = 5, 610 611 /** This message may be sent periodically (not necessarily for every 612 * file) while file and directory metadata is being extracted, following 613 * file data extraction. @p info will point to 614 * ::wimlib_progress_info.extract. The @p current_file_count and @p 615 * end_file_count members may be used to track the progress of this 616 * phase of extraction. */ 617 WIMLIB_PROGRESS_MSG_EXTRACT_METADATA = 6, 618 619 /** The image has been successfully extracted. @p info will point to 620 * ::wimlib_progress_info.extract. This is paired with 621 * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN. */ 622 WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END = 7, 623 624 /** The files or directory trees have been successfully extracted. @p 625 * info will point to ::wimlib_progress_info.extract. This is paired 626 * with ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */ 627 WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END = 8, 628 629 /** The directory or NTFS volume is about to be scanned for metadata. 630 * @p info will point to ::wimlib_progress_info.scan. This message is 631 * received once per call to wimlib_add_image(), or once per capture 632 * source passed to wimlib_add_image_multisource(), or once per add 633 * command passed to wimlib_update_image(). */ 634 WIMLIB_PROGRESS_MSG_SCAN_BEGIN = 9, 635 636 /** A directory or file has been scanned. @p info will point to 637 * ::wimlib_progress_info.scan, and its @p cur_path member will be 638 * valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE has 639 * been specified. */ 640 WIMLIB_PROGRESS_MSG_SCAN_DENTRY = 10, 641 642 /** The directory or NTFS volume has been successfully scanned. @p info 643 * will point to ::wimlib_progress_info.scan. This is paired with a 644 * previous ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN message, possibly with many 645 * intervening ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY messages. */ 646 WIMLIB_PROGRESS_MSG_SCAN_END = 11, 647 648 /** File data is currently being written to the WIM. @p info will point 649 * to ::wimlib_progress_info.write_streams. This message may be 650 * received many times while the WIM file is being written or appended 651 * to with wimlib_write(), wimlib_overwrite(), or wimlib_write_to_fd(). 652 */ 653 WIMLIB_PROGRESS_MSG_WRITE_STREAMS = 12, 654 655 /** Per-image metadata is about to be written to the WIM file. @p info 656 * will not be valid. */ 657 WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN = 13, 658 659 /** The per-image metadata has been written to the WIM file. @p info 660 * will not be valid. This message is paired with a preceding 661 * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message. */ 662 WIMLIB_PROGRESS_MSG_WRITE_METADATA_END = 14, 663 664 /** wimlib_overwrite() has successfully renamed the temporary file to 665 * the original WIM file, thereby committing the changes to the WIM 666 * file. @p info will point to ::wimlib_progress_info.rename. Note: 667 * this message is not received if wimlib_overwrite() chose to append to 668 * the WIM file in-place. */ 669 WIMLIB_PROGRESS_MSG_RENAME = 15, 670 671 /** The contents of the WIM file are being checked against the integrity 672 * table. @p info will point to ::wimlib_progress_info.integrity. This 673 * message is only received (and may be received many times) when 674 * wimlib_open_wim_with_progress() is called with the 675 * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. */ 676 WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY = 16, 677 678 /** An integrity table is being calculated for the WIM being written. 679 * @p info will point to ::wimlib_progress_info.integrity. This message 680 * is only received (and may be received many times) when a WIM file is 681 * being written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */ 682 WIMLIB_PROGRESS_MSG_CALC_INTEGRITY = 17, 683 684 /** A wimlib_split() operation is in progress, and a new split part is 685 * about to be started. @p info will point to 686 * ::wimlib_progress_info.split. */ 687 WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART = 19, 688 689 /** A wimlib_split() operation is in progress, and a split part has been 690 * finished. @p info will point to ::wimlib_progress_info.split. */ 691 WIMLIB_PROGRESS_MSG_SPLIT_END_PART = 20, 692 693 /** A WIM update command is about to be executed. @p info will point to 694 * ::wimlib_progress_info.update. This message is received once per 695 * update command when wimlib_update_image() is called with the flag 696 * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */ 697 WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND = 21, 698 699 /** A WIM update command has been executed. @p info will point to 700 * ::wimlib_progress_info.update. This message is received once per 701 * update command when wimlib_update_image() is called with the flag 702 * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */ 703 WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND = 22, 704 705 /** A file in the image is being replaced as a result of a 706 * ::wimlib_add_command without ::WIMLIB_ADD_FLAG_NO_REPLACE specified. 707 * @p info will point to ::wimlib_progress_info.replace. This is only 708 * received when ::WIMLIB_ADD_FLAG_VERBOSE is also specified in the add 709 * command. */ 710 WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM = 23, 711 712 /** An image is being extracted with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and 713 * a file is being extracted normally (not as a "WIMBoot pointer file") 714 * due to it matching a pattern in the <c>[PrepopulateList]</c> section 715 * of the configuration file 716 * <c>/Windows/System32/WimBootCompress.ini</c> in the WIM image. @p 717 * info will point to ::wimlib_progress_info.wimboot_exclude. */ 718 WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE = 24, 719 720 /** Starting to unmount an image. @p info will point to 721 * ::wimlib_progress_info.unmount. */ 722 WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25, 723 724 /** wimlib has used a file's data for the last time (including all data 725 * streams, if it has multiple). @p info will point to 726 * ::wimlib_progress_info.done_with_file. This message is only received 727 * if ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES was provided. */ 728 WIMLIB_PROGRESS_MSG_DONE_WITH_FILE = 26, 729 730 /** wimlib_verify_wim() is starting to verify the metadata for an image. 731 * @p info will point to ::wimlib_progress_info.verify_image. */ 732 WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE = 27, 733 734 /** wimlib_verify_wim() has finished verifying the metadata for an 735 * image. @p info will point to ::wimlib_progress_info.verify_image. 736 */ 737 WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE = 28, 738 739 /** wimlib_verify_wim() is verifying file data integrity. @p info will 740 * point to ::wimlib_progress_info.verify_streams. */ 741 WIMLIB_PROGRESS_MSG_VERIFY_STREAMS = 29, 742 743 /** 744 * The progress function is being asked whether a file should be 745 * excluded from capture or not. @p info will point to 746 * ::wimlib_progress_info.test_file_exclusion. This is a bidirectional 747 * message that allows the progress function to set a flag if the file 748 * should be excluded. 749 * 750 * This message is only received if the flag 751 * ::WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION is used. This method for file 752 * exclusions is independent of the "capture configuration file" 753 * mechanism. 754 */ 755 WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION = 30, 756 757 /** 758 * An error has occurred and the progress function is being asked 759 * whether to ignore the error or not. @p info will point to 760 * ::wimlib_progress_info.handle_error. This is a bidirectional 761 * message. 762 * 763 * This message provides a limited capability for applications to 764 * recover from "unexpected" errors (i.e. those with no in-library 765 * handling policy) arising from the underlying operating system. 766 * Normally, any such error will cause the library to abort the current 767 * operation. By implementing a handler for this message, the 768 * application can instead choose to ignore a given error. 769 * 770 * Currently, only the following types of errors will result in this 771 * progress message being sent: 772 * 773 * - Directory tree scan errors, e.g. from wimlib_add_image() 774 * - Most extraction errors; currently restricted to the Windows 775 * build of the library only. 776 */ 777 WIMLIB_PROGRESS_MSG_HANDLE_ERROR = 31, 778 }; 779 780 /** Valid return values from user-provided progress functions 781 * (::wimlib_progress_func_t). 782 * 783 * (Note: if an invalid value is returned, ::WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS 784 * will be issued.) 785 */ 786 enum wimlib_progress_status { 787 788 /** The operation should be continued. This is the normal return value. 789 */ 790 WIMLIB_PROGRESS_STATUS_CONTINUE = 0, 791 792 /** The operation should be aborted. This will cause the current 793 * operation to fail with ::WIMLIB_ERR_ABORTED_BY_PROGRESS. */ 794 WIMLIB_PROGRESS_STATUS_ABORT = 1, 795 }; 796 797 /** 798 * A pointer to this union is passed to the user-supplied 799 * ::wimlib_progress_func_t progress function. One (or none) of the structures 800 * contained in this union will be applicable for the operation 801 * (::wimlib_progress_msg) indicated in the first argument to the progress 802 * function. */ 803 union wimlib_progress_info { 804 805 /** Valid on the message ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. This is 806 * the primary message for tracking the progress of writing a WIM file. 807 */ 808 struct wimlib_progress_info_write_streams { 809 810 /** An upper bound on the number of bytes of file data that will 811 * be written. This number is the uncompressed size; the actual 812 * size may be lower due to compression. In addition, this 813 * number may decrease over time as duplicated file data is 814 * discovered. */ 815 uint64_t total_bytes; 816 817 /** An upper bound on the number of distinct file data "blobs" 818 * that will be written. This will often be similar to the 819 * "number of files", but for several reasons (hard links, named 820 * data streams, empty files, etc.) it can be different. In 821 * addition, this number may decrease over time as duplicated 822 * file data is discovered. */ 823 uint64_t total_streams; 824 825 /** The number of bytes of file data that have been written so 826 * far. This starts at 0 and ends at @p total_bytes. This 827 * number is the uncompressed size; the actual size may be lower 828 * due to compression. */ 829 uint64_t completed_bytes; 830 831 /** The number of distinct file data "blobs" that have been 832 * written so far. This starts at 0 and ends at @p 833 * total_streams. */ 834 uint64_t completed_streams; 835 836 /** The number of threads being used for data compression; or, 837 * if no compression is being performed, this will be 1. */ 838 uint32_t num_threads; 839 840 /** The compression type being used, as one of the 841 * ::wimlib_compression_type constants. */ 842 int32_t compression_type; 843 844 /** The number of on-disk WIM files from which file data is 845 * being exported into the output WIM file. This can be 0, 1, 846 * or more than 1, depending on the situation. */ 847 uint32_t total_parts; 848 849 /** This is currently broken and will always be 0. */ 850 uint32_t completed_parts; 851 } write_streams; 852 853 /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN, 854 * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY, and 855 * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ 856 struct wimlib_progress_info_scan { 857 858 /** Top-level directory being scanned; or, when capturing an NTFS 859 * volume with ::WIMLIB_ADD_FLAG_NTFS, this is instead the path 860 * to the file or block device that contains the NTFS volume 861 * being scanned. */ 862 const wimlib_tchar *source; 863 864 /** Path to the file (or directory) that has been scanned, valid 865 * on ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. When capturing an NTFS 866 * volume with ::WIMLIB_ADD_FLAG_NTFS, this path will be 867 * relative to the root of the NTFS volume. */ 868 const wimlib_tchar *cur_path; 869 870 /** Dentry scan status, valid on 871 * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. */ 872 enum { 873 /** File looks okay and will be captured. */ 874 WIMLIB_SCAN_DENTRY_OK = 0, 875 876 /** File is being excluded from capture due to the 877 * capture configuration. */ 878 WIMLIB_SCAN_DENTRY_EXCLUDED = 1, 879 880 /** File is being excluded from capture due to being of 881 * an unsupported type. */ 882 WIMLIB_SCAN_DENTRY_UNSUPPORTED = 2, 883 884 /** The file is an absolute symbolic link or junction 885 * that points into the capture directory, and 886 * reparse-point fixups are enabled, so its target is 887 * being adjusted. (Reparse point fixups can be 888 * disabled with the flag ::WIMLIB_ADD_FLAG_NORPFIX.) 889 */ 890 WIMLIB_SCAN_DENTRY_FIXED_SYMLINK = 3, 891 892 /** Reparse-point fixups are enabled, but the file is an 893 * absolute symbolic link or junction that does 894 * <b>not</b> point into the capture directory, so its 895 * target is <b>not</b> being adjusted. */ 896 WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK = 4, 897 } status; 898 899 union { 900 /** Target path in the image. Only valid on messages 901 * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and 902 * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ 903 const wimlib_tchar *wim_target_path; 904 905 /** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status 906 * of @p WIMLIB_SCAN_DENTRY_FIXED_SYMLINK or @p 907 * WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK, this is the 908 * target of the absolute symbolic link or junction. */ 909 const wimlib_tchar *symlink_target; 910 }; 911 912 /** The number of directories scanned so far, not counting 913 * excluded/unsupported files. */ 914 uint64_t num_dirs_scanned; 915 916 /** The number of non-directories scanned so far, not counting 917 * excluded/unsupported files. */ 918 uint64_t num_nondirs_scanned; 919 920 /** The number of bytes of file data detected so far, not 921 * counting excluded/unsupported files. */ 922 uint64_t num_bytes_scanned; 923 } scan; 924 925 /** Valid on messages 926 * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN, 927 * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, 928 * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, 929 * ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE, 930 * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, 931 * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA, 932 * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, and 933 * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. 934 * 935 * Note: most of the time of an extraction operation will be spent 936 * extracting file data, and the application will receive 937 * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS during this time. Using @p 938 * completed_bytes and @p total_bytes, the application can calculate a 939 * percentage complete. However, there is no way for applications to 940 * know which file is currently being extracted. This is by design 941 * because the best way to complete the extraction operation is not 942 * necessarily file-by-file. 943 */ 944 struct wimlib_progress_info_extract { 945 946 /** The 1-based index of the image from which files are being 947 * extracted. */ 948 uint32_t image; 949 950 /** Extraction flags being used. */ 951 uint32_t extract_flags; 952 953 /** If the ::WIMStruct from which the extraction being performed 954 * has a backing file, then this is an absolute path to that 955 * backing file. Otherwise, this is @c NULL. */ 956 const wimlib_tchar *wimfile_name; 957 958 /** Name of the image from which files are being extracted, or 959 * the empty string if the image is unnamed. */ 960 const wimlib_tchar *image_name; 961 962 /** Path to the directory or NTFS volume to which the files are 963 * being extracted. */ 964 const wimlib_tchar *target; 965 966 /** Reserved. */ 967 const wimlib_tchar *reserved; 968 969 /** The number of bytes of file data that will be extracted. */ 970 uint64_t total_bytes; 971 972 /** The number of bytes of file data that have been extracted so 973 * far. This starts at 0 and ends at @p total_bytes. */ 974 uint64_t completed_bytes; 975 976 /** The number of file streams that will be extracted. This 977 * will often be similar to the "number of files", but for 978 * several reasons (hard links, named data streams, empty files, 979 * etc.) it can be different. */ 980 uint64_t total_streams; 981 982 /** The number of file streams that have been extracted so far. 983 * This starts at 0 and ends at @p total_streams. */ 984 uint64_t completed_streams; 985 986 /** Currently only used for 987 * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ 988 uint32_t part_number; 989 990 /** Currently only used for 991 * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ 992 uint32_t total_parts; 993 994 /** Currently only used for 995 * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ 996 uint8_t guid[WIMLIB_GUID_LEN]; 997 998 /** For ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE and 999 * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, this is the 1000 * number of files that have been processed so far. Once the 1001 * corresponding phase of extraction is complete, this value 1002 * will be equal to @c end_file_count. */ 1003 uint64_t current_file_count; 1004 1005 /** For ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE and 1006 * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, this is 1007 * total number of files that will be processed. 1008 * 1009 * This number is provided for informational purposes only, e.g. 1010 * for a progress bar. This number will not necessarily be 1011 * equal to the number of files actually being extracted. This 1012 * is because extraction backends are free to implement an 1013 * extraction algorithm that might be more efficient than 1014 * processing every file in the "extract file structure" and 1015 * "extract file metadata" phases. For example, the current 1016 * implementation of the UNIX extraction backend will create 1017 * files on-demand during the "extract file data" phase. 1018 * Therefore, when using that particular extraction backend, @p 1019 * end_file_count will only include directories and empty files. 1020 */ 1021 uint64_t end_file_count; 1022 } extract; 1023 1024 /** Valid on messages ::WIMLIB_PROGRESS_MSG_RENAME. */ 1025 struct wimlib_progress_info_rename { 1026 /** Name of the temporary file that the WIM was written to. */ 1027 const wimlib_tchar *from; 1028 1029 /** Name of the original WIM file to which the temporary file is 1030 * being renamed. */ 1031 const wimlib_tchar *to; 1032 } rename; 1033 1034 /** Valid on messages ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and 1035 * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND. */ 1036 struct wimlib_progress_info_update { 1037 /** Pointer to the update command that will be executed or has 1038 * just been executed. */ 1039 const struct wimlib_update_command *command; 1040 1041 /** Number of update commands that have been completed so far. 1042 */ 1043 size_t completed_commands; 1044 1045 /** Number of update commands that are being executed as part of 1046 * this call to wimlib_update_image(). */ 1047 size_t total_commands; 1048 } update; 1049 1050 /** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY and 1051 * ::WIMLIB_PROGRESS_MSG_CALC_INTEGRITY. */ 1052 struct wimlib_progress_info_integrity { 1053 1054 /** The number of bytes in the WIM file that are covered by 1055 * integrity checks. */ 1056 uint64_t total_bytes; 1057 1058 /** The number of bytes that have been checksummed so far. This 1059 * starts at 0 and ends at @p total_bytes. */ 1060 uint64_t completed_bytes; 1061 1062 /** The number of individually checksummed "chunks" the 1063 * integrity-checked region is divided into. */ 1064 uint32_t total_chunks; 1065 1066 /** The number of chunks that have been checksummed so far. 1067 * This starts at 0 and ends at @p total_chunks. */ 1068 uint32_t completed_chunks; 1069 1070 /** The size of each individually checksummed "chunk" in the 1071 * integrity-checked region. */ 1072 uint32_t chunk_size; 1073 1074 /** For ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY messages, this is 1075 * the path to the WIM file being checked. */ 1076 const wimlib_tchar *filename; 1077 } integrity; 1078 1079 /** Valid on messages ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and 1080 * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART. */ 1081 struct wimlib_progress_info_split { 1082 /** Total size of the original WIM's file and metadata resources 1083 * (compressed). */ 1084 uint64_t total_bytes; 1085 1086 /** Number of bytes of file and metadata resources that have 1087 * been copied out of the original WIM so far. Will be 0 1088 * initially, and equal to @p total_bytes at the end. */ 1089 uint64_t completed_bytes; 1090 1091 /** Number of the split WIM part that is about to be started 1092 * (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been 1093 * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */ 1094 unsigned cur_part_number; 1095 1096 /** Total number of split WIM parts that are being written. */ 1097 unsigned total_parts; 1098 1099 /** Name of the split WIM part that is about to be started 1100 * (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been 1101 * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). Since 1102 * wimlib v1.7.0, the library user may change this when 1103 * receiving ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART in order to 1104 * cause the next split WIM part to be written to a different 1105 * location. */ 1106 wimlib_tchar *part_name; 1107 } split; 1108 1109 /** Valid on messages ::WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM */ 1110 struct wimlib_progress_info_replace { 1111 /** Path to the file in the image that is being replaced */ 1112 const wimlib_tchar *path_in_wim; 1113 } replace; 1114 1115 /** Valid on messages ::WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE */ 1116 struct wimlib_progress_info_wimboot_exclude { 1117 /** Path to the file in the image */ 1118 const wimlib_tchar *path_in_wim; 1119 1120 /** Path to which the file is being extracted */ 1121 const wimlib_tchar *extraction_path; 1122 } wimboot_exclude; 1123 1124 /** Valid on messages ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN. */ 1125 struct wimlib_progress_info_unmount { 1126 /** Path to directory being unmounted */ 1127 const wimlib_tchar *mountpoint; 1128 1129 /** Path to WIM file being unmounted */ 1130 const wimlib_tchar *mounted_wim; 1131 1132 /** 1-based index of image being unmounted. */ 1133 uint32_t mounted_image; 1134 1135 /** Flags that were passed to wimlib_mount_image() when the 1136 * mountpoint was set up. */ 1137 uint32_t mount_flags; 1138 1139 /** Flags passed to wimlib_unmount_image(). */ 1140 uint32_t unmount_flags; 1141 } unmount; 1142 1143 /** Valid on messages ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE. */ 1144 struct wimlib_progress_info_done_with_file { 1145 /** 1146 * Path to the file whose data has been written to the WIM file, 1147 * or is currently being asynchronously compressed in memory, 1148 * and therefore is no longer needed by wimlib. 1149 * 1150 * WARNING: The file data will not actually be accessible in the 1151 * WIM file until the WIM file has been completely written. 1152 * Ordinarily you should <b>not</b> treat this message as a 1153 * green light to go ahead and delete the specified file, since 1154 * that would result in data loss if the WIM file cannot be 1155 * successfully created for any reason. 1156 * 1157 * If a file has multiple names (hard links), 1158 * ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE will only be received 1159 * for one name. Also, this message will not be received for 1160 * empty files or reparse points (or symbolic links), unless 1161 * they have nonempty named data streams. 1162 */ 1163 const wimlib_tchar *path_to_file; 1164 } done_with_file; 1165 1166 /** Valid on messages ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE and 1167 * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE. */ 1168 struct wimlib_progress_info_verify_image { 1169 const wimlib_tchar *wimfile; 1170 uint32_t total_images; 1171 uint32_t current_image; 1172 } verify_image; 1173 1174 /** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS. */ 1175 struct wimlib_progress_info_verify_streams { 1176 const wimlib_tchar *wimfile; 1177 uint64_t total_streams; 1178 uint64_t total_bytes; 1179 uint64_t completed_streams; 1180 uint64_t completed_bytes; 1181 } verify_streams; 1182 1183 /** Valid on messages ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION. */ 1184 struct wimlib_progress_info_test_file_exclusion { 1185 1186 /** 1187 * Path to the file for which exclusion is being tested. 1188 * 1189 * UNIX capture mode: The path will be a standard relative or 1190 * absolute UNIX filesystem path. 1191 * 1192 * NTFS-3G capture mode: The path will be given relative to the 1193 * root of the NTFS volume, with a leading slash. 1194 * 1195 * Windows capture mode: The path will be a Win32 namespace 1196 * path to the file. 1197 */ 1198 const wimlib_tchar *path; 1199 1200 /** 1201 * Indicates whether the file or directory will be excluded from 1202 * capture or not. This will be <c>false</c> by default. The 1203 * progress function can set this to <c>true</c> if it decides 1204 * that the file needs to be excluded. 1205 */ 1206 bool will_exclude; 1207 } test_file_exclusion; 1208 1209 /** Valid on messages ::WIMLIB_PROGRESS_MSG_HANDLE_ERROR. */ 1210 struct wimlib_progress_info_handle_error { 1211 1212 /** Path to the file for which the error occurred, or NULL if 1213 * not relevant. */ 1214 const wimlib_tchar *path; 1215 1216 /** The wimlib error code associated with the error. */ 1217 int error_code; 1218 1219 /** 1220 * Indicates whether the error will be ignored or not. This 1221 * will be <c>false</c> by default; the progress function may 1222 * set it to <c>true</c>. 1223 */ 1224 bool will_ignore; 1225 } handle_error; 1226 }; 1227 1228 /** 1229 * A user-supplied function that will be called periodically during certain WIM 1230 * operations. 1231 * 1232 * The first argument will be the type of operation that is being performed or 1233 * is about to be started or has been completed. 1234 * 1235 * The second argument will be a pointer to one of a number of structures 1236 * depending on the first argument. It may be @c NULL for some message types. 1237 * Note that although this argument is not @c const, users should not modify it 1238 * except in explicitly documented cases. 1239 * 1240 * The third argument will be a user-supplied value that was provided when 1241 * registering or specifying the progress function. 1242 * 1243 * This function must return one of the ::wimlib_progress_status values. By 1244 * default, you should return ::WIMLIB_PROGRESS_STATUS_CONTINUE (0). 1245 */ 1246 typedef enum wimlib_progress_status 1247 (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, 1248 union wimlib_progress_info *info, 1249 void *progctx); 1250 1251 /** @} */ 1252 /** @addtogroup G_modifying_wims 1253 * @{ */ 1254 1255 /** An array of these structures is passed to wimlib_add_image_multisource() to 1256 * specify the sources from which to create a WIM image. */ 1257 struct wimlib_capture_source { 1258 /** Absolute or relative path to a file or directory on the external 1259 * filesystem to be included in the image. */ 1260 wimlib_tchar *fs_source_path; 1261 1262 /** Destination path in the image. To specify the root directory of the 1263 * image, use ::WIMLIB_WIM_ROOT_PATH. */ 1264 wimlib_tchar *wim_target_path; 1265 1266 /** Reserved; set to 0. */ 1267 long reserved; 1268 }; 1269 1270 /** Set or unset the "readonly" WIM header flag (<c>WIM_HDR_FLAG_READONLY</c> in 1271 * Microsoft's documentation), based on the ::wimlib_wim_info.is_marked_readonly 1272 * member of the @p info parameter. This is distinct from basic file 1273 * permissions; this flag can be set on a WIM file that is physically writable. 1274 * 1275 * wimlib disallows modifying on-disk WIM files with the readonly flag set. 1276 * However, wimlib_overwrite() with ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 1277 * will override this --- and in fact, this is necessary to set the readonly 1278 * flag persistently on an existing WIM file. 1279 */ 1280 #define WIMLIB_CHANGE_READONLY_FLAG 0x00000001 1281 1282 /** Set the GUID (globally unique identifier) of the WIM file to the value 1283 * specified in ::wimlib_wim_info.guid of the @p info parameter. */ 1284 #define WIMLIB_CHANGE_GUID 0x00000002 1285 1286 /** Change the bootable image of the WIM to the value specified in 1287 * ::wimlib_wim_info.boot_index of the @p info parameter. */ 1288 #define WIMLIB_CHANGE_BOOT_INDEX 0x00000004 1289 1290 /** Change the <c>WIM_HDR_FLAG_RP_FIX</c> flag of the WIM file to the value 1291 * specified in ::wimlib_wim_info.has_rpfix of the @p info parameter. This flag 1292 * generally indicates whether an image in the WIM has been captured with 1293 * reparse-point fixups enabled. wimlib also treats this flag as specifying 1294 * whether to do reparse-point fixups by default when capturing or applying WIM 1295 * images. */ 1296 #define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 1297 1298 /** @} */ 1299 1300 /** @addtogroup G_wim_information */ 1301 1302 /** @{ */ 1303 1304 /** 1305 * General information about a WIM file. 1306 * 1307 * This info can also be requested for a ::WIMStruct that does not have a 1308 * backing file. In this case, fields that only make sense given a backing file 1309 * are set to default values. 1310 */ 1311 struct wimlib_wim_info { 1312 1313 /** The globally unique identifier for this WIM. (Note: all parts of a 1314 * split WIM normally have identical GUIDs.) */ 1315 uint8_t guid[WIMLIB_GUID_LEN]; 1316 1317 /** The number of images in this WIM file. */ 1318 uint32_t image_count; 1319 1320 /** The 1-based index of the bootable image in this WIM file, or 0 if no 1321 * image is bootable. */ 1322 uint32_t boot_index; 1323 1324 /** The version of the WIM file format used in this WIM file. */ 1325 uint32_t wim_version; 1326 1327 /** The default compression chunk size of resources in this WIM file. 1328 */ 1329 uint32_t chunk_size; 1330 1331 /** For split WIMs, the 1-based index of this part within the split WIM; 1332 * otherwise 1. */ 1333 uint16_t part_number; 1334 1335 /** For split WIMs, the total number of parts in the split WIM; 1336 * otherwise 1. */ 1337 uint16_t total_parts; 1338 1339 /** The default compression type of resources in this WIM file, as one 1340 * of the ::wimlib_compression_type constants. */ 1341 int32_t compression_type; 1342 1343 /** The size of this WIM file in bytes, excluding the XML data and 1344 * integrity table. */ 1345 uint64_t total_bytes; 1346 1347 /** 1 iff this WIM file has an integrity table. */ 1348 uint32_t has_integrity_table : 1; 1349 1350 /** 1 iff this info struct is for a ::WIMStruct that has a backing file. 1351 */ 1352 uint32_t opened_from_file : 1; 1353 1354 /** 1 iff this WIM file is considered readonly for any reason (e.g. the 1355 * "readonly" header flag is set, or this is part of a split WIM, or 1356 * filesystem permissions deny writing) */ 1357 uint32_t is_readonly : 1; 1358 1359 /** 1 iff the "reparse point fix" flag is set in this WIM's header */ 1360 uint32_t has_rpfix : 1; 1361 1362 /** 1 iff the "readonly" flag is set in this WIM's header */ 1363 uint32_t is_marked_readonly : 1; 1364 1365 /** 1 iff the "spanned" flag is set in this WIM's header */ 1366 uint32_t spanned : 1; 1367 1368 /** 1 iff the "write in progress" flag is set in this WIM's header */ 1369 uint32_t write_in_progress : 1; 1370 1371 /** 1 iff the "metadata only" flag is set in this WIM's header */ 1372 uint32_t metadata_only : 1; 1373 1374 /** 1 iff the "resource only" flag is set in this WIM's header */ 1375 uint32_t resource_only : 1; 1376 1377 /** 1 iff this WIM file is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */ 1378 uint32_t pipable : 1; 1379 uint32_t reserved_flags : 22; 1380 uint32_t reserved[9]; 1381 }; 1382 1383 /** 1384 * Information about a "blob", which is a fixed length sequence of binary data. 1385 * Each nonempty stream of each file in a WIM image is associated with a blob. 1386 * Blobs are deduplicated within a WIM file. 1387 * 1388 * TODO: this struct needs to be renamed, and perhaps made into a union since 1389 * there are several cases. I'll try to list them below: 1390 * 1391 * 1. The blob is "missing", meaning that it is referenced by hash but not 1392 * actually present in the WIM file. In this case we only know the 1393 * sha1_hash. This case can only occur with wimlib_iterate_dir_tree(), never 1394 * wimlib_iterate_lookup_table(). 1395 * 1396 * 2. Otherwise we know the sha1_hash, the uncompressed_size, the 1397 * reference_count, and the is_metadata flag. In addition: 1398 * 1399 * A. If the blob is located in a non-solid WIM resource, then we also know 1400 * the compressed_size and offset. 1401 * 1402 * B. If the blob is located in a solid WIM resource, then we also know the 1403 * offset, raw_resource_offset_in_wim, raw_resource_compressed_size, and 1404 * raw_resource_uncompressed_size. But the "offset" is actually the 1405 * offset in the uncompressed solid resource rather than the offset from 1406 * the beginning of the WIM file. 1407 * 1408 * C. If the blob is *not* located in any type of WIM resource, then we don't 1409 * know any additional information. 1410 * 1411 * Unknown or irrelevant fields are left zeroed. 1412 */ 1413 struct wimlib_resource_entry { 1414 1415 /** If this blob is not missing, then this is the uncompressed size of 1416 * this blob in bytes. */ 1417 uint64_t uncompressed_size; 1418 1419 /** If this blob is located in a non-solid WIM resource, then this is 1420 * the compressed size of that resource. */ 1421 uint64_t compressed_size; 1422 1423 /** If this blob is located in a non-solid WIM resource, then this is 1424 * the offset of that resource within the WIM file containing it. If 1425 * this blob is located in a solid WIM resource, then this is the offset 1426 * of this blob within that solid resource when uncompressed. */ 1427 uint64_t offset; 1428 1429 /** The SHA-1 message digest of the blob's uncompressed contents. */ 1430 uint8_t sha1_hash[20]; 1431 1432 /** If this blob is located in a WIM resource, then this is the part 1433 * number of the WIM file containing it. */ 1434 uint32_t part_number; 1435 1436 /** If this blob is not missing, then this is the number of times this 1437 * blob is referenced over all images in the WIM. This number is not 1438 * guaranteed to be correct. */ 1439 uint32_t reference_count; 1440 1441 /** 1 iff this blob is located in a non-solid compressed WIM resource. 1442 */ 1443 uint32_t is_compressed : 1; 1444 1445 /** 1 iff this blob contains the metadata for an image. */ 1446 uint32_t is_metadata : 1; 1447 1448 uint32_t is_free : 1; 1449 uint32_t is_spanned : 1; 1450 1451 /** 1 iff a blob with this hash was not found in the blob lookup table 1452 * of the ::WIMStruct. This normally implies a missing call to 1453 * wimlib_reference_resource_files() or wimlib_reference_resources(). */ 1454 uint32_t is_missing : 1; 1455 1456 /** 1 iff this blob is located in a solid resource. */ 1457 uint32_t packed : 1; 1458 1459 uint32_t reserved_flags : 26; 1460 1461 /** If this blob is located in a solid WIM resource, then this is the 1462 * offset of that solid resource within the WIM file containing it. */ 1463 uint64_t raw_resource_offset_in_wim; 1464 1465 /** If this blob is located in a solid WIM resource, then this is the 1466 * compressed size of that solid resource. */ 1467 uint64_t raw_resource_compressed_size; 1468 1469 /** If this blob is located in a solid WIM resource, then this is the 1470 * uncompressed size of that solid resource. */ 1471 uint64_t raw_resource_uncompressed_size; 1472 1473 uint64_t reserved[1]; 1474 }; 1475 1476 /** 1477 * Information about a stream of a particular file in the WIM. 1478 * 1479 * Normally, only WIM images captured from NTFS filesystems will have multiple 1480 * streams per file. In practice, this is a rarely used feature of the 1481 * filesystem. 1482 * 1483 * TODO: the library now explicitly tracks stream types, which allows it to have 1484 * multiple unnamed streams (e.g. both a reparse point stream and unnamed data 1485 * stream). However, this isn't yet exposed by wimlib_iterate_dir_tree(). 1486 */ 1487 struct wimlib_stream_entry { 1488 1489 /** Name of the stream, or NULL if the stream is unnamed. */ 1490 const wimlib_tchar *stream_name; 1491 1492 /** Info about this stream's data, such as its hash and size if known.*/ 1493 struct wimlib_resource_entry resource; 1494 1495 uint64_t reserved[4]; 1496 }; 1497 1498 /** 1499 * Since wimlib v1.9.1: an object ID, which is an extra piece of metadata that 1500 * may be associated with a file on NTFS filesystems. See: 1501 * https://msdn.microsoft.com/en-us/library/windows/desktop/aa363997(v=vs.85).aspx 1502 */ 1503 struct wimlib_object_id { 1504 uint8_t object_id[WIMLIB_GUID_LEN]; 1505 uint8_t birth_volume_id[WIMLIB_GUID_LEN]; 1506 uint8_t birth_object_id[WIMLIB_GUID_LEN]; 1507 uint8_t domain_id[WIMLIB_GUID_LEN]; 1508 }; 1509 1510 /** Structure passed to the wimlib_iterate_dir_tree() callback function. 1511 * Roughly, the information about a "file" in the WIM image --- but really a 1512 * directory entry ("dentry") because hard links are allowed. The 1513 * hard_link_group_id field can be used to distinguish actual file inodes. */ 1514 struct wimlib_dir_entry { 1515 /** Name of the file, or NULL if this file is unnamed. Only the root 1516 * directory of an image will be unnamed. */ 1517 const wimlib_tchar *filename; 1518 1519 /** 8.3 name (or "DOS name", or "short name") of this file; or NULL if 1520 * this file has no such name. */ 1521 const wimlib_tchar *dos_name; 1522 1523 /** Full path to this file within the image. Path separators will be 1524 * ::WIMLIB_WIM_PATH_SEPARATOR. */ 1525 const wimlib_tchar *full_path; 1526 1527 /** Depth of this directory entry, where 0 is the root, 1 is the root's 1528 * children, ..., etc. */ 1529 size_t depth; 1530 1531 /** Pointer to the security descriptor for this file, in Windows 1532 * SECURITY_DESCRIPTOR_RELATIVE format, or NULL if this file has no 1533 * security descriptor. */ 1534 const char *security_descriptor; 1535 1536 /** Size of the above security descriptor, in bytes. */ 1537 size_t security_descriptor_size; 1538 1539 #define WIMLIB_FILE_ATTRIBUTE_READONLY 0x00000001 1540 #define WIMLIB_FILE_ATTRIBUTE_HIDDEN 0x00000002 1541 #define WIMLIB_FILE_ATTRIBUTE_SYSTEM 0x00000004 1542 #define WIMLIB_FILE_ATTRIBUTE_DIRECTORY 0x00000010 1543 #define WIMLIB_FILE_ATTRIBUTE_ARCHIVE 0x00000020 1544 #define WIMLIB_FILE_ATTRIBUTE_DEVICE 0x00000040 1545 #define WIMLIB_FILE_ATTRIBUTE_NORMAL 0x00000080 1546 #define WIMLIB_FILE_ATTRIBUTE_TEMPORARY 0x00000100 1547 #define WIMLIB_FILE_ATTRIBUTE_SPARSE_FILE 0x00000200 1548 #define WIMLIB_FILE_ATTRIBUTE_REPARSE_POINT 0x00000400 1549 #define WIMLIB_FILE_ATTRIBUTE_COMPRESSED 0x00000800 1550 #define WIMLIB_FILE_ATTRIBUTE_OFFLINE 0x00001000 1551 #define WIMLIB_FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 0x00002000 1552 #define WIMLIB_FILE_ATTRIBUTE_ENCRYPTED 0x00004000 1553 #define WIMLIB_FILE_ATTRIBUTE_VIRTUAL 0x00010000 1554 /** File attributes, such as whether the file is a directory or not. 1555 * These are the "standard" Windows FILE_ATTRIBUTE_* values, although in 1556 * wimlib.h they are defined as WIMLIB_FILE_ATTRIBUTE_* for convenience 1557 * on other platforms. */ 1558 uint32_t attributes; 1559 1560 #define WIMLIB_REPARSE_TAG_RESERVED_ZERO 0x00000000 1561 #define WIMLIB_REPARSE_TAG_RESERVED_ONE 0x00000001 1562 #define WIMLIB_REPARSE_TAG_MOUNT_POINT 0xA0000003 1563 #define WIMLIB_REPARSE_TAG_HSM 0xC0000004 1564 #define WIMLIB_REPARSE_TAG_HSM2 0x80000006 1565 #define WIMLIB_REPARSE_TAG_DRIVER_EXTENDER 0x80000005 1566 #define WIMLIB_REPARSE_TAG_SIS 0x80000007 1567 #define WIMLIB_REPARSE_TAG_DFS 0x8000000A 1568 #define WIMLIB_REPARSE_TAG_DFSR 0x80000012 1569 #define WIMLIB_REPARSE_TAG_FILTER_MANAGER 0x8000000B 1570 #define WIMLIB_REPARSE_TAG_WOF 0x80000017 1571 #define WIMLIB_REPARSE_TAG_SYMLINK 0xA000000C 1572 /** If the file is a reparse point (FILE_ATTRIBUTE_REPARSE_POINT set in 1573 * the attributes), this will give the reparse tag. This tells you 1574 * whether the reparse point is a symbolic link, junction point, or some 1575 * other, more unusual kind of reparse point. */ 1576 uint32_t reparse_tag; 1577 1578 /** Number of links to this file's inode (hard links). 1579 * 1580 * Currently, this will always be 1 for directories. However, it can be 1581 * greater than 1 for nondirectory files. */ 1582 uint32_t num_links; 1583 1584 /** Number of named data streams this file has. Normally 0. */ 1585 uint32_t num_named_streams; 1586 1587 /** A unique identifier for this file's inode. However, as a special 1588 * case, if the inode only has a single link (@p num_links == 1), this 1589 * value may be 0. 1590 * 1591 * Note: if a WIM image is captured from a filesystem, this value is not 1592 * guaranteed to be the same as the original number of the inode on the 1593 * filesystem. */ 1594 uint64_t hard_link_group_id; 1595 1596 /** Time this file was created. */ 1597 struct wimlib_timespec creation_time; 1598 1599 /** Time this file was last written to. */ 1600 struct wimlib_timespec last_write_time; 1601 1602 /** Time this file was last accessed. */ 1603 struct wimlib_timespec last_access_time; 1604 1605 /** The UNIX user ID of this file. This is a wimlib extension. 1606 * 1607 * This field is only valid if @p unix_mode != 0. */ 1608 uint32_t unix_uid; 1609 1610 /** The UNIX group ID of this file. This is a wimlib extension. 1611 * 1612 * This field is only valid if @p unix_mode != 0. */ 1613 uint32_t unix_gid; 1614 1615 /** The UNIX mode of this file. This is a wimlib extension. 1616 * 1617 * If this field is 0, then @p unix_uid, @p unix_gid, @p unix_mode, and 1618 * @p unix_rdev are all unknown (fields are not present in the WIM 1619 * image). */ 1620 uint32_t unix_mode; 1621 1622 /** The UNIX device ID (major and minor number) of this file. This is a 1623 * wimlib extension. 1624 * 1625 * This field is only valid if @p unix_mode != 0. */ 1626 uint32_t unix_rdev; 1627 1628 /* The object ID of this file, if any. Only valid if 1629 * object_id.object_id is not all zeroes. */ 1630 struct wimlib_object_id object_id; 1631 1632 /** High 32 bits of the seconds portion of the creation timestamp, 1633 * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */ 1634 int32_t creation_time_high; 1635 1636 /** High 32 bits of the seconds portion of the last write timestamp, 1637 * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */ 1638 int32_t last_write_time_high; 1639 1640 /** High 32 bits of the seconds portion of the last access timestamp, 1641 * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */ 1642 int32_t last_access_time_high; 1643 1644 int32_t reserved2; 1645 1646 uint64_t reserved[4]; 1647 1648 /** 1649 * Variable-length array of streams that make up this file. 1650 * 1651 * The first entry will always exist and will correspond to the unnamed 1652 * data stream (default file contents), so it will have <c>stream_name 1653 * == NULL</c>. Alternatively, for reparse point files, the first entry 1654 * will correspond to the reparse data stream. Alternatively, for 1655 * encrypted files, the first entry will correspond to the encrypted 1656 * data. 1657 * 1658 * Then, following the first entry, there be @p num_named_streams 1659 * additional entries that specify the named data streams, if any, each 1660 * of which will have <c>stream_name != NULL</c>. 1661 */ 1662 struct wimlib_stream_entry streams[]; 1663 }; 1664 1665 /** 1666 * Type of a callback function to wimlib_iterate_dir_tree(). Must return 0 on 1667 * success. 1668 */ 1669 typedef int (*wimlib_iterate_dir_tree_callback_t)(const struct wimlib_dir_entry *dentry, 1670 void *user_ctx); 1671 1672 /** 1673 * Type of a callback function to wimlib_iterate_lookup_table(). Must return 0 1674 * on success. 1675 */ 1676 typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resource_entry *resource, 1677 void *user_ctx); 1678 1679 /** For wimlib_iterate_dir_tree(): Iterate recursively on children rather than 1680 * just on the specified path. */ 1681 #define WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE 0x00000001 1682 1683 /** For wimlib_iterate_dir_tree(): Don't iterate on the file or directory 1684 * itself; only its children (in the case of a non-empty directory) */ 1685 #define WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN 0x00000002 1686 1687 /** Return ::WIMLIB_ERR_RESOURCE_NOT_FOUND if any file data blobs needed to fill 1688 * in the ::wimlib_resource_entry's for the iteration cannot be found in the 1689 * blob lookup table of the ::WIMStruct. The default behavior without this flag 1690 * is to fill in the @ref wimlib_resource_entry::sha1_hash "sha1_hash" and set 1691 * the @ref wimlib_resource_entry::is_missing "is_missing" flag. */ 1692 #define WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED 0x00000004 1693 1694 1695 /** @} */ 1696 /** @addtogroup G_modifying_wims 1697 * @{ */ 1698 1699 /** UNIX-like systems only: Directly capture an NTFS volume rather than a 1700 * generic directory. This requires that wimlib was compiled with support for 1701 * libntfs-3g. 1702 * 1703 * This flag cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or 1704 * ::WIMLIB_ADD_FLAG_UNIX_DATA. 1705 * 1706 * Do not use this flag on Windows, where wimlib already supports all 1707 * Windows-native filesystems, including NTFS, through the Windows APIs. */ 1708 #define WIMLIB_ADD_FLAG_NTFS 0x00000001 1709 1710 /** Follow symbolic links when scanning the directory tree. Currently only 1711 * supported on UNIX-like systems. */ 1712 #define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002 1713 1714 /** Call the progress function with the message 1715 * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been 1716 * scanned. */ 1717 #define WIMLIB_ADD_FLAG_VERBOSE 0x00000004 1718 1719 /** Mark the image being added as the bootable image of the WIM. This flag is 1720 * valid only for wimlib_add_image() and wimlib_add_image_multisource(). 1721 * 1722 * Note that you can also change the bootable image of a WIM using 1723 * wimlib_set_wim_info(). 1724 * 1725 * Note: ::WIMLIB_ADD_FLAG_BOOT does something different from, and independent 1726 * from, ::WIMLIB_ADD_FLAG_WIMBOOT. */ 1727 #define WIMLIB_ADD_FLAG_BOOT 0x00000008 1728 1729 /** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID 1730 * (major and minor number) of each file. In addition, capture special files 1731 * such as device nodes and FIFOs. Since wimlib v1.11.0, on Linux also capture 1732 * extended attributes. See the documentation for the <b>--unix-data</b> option 1733 * to <b>wimcapture</b> for more information. */ 1734 #define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 1735 1736 /** Do not capture security descriptors. Only has an effect in NTFS-3G capture 1737 * mode, or in Windows native builds. */ 1738 #define WIMLIB_ADD_FLAG_NO_ACLS 0x00000020 1739 1740 /** Fail immediately if the full security descriptor of any file or directory 1741 * cannot be accessed. Only has an effect in Windows native builds. The 1742 * default behavior without this flag is to first try omitting the SACL from the 1743 * security descriptor, then to try omitting the security descriptor entirely. 1744 */ 1745 #define WIMLIB_ADD_FLAG_STRICT_ACLS 0x00000040 1746 1747 /** Call the progress function with the message 1748 * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from 1749 * capture. This is a subset of the messages provided by 1750 * ::WIMLIB_ADD_FLAG_VERBOSE. */ 1751 #define WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE 0x00000080 1752 1753 /** Reparse-point fixups: Modify absolute symbolic links (and junctions, in the 1754 * case of Windows) that point inside the directory being captured to instead be 1755 * absolute relative to the directory being captured. 1756 * 1757 * Without this flag, the default is to do reparse-point fixups if 1758 * <c>WIM_HDR_FLAG_RP_FIX</c> is set in the WIM header or if this is the first 1759 * image being added. */ 1760 #define WIMLIB_ADD_FLAG_RPFIX 0x00000100 1761 1762 /** Don't do reparse point fixups. See ::WIMLIB_ADD_FLAG_RPFIX. */ 1763 #define WIMLIB_ADD_FLAG_NORPFIX 0x00000200 1764 1765 /** Do not automatically exclude unsupported files or directories from capture, 1766 * such as encrypted files in NTFS-3G capture mode, or device files and FIFOs on 1767 * UNIX-like systems when not also using ::WIMLIB_ADD_FLAG_UNIX_DATA. Instead, 1768 * fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when such a file is encountered. */ 1769 #define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400 1770 1771 /** 1772 * Automatically select a capture configuration appropriate for capturing 1773 * filesystems containing Windows operating systems. For example, 1774 * <c>/pagefile.sys</c> and <c>"/System Volume Information"</c> will be 1775 * excluded. 1776 * 1777 * When this flag is specified, the corresponding @p config parameter (for 1778 * wimlib_add_image()) or member (for wimlib_update_image()) must be @c NULL. 1779 * Otherwise, ::WIMLIB_ERR_INVALID_PARAM will be returned. 1780 * 1781 * Note that the default behavior--- that is, when neither 1782 * ::WIMLIB_ADD_FLAG_WINCONFIG nor ::WIMLIB_ADD_FLAG_WIMBOOT is specified and @p 1783 * config is @c NULL--- is to use no capture configuration, meaning that no 1784 * files are excluded from capture. 1785 */ 1786 #define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800 1787 1788 /** 1789 * Capture image as "WIMBoot compatible". In addition, if no capture 1790 * configuration file is explicitly specified use the capture configuration file 1791 * <c>$SOURCE/Windows/System32/WimBootCompress.ini</c> if it exists, where 1792 * <c>$SOURCE</c> is the directory being captured; or, if a capture 1793 * configuration file is explicitly specified, use it and also place it at 1794 * <c>/Windows/System32/WimBootCompress.ini</c> in the WIM image. 1795 * 1796 * This flag does not, by itself, change the compression type or chunk size. 1797 * Before writing the WIM file, you may wish to set the compression format to 1798 * be the same as that used by WIMGAPI and DISM: 1799 * 1800 * \code 1801 * wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS); 1802 * wimlib_set_output_chunk_size(wim, 4096); 1803 * \endcode 1804 * 1805 * However, "WIMBoot" also works with other XPRESS chunk sizes as well as LZX 1806 * with 32768 byte chunks. 1807 * 1808 * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and 1809 * independent from, ::WIMLIB_ADD_FLAG_BOOT. 1810 * 1811 * Since wimlib v1.8.3, ::WIMLIB_ADD_FLAG_WIMBOOT also causes offline WIM-backed 1812 * files to be added as the "real" files rather than as their reparse points, 1813 * provided that their data is already present in the WIM. This feature can be 1814 * useful when updating a backing WIM file in an "offline" state. 1815 */ 1816 #define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000 1817 1818 /** 1819 * If the add command involves adding a non-directory file to a location at 1820 * which there already exists a nondirectory file in the image, issue 1821 * ::WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file. This was the 1822 * default behavior before wimlib v1.7.0. 1823 */ 1824 #define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000 1825 1826 /** 1827 * Send ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress 1828 * function. 1829 * 1830 * Note: This method for file exclusions is independent from the capture 1831 * configuration file mechanism. 1832 */ 1833 #define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000 1834 1835 /** 1836 * Since wimlib v1.9.0: create a temporary filesystem snapshot of the source 1837 * directory and add the files from it. Currently, this option is only 1838 * supported on Windows, where it uses the Volume Shadow Copy Service (VSS). 1839 * Using this option, you can create a consistent backup of the system volume of 1840 * a running Windows system without running into problems with locked files. 1841 * For the VSS snapshot to be successfully created, your application must be run 1842 * as an Administrator, and it cannot be run in WoW64 mode (i.e. if Windows is 1843 * 64-bit, then your application must be 64-bit as well). 1844 */ 1845 #define WIMLIB_ADD_FLAG_SNAPSHOT 0x00008000 1846 1847 /** 1848 * Since wimlib v1.9.0: permit the library to discard file paths after the 1849 * initial scan. If the application won't use 1850 * ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES while writing the WIM 1851 * archive, this flag can be used to allow the library to enable optimizations 1852 * such as opening files by inode number rather than by path. Currently this 1853 * only makes a difference on Windows. 1854 */ 1855 #define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED 0x00010000 1856 1857 /** @} */ 1858 /** @addtogroup G_modifying_wims 1859 * @{ */ 1860 1861 /** Do not issue an error if the path to delete does not exist. */ 1862 #define WIMLIB_DELETE_FLAG_FORCE 0x00000001 1863 1864 /** Delete the file or directory tree recursively; if not specified, an error is 1865 * issued if the path to delete is a directory. */ 1866 #define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002 1867 1868 /** @} */ 1869 /** @addtogroup G_modifying_wims 1870 * @{ */ 1871 1872 /** 1873 * If a single image is being exported, mark it bootable in the destination WIM. 1874 * Alternatively, if ::WIMLIB_ALL_IMAGES is specified as the image to export, 1875 * the image in the source WIM (if any) that is marked as bootable is also 1876 * marked as bootable in the destination WIM. 1877 */ 1878 #define WIMLIB_EXPORT_FLAG_BOOT 0x00000001 1879 1880 /** Give the exported image(s) no names. Avoids problems with image name 1881 * collisions. 1882 */ 1883 #define WIMLIB_EXPORT_FLAG_NO_NAMES 0x00000002 1884 1885 /** Give the exported image(s) no descriptions. */ 1886 #define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS 0x00000004 1887 1888 /** This advises the library that the program is finished with the source 1889 * WIMStruct and will not attempt to access it after the call to 1890 * wimlib_export_image(), with the exception of the call to wimlib_free(). */ 1891 #define WIMLIB_EXPORT_FLAG_GIFT 0x00000008 1892 1893 /** 1894 * Mark each exported image as WIMBoot-compatible. 1895 * 1896 * Note: by itself, this does change the destination WIM's compression type, nor 1897 * does it add the file @c \\Windows\\System32\\WimBootCompress.ini in the WIM 1898 * image. Before writing the destination WIM, it's recommended to do something 1899 * like: 1900 * 1901 * \code 1902 * wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS); 1903 * wimlib_set_output_chunk_size(wim, 4096); 1904 * wimlib_add_tree(wim, image, L"myconfig.ini", 1905 * L"\\Windows\\System32\\WimBootCompress.ini", 0); 1906 * \endcode 1907 */ 1908 #define WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010 1909 1910 /** @} */ 1911 /** @addtogroup G_extracting_wims 1912 * @{ */ 1913 1914 /** Extract the image directly to an NTFS volume rather than a generic directory. 1915 * This mode is only available if wimlib was compiled with libntfs-3g support; 1916 * if not, ::WIMLIB_ERR_UNSUPPORTED will be returned. In this mode, the 1917 * extraction target will be interpreted as the path to an NTFS volume image (as 1918 * a regular file or block device) rather than a directory. It will be opened 1919 * using libntfs-3g, and the image will be extracted to the NTFS filesystem's 1920 * root directory. Note: this flag cannot be used when wimlib_extract_image() 1921 * is called with ::WIMLIB_ALL_IMAGES as the @p image, nor can it be used with 1922 * wimlib_extract_paths() when passed multiple paths. */ 1923 #define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001 1924 1925 /** UNIX-like systems only: Extract UNIX-specific metadata captured with 1926 * ::WIMLIB_ADD_FLAG_UNIX_DATA. */ 1927 #define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020 1928 1929 /** Do not extract security descriptors. This flag cannot be combined with 1930 * ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS. */ 1931 #define WIMLIB_EXTRACT_FLAG_NO_ACLS 0x00000040 1932 1933 /** 1934 * Fail immediately if the full security descriptor of any file or directory 1935 * cannot be set exactly as specified in the WIM image. On Windows, the default 1936 * behavior without this flag when wimlib does not have permission to set the 1937 * correct security descriptor is to fall back to setting the security 1938 * descriptor with the SACL omitted, then with the DACL omitted, then with the 1939 * owner omitted, then not at all. This flag cannot be combined with 1940 * ::WIMLIB_EXTRACT_FLAG_NO_ACLS. 1941 */ 1942 #define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080 1943 1944 /** 1945 * This is the extraction equivalent to ::WIMLIB_ADD_FLAG_RPFIX. This forces 1946 * reparse-point fixups on, so absolute symbolic links or junction points will 1947 * be fixed to be absolute relative to the actual extraction root. Reparse- 1948 * point fixups are done by default for wimlib_extract_image() and 1949 * wimlib_extract_image_from_pipe() if <c>WIM_HDR_FLAG_RP_FIX</c> is set in the 1950 * WIM header. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_NORPFIX. 1951 */ 1952 #define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100 1953 1954 /** Force reparse-point fixups on extraction off, regardless of the state of the 1955 * WIM_HDR_FLAG_RP_FIX flag in the WIM header. This flag cannot be combined 1956 * with ::WIMLIB_EXTRACT_FLAG_RPFIX. */ 1957 #define WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200 1958 1959 /** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Extract the 1960 * paths, each of which must name a regular file, to standard output. */ 1961 #define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400 1962 1963 /** 1964 * Instead of ignoring files and directories with names that cannot be 1965 * represented on the current platform (note: Windows has more restrictions on 1966 * filenames than POSIX-compliant systems), try to replace characters or append 1967 * junk to the names so that they can be extracted in some form. 1968 * 1969 * Note: this flag is unlikely to have any effect when extracting a WIM image 1970 * that was captured on Windows. 1971 */ 1972 #define WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES 0x00000800 1973 1974 /** 1975 * On Windows, when there exist two or more files with the same case insensitive 1976 * name but different case sensitive names, try to extract them all by appending 1977 * junk to the end of them, rather than arbitrarily extracting only one. 1978 * 1979 * Note: this flag is unlikely to have any effect when extracting a WIM image 1980 * that was captured on Windows. 1981 */ 1982 #define WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS 0x00001000 1983 1984 /** Do not ignore failure to set timestamps on extracted files. This flag 1985 * currently only has an effect when extracting to a directory on UNIX-like 1986 * systems. */ 1987 #define WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS 0x00002000 1988 1989 /** Do not ignore failure to set short names on extracted files. This flag 1990 * currently only has an effect on Windows. */ 1991 #define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000 1992 1993 /** Do not ignore failure to extract symbolic links and junctions due to 1994 * permissions problems. This flag currently only has an effect on Windows. By 1995 * default, such failures are ignored since the default configuration of Windows 1996 * only allows the Administrator to create symbolic links. */ 1997 #define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000 1998 1999 /** 2000 * For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the 2001 * paths to extract as wildcard patterns ("globs") which may contain the 2002 * wildcard characters @c ? and @c *. The @c ? character matches any 2003 * non-path-separator character, whereas the @c * character matches zero or more 2004 * non-path-separator characters. Consequently, each glob may match zero or 2005 * more actual paths in the WIM image. 2006 * 2007 * By default, if a glob does not match any files, a warning but not an error 2008 * will be issued. This is the case even if the glob did not actually contain 2009 * wildcard characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB to get an error 2010 * instead. 2011 */ 2012 #define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000 2013 2014 /** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error 2015 * (::WIMLIB_ERR_PATH_DOES_NOT_EXIST) rather than a warning to be issued when 2016 * one of the provided globs did not match a file. */ 2017 #define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000 2018 2019 /** 2020 * Do not extract Windows file attributes such as readonly, hidden, etc. 2021 * 2022 * This flag has an effect on Windows as well as in the NTFS-3G extraction mode. 2023 */ 2024 #define WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES 0x00100000 2025 2026 /** 2027 * For wimlib_extract_paths() and wimlib_extract_pathlist() only: Do not 2028 * preserve the directory structure of the archive when extracting --- that is, 2029 * place each extracted file or directory tree directly in the target directory. 2030 * The target directory will still be created if it does not already exist. 2031 */ 2032 #define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000 2033 2034 /** 2035 * Windows only: Extract files as "pointers" back to the WIM archive. 2036 * 2037 * The effects of this option are fairly complex. See the documentation for the 2038 * <b>--wimboot</b> option of <b>wimapply</b> for more information. 2039 */ 2040 #define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 2041 2042 /** 2043 * Since wimlib v1.8.2 and Windows-only: compress the extracted files using 2044 * System Compression, when possible. This only works on either Windows 10 or 2045 * later, or on an older Windows to which Microsoft's wofadk.sys driver has been 2046 * added. Several different compression formats may be used with System 2047 * Compression; this particular flag selects the XPRESS compression format with 2048 * 4096 byte chunks. 2049 */ 2050 #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000 2051 2052 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with 2053 * 8192 byte chunks. */ 2054 #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000 2055 2056 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with 2057 * 16384 byte chunks. */ 2058 #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000 2059 2060 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with 2061 * 32768 byte chunks. */ 2062 #define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000 2063 2064 /** @} */ 2065 /** @addtogroup G_mounting_wim_images 2066 * @{ */ 2067 2068 /** Mount the WIM image read-write rather than the default of read-only. */ 2069 #define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001 2070 2071 /** Enable FUSE debugging by passing the @c -d option to @c fuse_main(). */ 2072 #define WIMLIB_MOUNT_FLAG_DEBUG 0x00000002 2073 2074 /** Do not allow accessing named data streams in the mounted WIM image. */ 2075 #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE 0x00000004 2076 2077 /** Access named data streams in the mounted WIM image through extended file 2078 * attributes named "user.X", where X is the name of a data stream. This is the 2079 * default mode. */ 2080 #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR 0x00000008 2081 2082 /** Access named data streams in the mounted WIM image by specifying the file 2083 * name, a colon, then the name of the data stream. */ 2084 #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010 2085 2086 /** Support UNIX owners, groups, modes, and special files. */ 2087 #define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020 2088 2089 /** Allow other users to see the mounted filesystem. This passes the @c 2090 * allow_other option to fuse_main(). */ 2091 #define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 2092 2093 /** @} */ 2094 /** @addtogroup G_creating_and_opening_wims 2095 * @{ */ 2096 2097 /** Verify the WIM contents against the WIM's integrity table, if present. The 2098 * integrity table stores checksums for the raw data of the WIM file, divided 2099 * into fixed size chunks. Verification will compute checksums and compare them 2100 * with the stored values. If there are any mismatches, then 2101 * ::WIMLIB_ERR_INTEGRITY will be issued. If the WIM file does not contain an 2102 * integrity table, then this flag has no effect. */ 2103 #define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001 2104 2105 /** Issue an error (::WIMLIB_ERR_IS_SPLIT_WIM) if the WIM is part of a split 2106 * WIM. Software can provide this flag for convenience if it explicitly does 2107 * not want to support split WIMs. */ 2108 #define WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT 0x00000002 2109 2110 /** Check if the WIM is writable and issue an error 2111 * (::WIMLIB_ERR_WIM_IS_READONLY) if it is not. A WIM is considered writable 2112 * only if it is writable at the filesystem level, does not have the 2113 * <c>WIM_HDR_FLAG_READONLY</c> flag set in its header, and is not part of a 2114 * spanned set. It is not required to provide this flag before attempting to 2115 * make changes to the WIM, but with this flag you get an error immediately 2116 * rather than potentially much later, when wimlib_overwrite() is finally 2117 * called. */ 2118 #define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004 2119 2120 /** @} */ 2121 /** @addtogroup G_mounting_wim_images 2122 * @{ */ 2123 2124 /** Provide ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image. 2125 * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ 2126 #define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001 2127 2128 /** Commit changes to the read-write mounted WIM image. 2129 * If this flag is not specified, changes will be discarded. */ 2130 #define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002 2131 2132 /** Provide ::WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image. 2133 * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ 2134 #define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004 2135 2136 /** Provide ::WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image. 2137 * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ 2138 #define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008 2139 2140 /** 2141 * In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM 2142 * image, forces all file descriptors to the open WIM image to be closed before 2143 * committing it. 2144 * 2145 * Without ::WIMLIB_UNMOUNT_FLAG_COMMIT or with a read-only mounted WIM image, 2146 * this flag has no effect. 2147 */ 2148 #define WIMLIB_UNMOUNT_FLAG_FORCE 0x00000010 2149 2150 /** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted 2151 * WIM image, causes the modified image to be committed to the WIM file as a 2152 * new, unnamed image appended to the archive. The original image in the WIM 2153 * file will be unmodified. */ 2154 #define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020 2155 2156 /** @} */ 2157 /** @addtogroup G_modifying_wims 2158 * @{ */ 2159 2160 /** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and 2161 * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */ 2162 #define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001 2163 2164 /** @} */ 2165 /** @addtogroup G_writing_and_overwriting_wims 2166 * @{ */ 2167 2168 /** 2169 * Include an integrity table in the resulting WIM file. 2170 * 2171 * For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to 2172 * include an integrity table if and only if one was present before. For 2173 * ::WIMStruct's created with wimlib_create_new_wim(), the default behavior is 2174 * to not include an integrity table. 2175 */ 2176 #define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY 0x00000001 2177 2178 /** 2179 * Do not include an integrity table in the resulting WIM file. This is the 2180 * default behavior, unless the ::WIMStruct was created by opening a WIM with an 2181 * integrity table. 2182 */ 2183 #define WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY 0x00000002 2184 2185 /** 2186 * Write the WIM as "pipable". After writing a WIM with this flag specified, 2187 * images from it can be applied directly from a pipe using 2188 * wimlib_extract_image_from_pipe(). See the documentation for the 2189 * <b>--pipable</b> option of <b>wimcapture</b> for more information. Beware: 2190 * WIMs written with this flag will not be compatible with Microsoft's software. 2191 * 2192 * For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to 2193 * write the WIM as pipable if and only if it was pipable before. For 2194 * ::WIMStruct's created with wimlib_create_new_wim(), the default behavior is 2195 * to write the WIM as non-pipable. 2196 */ 2197 #define WIMLIB_WRITE_FLAG_PIPABLE 0x00000004 2198 2199 /** 2200 * Do not write the WIM as "pipable". This is the default behavior, unless the 2201 * ::WIMStruct was created by opening a pipable WIM. 2202 */ 2203 #define WIMLIB_WRITE_FLAG_NOT_PIPABLE 0x00000008 2204 2205 /** 2206 * When writing data to the WIM file, recompress it, even if the data is already 2207 * available in the desired compressed form (for example, in a WIM file from 2208 * which an image has been exported using wimlib_export_image()). 2209 * 2210 * ::WIMLIB_WRITE_FLAG_RECOMPRESS can be used to recompress with a higher 2211 * compression ratio for the same compression type and chunk size. Simply using 2212 * the default compression settings may suffice for this, especially if the WIM 2213 * file was created using another program/library that may not use as 2214 * sophisticated compression algorithms. Or, 2215 * wimlib_set_default_compression_level() can be called beforehand to set an 2216 * even higher compression level than the default. 2217 * 2218 * If the WIM contains solid resources, then ::WIMLIB_WRITE_FLAG_RECOMPRESS can 2219 * be used in combination with ::WIMLIB_WRITE_FLAG_SOLID to prevent any solid 2220 * resources from being re-used. Otherwise, solid resources are re-used 2221 * somewhat more liberally than normal compressed resources. 2222 * 2223 * ::WIMLIB_WRITE_FLAG_RECOMPRESS does <b>not</b> cause recompression of data 2224 * that would not otherwise be written. For example, a call to 2225 * wimlib_overwrite() with ::WIMLIB_WRITE_FLAG_RECOMPRESS will not, by itself, 2226 * cause already-existing data in the WIM file to be recompressed. To force the 2227 * WIM file to be fully rebuilt and recompressed, combine 2228 * ::WIMLIB_WRITE_FLAG_RECOMPRESS with ::WIMLIB_WRITE_FLAG_REBUILD. 2229 */ 2230 #define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000010 2231 2232 /** 2233 * Immediately before closing the WIM file, sync its data to disk. 2234 * 2235 * This flag forces the function to wait until the data is safely on disk before 2236 * returning success. Otherwise, modern operating systems tend to cache data 2237 * for some time (in some cases, 30+ seconds) before actually writing it to 2238 * disk, even after reporting to the application that the writes have succeeded. 2239 * 2240 * wimlib_overwrite() will set this flag automatically if it decides to 2241 * overwrite the WIM file via a temporary file instead of in-place. This is 2242 * necessary on POSIX systems; it will, for example, avoid problems with delayed 2243 * allocation on ext4. 2244 */ 2245 #define WIMLIB_WRITE_FLAG_FSYNC 0x00000020 2246 2247 /** 2248 * For wimlib_overwrite(): rebuild the entire WIM file, even if it otherwise 2249 * could be updated in-place by appending to it. Any data that existed in the 2250 * original WIM file but is not actually needed by any of the remaining images 2251 * will not be included. This can free up space left over after previous 2252 * in-place modifications to the WIM file. 2253 * 2254 * This flag can be combined with ::WIMLIB_WRITE_FLAG_RECOMPRESS to force all 2255 * data to be recompressed. Otherwise, compressed data is re-used if possible. 2256 * 2257 * wimlib_write() ignores this flag. 2258 */ 2259 #define WIMLIB_WRITE_FLAG_REBUILD 0x00000040 2260 2261 /** 2262 * For wimlib_overwrite(): override the default behavior after one or more calls 2263 * to wimlib_delete_image(), which is to rebuild the entire WIM file. With this 2264 * flag, only minimal changes to correctly remove the image from the WIM file 2265 * will be taken. This can be much faster, but it will result in the WIM file 2266 * getting larger rather than smaller. 2267 * 2268 * wimlib_write() ignores this flag. 2269 */ 2270 #define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000080 2271 2272 /** 2273 * For wimlib_overwrite(), allow overwriting the WIM file even if the readonly 2274 * flag (<c>WIM_HDR_FLAG_READONLY</c>) is set in the WIM header. This can be 2275 * used following a call to wimlib_set_wim_info() with the 2276 * ::WIMLIB_CHANGE_READONLY_FLAG flag to actually set the readonly flag on the 2277 * on-disk WIM file. 2278 * 2279 * wimlib_write() ignores this flag. 2280 */ 2281 #define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100 2282 2283 /** 2284 * Do not include file data already present in other WIMs. This flag can be 2285 * used to write a "delta" WIM after the WIM files on which the delta is to be 2286 * based were referenced with wimlib_reference_resource_files() or 2287 * wimlib_reference_resources(). 2288 */ 2289 #define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS 0x00000200 2290 2291 /** Deprecated; this flag should not be used outside of the library itself. */ 2292 #define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 2293 2294 /** 2295 * For wimlib_write(), retain the WIM's GUID instead of generating a new one. 2296 * 2297 * wimlib_overwrite() sets this by default, since the WIM remains, logically, 2298 * the same file. 2299 */ 2300 #define WIMLIB_WRITE_FLAG_RETAIN_GUID 0x00000800 2301 2302 /** 2303 * Concatenate files and compress them together, rather than compress each file 2304 * independently. This is also known as creating a "solid archive". This tends 2305 * to produce a better compression ratio at the cost of much slower random 2306 * access. 2307 * 2308 * WIM files created with this flag are only compatible with wimlib v1.6.0 or 2309 * later, WIMGAPI Windows 8 or later, and DISM Windows 8.1 or later. WIM files 2310 * created with this flag use a different version number in their header (3584 2311 * instead of 68864) and are also called "ESD files". 2312 * 2313 * Note that providing this flag does not affect the "append by default" 2314 * behavior of wimlib_overwrite(). In other words, wimlib_overwrite() with just 2315 * ::WIMLIB_WRITE_FLAG_SOLID can be used to append solid-compressed data to a 2316 * WIM file that originally did not contain any solid-compressed data. But if 2317 * you instead want to rebuild and recompress an entire WIM file in solid mode, 2318 * then also provide ::WIMLIB_WRITE_FLAG_REBUILD and 2319 * ::WIMLIB_WRITE_FLAG_RECOMPRESS. 2320 * 2321 * Currently, new solid resources will, by default, be written using LZMS 2322 * compression with 64 MiB (67108864 byte) chunks. Use 2323 * wimlib_set_output_pack_compression_type() and/or 2324 * wimlib_set_output_pack_chunk_size() to change this. This is independent of 2325 * the WIM's main compression type and chunk size; you can have a WIM that 2326 * nominally uses LZX compression and 32768 byte chunks but actually contains 2327 * LZMS-compressed solid resources, for example. However, if including solid 2328 * resources, I suggest that you set the WIM's main compression type to LZMS as 2329 * well, either by creating the WIM with 2330 * ::wimlib_create_new_wim(::WIMLIB_COMPRESSION_TYPE_LZMS, ...) or by calling 2331 * ::wimlib_set_output_compression_type(..., ::WIMLIB_COMPRESSION_TYPE_LZMS). 2332 * 2333 * This flag will be set by default when writing or overwriting a WIM file that 2334 * either already contains solid resources, or has had solid resources exported 2335 * into it and the WIM's main compression type is LZMS. 2336 */ 2337 #define WIMLIB_WRITE_FLAG_SOLID 0x00001000 2338 2339 /** 2340 * Send ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM 2341 * file. This is only needed in the unusual case that the library user needs to 2342 * know exactly when wimlib has read each file for the last time. 2343 */ 2344 #define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000 2345 2346 /** 2347 * Do not consider content similarity when arranging file data for solid 2348 * compression. Providing this flag will typically worsen the compression 2349 * ratio, so only provide this flag if you know what you are doing. 2350 */ 2351 #define WIMLIB_WRITE_FLAG_NO_SOLID_SORT 0x00004000 2352 2353 /** 2354 * Since wimlib v1.8.3 and for wimlib_overwrite() only: <b>unsafely</b> compact 2355 * the WIM file in-place, without appending. Existing resources are shifted 2356 * down to fill holes and new resources are appended as needed. The WIM file is 2357 * truncated to its final size, which may shrink the on-disk file. <b>This 2358 * operation cannot be safely interrupted. If the operation is interrupted, 2359 * then the WIM file will be corrupted, and it may be impossible (or at least 2360 * very difficult) to recover any data from it. Users of this flag are expected 2361 * to know what they are doing and assume responsibility for any data corruption 2362 * that may result.</b> 2363 * 2364 * If the WIM file cannot be compacted in-place because of its structure, its 2365 * layout, or other requested write parameters, then wimlib_overwrite() fails 2366 * with ::WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry 2367 * the operation without this flag. 2368 */ 2369 #define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT 0x00008000 2370 2371 /** @} */ 2372 /** @addtogroup G_general 2373 * @{ */ 2374 2375 /** Deprecated; no longer has any effect. */ 2376 #define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001 2377 2378 /** Windows-only: do not attempt to acquire additional privileges (currently 2379 * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, 2380 * SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the 2381 * library. This flag is intended for the case where the calling program 2382 * manages these privileges itself. Note: by default, no error is issued if 2383 * privileges cannot be acquired, although related errors may be reported later, 2384 * depending on if the operations performed actually require additional 2385 * privileges or not. */ 2386 #define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002 2387 2388 /** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, 2389 * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed 2390 * to read all possible data and metadata for a capture operation could not be 2391 * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES. 2392 */ 2393 #define WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES 0x00000004 2394 2395 /** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, 2396 * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed 2397 * to restore all possible data and metadata for an apply operation could not be 2398 * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES. 2399 */ 2400 #define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008 2401 2402 /** Default to interpreting WIM paths case sensitively (default on UNIX-like 2403 * systems). */ 2404 #define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE 0x00000010 2405 2406 /** Default to interpreting WIM paths case insensitively (default on Windows). 2407 * This does not apply to mounted images. */ 2408 #define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020 2409 2410 /** @} */ 2411 /** @addtogroup G_nonstandalone_wims 2412 * @{ */ 2413 2414 /** For wimlib_reference_resource_files(), enable shell-style filename globbing. 2415 * Ignored by wimlib_reference_resources(). */ 2416 #define WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001 2417 2418 /** For wimlib_reference_resource_files(), issue an error 2419 * (::WIMLIB_ERR_GLOB_HAD_NO_MATCHES) if a glob did not match any files. The 2420 * default behavior without this flag is to issue no error at that point, but 2421 * then attempt to open the glob as a literal path, which of course will fail 2422 * anyway if no file exists at that path. No effect if 2423 * ::WIMLIB_REF_FLAG_GLOB_ENABLE is not also specified. Ignored by 2424 * wimlib_reference_resources(). */ 2425 #define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002 2426 2427 /** @} */ 2428 /** @addtogroup G_modifying_wims 2429 * @{ */ 2430 2431 /** The specific type of update to perform. */ 2432 enum wimlib_update_op { 2433 /** Add a new file or directory tree to the image. */ 2434 WIMLIB_UPDATE_OP_ADD = 0, 2435 2436 /** Delete a file or directory tree from the image. */ 2437 WIMLIB_UPDATE_OP_DELETE = 1, 2438 2439 /** Rename a file or directory tree in the image. */ 2440 WIMLIB_UPDATE_OP_RENAME = 2, 2441 }; 2442 2443 /** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */ 2444 struct wimlib_add_command { 2445 /** Filesystem path to the file or directory tree to add. */ 2446 wimlib_tchar *fs_source_path; 2447 2448 /** Destination path in the image. To specify the root directory of the 2449 * image, use ::WIMLIB_WIM_ROOT_PATH. */ 2450 wimlib_tchar *wim_target_path; 2451 2452 /** Path to capture configuration file to use, or @c NULL if not 2453 * specified. */ 2454 wimlib_tchar *config_file; 2455 2456 /** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */ 2457 int add_flags; 2458 }; 2459 2460 /** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */ 2461 struct wimlib_delete_command { 2462 2463 /** The path to the file or directory within the image to delete. */ 2464 wimlib_tchar *wim_path; 2465 2466 /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ 2467 int delete_flags; 2468 }; 2469 2470 /** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */ 2471 struct wimlib_rename_command { 2472 2473 /** The path to the source file or directory within the image. */ 2474 wimlib_tchar *wim_source_path; 2475 2476 /** The path to the destination file or directory within the image. */ 2477 wimlib_tchar *wim_target_path; 2478 2479 /** Reserved; set to 0. */ 2480 int rename_flags; 2481 }; 2482 2483 /** Specification of an update to perform on a WIM image. */ 2484 struct wimlib_update_command { 2485 2486 enum wimlib_update_op op; 2487 2488 union { 2489 struct wimlib_add_command add; 2490 struct wimlib_delete_command delete_; /* Underscore is for C++ 2491 compatibility. */ 2492 struct wimlib_rename_command rename; 2493 }; 2494 }; 2495 2496 /** @} */ 2497 /** @addtogroup G_general 2498 * @{ */ 2499 2500 /** 2501 * Possible values of the error code returned by many functions in wimlib. 2502 * 2503 * See the documentation for each wimlib function to see specifically what error 2504 * codes can be returned by a given function, and what they mean. 2505 */ 2506 enum wimlib_error_code { 2507 WIMLIB_ERR_SUCCESS = 0, 2508 WIMLIB_ERR_ALREADY_LOCKED = 1, 2509 WIMLIB_ERR_DECOMPRESSION = 2, 2510 WIMLIB_ERR_FUSE = 6, 2511 WIMLIB_ERR_GLOB_HAD_NO_MATCHES = 8, 2512 WIMLIB_ERR_IMAGE_COUNT = 10, 2513 WIMLIB_ERR_IMAGE_NAME_COLLISION = 11, 2514 WIMLIB_ERR_INSUFFICIENT_PRIVILEGES = 12, 2515 WIMLIB_ERR_INTEGRITY = 13, 2516 WIMLIB_ERR_INVALID_CAPTURE_CONFIG = 14, 2517 WIMLIB_ERR_INVALID_CHUNK_SIZE = 15, 2518 WIMLIB_ERR_INVALID_COMPRESSION_TYPE = 16, 2519 WIMLIB_ERR_INVALID_HEADER = 17, 2520 WIMLIB_ERR_INVALID_IMAGE = 18, 2521 WIMLIB_ERR_INVALID_INTEGRITY_TABLE = 19, 2522 WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY = 20, 2523 WIMLIB_ERR_INVALID_METADATA_RESOURCE = 21, 2524 WIMLIB_ERR_INVALID_OVERLAY = 23, 2525 WIMLIB_ERR_INVALID_PARAM = 24, 2526 WIMLIB_ERR_INVALID_PART_NUMBER = 25, 2527 WIMLIB_ERR_INVALID_PIPABLE_WIM = 26, 2528 WIMLIB_ERR_INVALID_REPARSE_DATA = 27, 2529 WIMLIB_ERR_INVALID_RESOURCE_HASH = 28, 2530 WIMLIB_ERR_INVALID_UTF16_STRING = 30, 2531 WIMLIB_ERR_INVALID_UTF8_STRING = 31, 2532 WIMLIB_ERR_IS_DIRECTORY = 32, 2533 WIMLIB_ERR_IS_SPLIT_WIM = 33, 2534 WIMLIB_ERR_LINK = 35, 2535 WIMLIB_ERR_METADATA_NOT_FOUND = 36, 2536 WIMLIB_ERR_MKDIR = 37, 2537 WIMLIB_ERR_MQUEUE = 38, 2538 WIMLIB_ERR_NOMEM = 39, 2539 WIMLIB_ERR_NOTDIR = 40, 2540 WIMLIB_ERR_NOTEMPTY = 41, 2541 WIMLIB_ERR_NOT_A_REGULAR_FILE = 42, 2542 WIMLIB_ERR_NOT_A_WIM_FILE = 43, 2543 WIMLIB_ERR_NOT_PIPABLE = 44, 2544 WIMLIB_ERR_NO_FILENAME = 45, 2545 WIMLIB_ERR_NTFS_3G = 46, 2546 WIMLIB_ERR_OPEN = 47, 2547 WIMLIB_ERR_OPENDIR = 48, 2548 WIMLIB_ERR_PATH_DOES_NOT_EXIST = 49, 2549 WIMLIB_ERR_READ = 50, 2550 WIMLIB_ERR_READLINK = 51, 2551 WIMLIB_ERR_RENAME = 52, 2552 WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED = 54, 2553 WIMLIB_ERR_RESOURCE_NOT_FOUND = 55, 2554 WIMLIB_ERR_RESOURCE_ORDER = 56, 2555 WIMLIB_ERR_SET_ATTRIBUTES = 57, 2556 WIMLIB_ERR_SET_REPARSE_DATA = 58, 2557 WIMLIB_ERR_SET_SECURITY = 59, 2558 WIMLIB_ERR_SET_SHORT_NAME = 60, 2559 WIMLIB_ERR_SET_TIMESTAMPS = 61, 2560 WIMLIB_ERR_SPLIT_INVALID = 62, 2561 WIMLIB_ERR_STAT = 63, 2562 WIMLIB_ERR_UNEXPECTED_END_OF_FILE = 65, 2563 WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE = 66, 2564 WIMLIB_ERR_UNKNOWN_VERSION = 67, 2565 WIMLIB_ERR_UNSUPPORTED = 68, 2566 WIMLIB_ERR_UNSUPPORTED_FILE = 69, 2567 WIMLIB_ERR_WIM_IS_READONLY = 71, 2568 WIMLIB_ERR_WRITE = 72, 2569 WIMLIB_ERR_XML = 73, 2570 WIMLIB_ERR_WIM_IS_ENCRYPTED = 74, 2571 WIMLIB_ERR_WIMBOOT = 75, 2572 WIMLIB_ERR_ABORTED_BY_PROGRESS = 76, 2573 WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS = 77, 2574 WIMLIB_ERR_MKNOD = 78, 2575 WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79, 2576 WIMLIB_ERR_NOT_A_MOUNTPOINT = 80, 2577 WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81, 2578 WIMLIB_ERR_FVE_LOCKED_VOLUME = 82, 2579 WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83, 2580 WIMLIB_ERR_WIM_IS_INCOMPLETE = 84, 2581 WIMLIB_ERR_COMPACTION_NOT_POSSIBLE = 85, 2582 WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86, 2583 WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87, 2584 WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88, 2585 WIMLIB_ERR_SNAPSHOT_FAILURE = 89, 2586 WIMLIB_ERR_INVALID_XATTR = 90, 2587 WIMLIB_ERR_SET_XATTR = 91, 2588 }; 2589 2590 2591 /** Used to indicate no image or an invalid image. */ 2592 #define WIMLIB_NO_IMAGE 0 2593 2594 /** Used to specify all images in the WIM. */ 2595 #define WIMLIB_ALL_IMAGES (-1) 2596 2597 /** @} */ 2598 2599 /** 2600 * @ingroup G_modifying_wims 2601 * 2602 * Append an empty image to a ::WIMStruct. 2603 * 2604 * The new image will initially contain no files or directories, although if 2605 * written without further modifications, then a root directory will be created 2606 * automatically for it. 2607 * 2608 * After calling this function, you can use wimlib_update_image() to add files 2609 * to the new image. This gives you more control over making the new image 2610 * compared to calling wimlib_add_image() or wimlib_add_image_multisource(). 2611 * 2612 * @param wim 2613 * Pointer to the ::WIMStruct to which to add the image. 2614 * @param name 2615 * Name to give the new image. If @c NULL or empty, the new image is given 2616 * no name. If nonempty, it must specify a name that does not already 2617 * exist in @p wim. 2618 * @param new_idx_ret 2619 * If non-<c>NULL</c>, the index of the newly added image is returned in 2620 * this location. 2621 * 2622 * @return 0 on success; a ::wimlib_error_code value on failure. 2623 * 2624 * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION 2625 * The WIM already contains an image with the requested name. 2626 */ 2627 extern int 2628 wimlib_add_empty_image(WIMStruct *wim, 2629 const wimlib_tchar *name, 2630 int *new_idx_ret); 2631 2632 /** 2633 * @ingroup G_modifying_wims 2634 * 2635 * Add an image to a ::WIMStruct from an on-disk directory tree or NTFS volume. 2636 * 2637 * The directory tree or NTFS volume is scanned immediately to load the dentry 2638 * tree into memory, and file metadata is read. However, actual file data may 2639 * not be read until the ::WIMStruct is persisted to disk using wimlib_write() 2640 * or wimlib_overwrite(). 2641 * 2642 * See the documentation for the @b wimlib-imagex program for more information 2643 * about the "normal" capture mode versus the NTFS capture mode (entered by 2644 * providing the flag ::WIMLIB_ADD_FLAG_NTFS). 2645 * 2646 * Note that no changes are committed to disk until wimlib_write() or 2647 * wimlib_overwrite() is called. 2648 * 2649 * @param wim 2650 * Pointer to the ::WIMStruct to which to add the image. 2651 * @param source 2652 * A path to a directory or unmounted NTFS volume that will be captured as 2653 * a WIM image. 2654 * @param name 2655 * Name to give the new image. If @c NULL or empty, the new image is given 2656 * no name. If nonempty, it must specify a name that does not already 2657 * exist in @p wim. 2658 * @param config_file 2659 * Path to capture configuration file, or @c NULL. This file may specify, 2660 * among other things, which files to exclude from capture. See the 2661 * documentation for <b>wimcapture</b> (<b>--config</b> option) for details 2662 * of the file format. If @c NULL, the default capture configuration will 2663 * be used. Ordinarily, the default capture configuration will result in 2664 * no files being excluded from capture purely based on name; however, the 2665 * ::WIMLIB_ADD_FLAG_WINCONFIG and ::WIMLIB_ADD_FLAG_WIMBOOT flags modify 2666 * the default. 2667 * @param add_flags 2668 * Bitwise OR of flags prefixed with WIMLIB_ADD_FLAG. 2669 * 2670 * @return 0 on success; a ::wimlib_error_code value on failure. 2671 * 2672 * This function is implemented by calling wimlib_add_empty_image(), then 2673 * calling wimlib_update_image() with a single "add" command, so any error code 2674 * returned by wimlib_add_empty_image() may be returned, as well as any error 2675 * codes returned by wimlib_update_image() other than ones documented as only 2676 * being returned specifically by an update involving delete or rename commands. 2677 * 2678 * If a progress function is registered with @p wim, then it will receive the 2679 * messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and ::WIMLIB_PROGRESS_MSG_SCAN_END. 2680 * In addition, if ::WIMLIB_ADD_FLAG_VERBOSE is specified in @p add_flags, it 2681 * will receive ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. 2682 */ 2683 extern int 2684 wimlib_add_image(WIMStruct *wim, 2685 const wimlib_tchar *source, 2686 const wimlib_tchar *name, 2687 const wimlib_tchar *config_file, 2688 int add_flags); 2689 2690 /** 2691 * @ingroup G_modifying_wims 2692 * 2693 * This function is equivalent to wimlib_add_image() except it allows for 2694 * multiple sources to be combined into a single WIM image. This is done by 2695 * specifying the @p sources and @p num_sources parameters instead of the @p 2696 * source parameter of wimlib_add_image(). The rest of the parameters are the 2697 * same as wimlib_add_image(). See the documentation for <b>wimcapture</b> for 2698 * full details on how this mode works. 2699 */ 2700 extern int 2701 wimlib_add_image_multisource(WIMStruct *wim, 2702 const struct wimlib_capture_source *sources, 2703 size_t num_sources, 2704 const wimlib_tchar *name, 2705 const wimlib_tchar *config_file, 2706 int add_flags); 2707 2708 /** 2709 * @ingroup G_modifying_wims 2710 * 2711 * Add the file or directory tree at @p fs_source_path on the filesystem to the 2712 * location @p wim_target_path within the specified @p image of the @p wim. 2713 * 2714 * This just builds an appropriate ::wimlib_add_command and passes it to 2715 * wimlib_update_image(). 2716 */ 2717 extern int 2718 wimlib_add_tree(WIMStruct *wim, int image, 2719 const wimlib_tchar *fs_source_path, 2720 const wimlib_tchar *wim_target_path, int add_flags); 2721 2722 /** 2723 * @ingroup G_creating_and_opening_wims 2724 * 2725 * Create a ::WIMStruct which initially contains no images and is not backed by 2726 * an on-disk file. 2727 * 2728 * @param ctype 2729 * The "output compression type" to assign to the ::WIMStruct. This is the 2730 * compression type that will be used if the ::WIMStruct is later persisted 2731 * to an on-disk file using wimlib_write(). 2732 * <br/> 2733 * This choice is not necessarily final. If desired, it can still be 2734 * changed at any time before wimlib_write() is called, using 2735 * wimlib_set_output_compression_type(). In addition, if you wish to use a 2736 * non-default compression chunk size, then you will need to call 2737 * wimlib_set_output_chunk_size(). 2738 * @param wim_ret 2739 * On success, a pointer to the new ::WIMStruct is written to the memory 2740 * location pointed to by this parameter. This ::WIMStruct must be freed 2741 * using using wimlib_free() when finished with it. 2742 * 2743 * @return 0 on success; a ::wimlib_error_code value on failure. 2744 * 2745 * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE 2746 * @p ctype was not a supported compression type. 2747 * @retval ::WIMLIB_ERR_NOMEM 2748 * Insufficient memory to allocate a new ::WIMStruct. 2749 */ 2750 extern int 2751 wimlib_create_new_wim(enum wimlib_compression_type ctype, WIMStruct **wim_ret); 2752 2753 /** 2754 * @ingroup G_modifying_wims 2755 * 2756 * Delete an image, or all images, from a ::WIMStruct. 2757 * 2758 * Note that no changes are committed to disk until wimlib_write() or 2759 * wimlib_overwrite() is called. 2760 * 2761 * @param wim 2762 * Pointer to the ::WIMStruct from which to delete the image. 2763 * @param image 2764 * The 1-based index of the image to delete, or ::WIMLIB_ALL_IMAGES to 2765 * delete all images. 2766 * 2767 * @return 0 on success; a ::wimlib_error_code value on failure. 2768 * 2769 * @retval ::WIMLIB_ERR_INVALID_IMAGE 2770 * @p image does not exist in the WIM. 2771 * 2772 * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, 2773 * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, 2774 * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which 2775 * indicate failure (for different reasons) to read the metadata resource for an 2776 * image that needed to be deleted. 2777 * 2778 * If this function fails when @p image was ::WIMLIB_ALL_IMAGES, then it's 2779 * possible that some but not all of the images were deleted. 2780 */ 2781 extern int 2782 wimlib_delete_image(WIMStruct *wim, int image); 2783 2784 /** 2785 * @ingroup G_modifying_wims 2786 * 2787 * Delete the @p path from the specified @p image of the @p wim. 2788 * 2789 * This just builds an appropriate ::wimlib_delete_command and passes it to 2790 * wimlib_update_image(). 2791 */ 2792 extern int 2793 wimlib_delete_path(WIMStruct *wim, int image, 2794 const wimlib_tchar *path, int delete_flags); 2795 2796 /** 2797 * @ingroup G_modifying_wims 2798 * 2799 * Export an image, or all images, from a ::WIMStruct into another ::WIMStruct. 2800 * 2801 * Specifically, if the destination ::WIMStruct contains <tt>n</tt> images, then 2802 * the source image(s) will be appended, in order, starting at destination index 2803 * <tt>n + 1</tt>. By default, all image metadata will be exported verbatim, 2804 * but certain changes can be made by passing appropriate parameters. 2805 * 2806 * wimlib_export_image() is only an in-memory operation; no changes are 2807 * committed to disk until wimlib_write() or wimlib_overwrite() is called. 2808 * 2809 * A limitation of the current implementation of wimlib_export_image() is that 2810 * the directory tree of a source or destination image cannot be updated 2811 * following an export until one of the two images has been freed from memory. 2812 * 2813 * @param src_wim 2814 * The WIM from which to export the images, specified as a pointer to the 2815 * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a 2816 * split WIM. In the case of a WIM file that is not standalone, this 2817 * ::WIMStruct must have had any needed external resources previously 2818 * referenced using wimlib_reference_resources() or 2819 * wimlib_reference_resource_files(). 2820 * @param src_image 2821 * The 1-based index of the image from @p src_wim to export, or 2822 * ::WIMLIB_ALL_IMAGES. 2823 * @param dest_wim 2824 * The ::WIMStruct to which to export the images. 2825 * @param dest_name 2826 * For single-image exports, the name to give the exported image in @p 2827 * dest_wim. If left @c NULL, the name from @p src_wim is used. For 2828 * ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c NULL; in 2829 * that case, the names are all taken from @p src_wim. This parameter is 2830 * overridden by ::WIMLIB_EXPORT_FLAG_NO_NAMES. 2831 * @param dest_description 2832 * For single-image exports, the description to give the exported image in 2833 * the new WIM file. If left @c NULL, the description from @p src_wim is 2834 * used. For ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c 2835 * NULL; in that case, the description are all taken from @p src_wim. This 2836 * parameter is overridden by ::WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS. 2837 * @param export_flags 2838 * Bitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG. 2839 * 2840 * @return 0 on success; a ::wimlib_error_code value on failure. 2841 * 2842 * @retval ::WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE 2843 * One or more of the source images had already been exported into the 2844 * destination WIM. 2845 * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION 2846 * One or more of the names being given to an exported image was already in 2847 * use in the destination WIM. 2848 * @retval ::WIMLIB_ERR_INVALID_IMAGE 2849 * @p src_image does not exist in @p src_wim. 2850 * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND 2851 * At least one of @p src_wim and @p dest_wim does not contain image 2852 * metadata; for example, one of them represents a non-first part of a 2853 * split WIM. 2854 * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND 2855 * A file data blob that needed to be exported could not be found in the 2856 * blob lookup table of @p src_wim. See @ref G_nonstandalone_wims. 2857 * 2858 * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, 2859 * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, 2860 * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which 2861 * indicate failure (for different reasons) to read the metadata resource for an 2862 * image in @p src_wim that needed to be exported. 2863 */ 2864 extern int 2865 wimlib_export_image(WIMStruct *src_wim, int src_image, 2866 WIMStruct *dest_wim, 2867 const wimlib_tchar *dest_name, 2868 const wimlib_tchar *dest_description, 2869 int export_flags); 2870 2871 /** 2872 * @ingroup G_extracting_wims 2873 * 2874 * Extract an image, or all images, from a ::WIMStruct. 2875 * 2876 * The exact behavior of how wimlib extracts files from a WIM image is 2877 * controllable by the @p extract_flags parameter, but there also are 2878 * differences depending on the platform (UNIX-like vs Windows). See the 2879 * documentation for <b>wimapply</b> for more information, including about the 2880 * NTFS-3G extraction mode. 2881 * 2882 * @param wim 2883 * The WIM from which to extract the image(s), specified as a pointer to the 2884 * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a 2885 * split WIM. In the case of a WIM file that is not standalone, this 2886 * ::WIMStruct must have had any needed external resources previously 2887 * referenced using wimlib_reference_resources() or 2888 * wimlib_reference_resource_files(). 2889 * @param image 2890 * The 1-based index of the image to extract, or ::WIMLIB_ALL_IMAGES to 2891 * extract all images. Note: ::WIMLIB_ALL_IMAGES is unsupported in NTFS-3G 2892 * extraction mode. 2893 * @param target 2894 * A null-terminated string which names the location to which the image(s) 2895 * will be extracted. By default, this is interpreted as a path to a 2896 * directory. Alternatively, if ::WIMLIB_EXTRACT_FLAG_NTFS is specified in 2897 * @p extract_flags, then this is interpreted as a path to an unmounted 2898 * NTFS volume. 2899 * @param extract_flags 2900 * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG. 2901 * 2902 * @return 0 on success; a ::wimlib_error_code value on failure. 2903 * 2904 * @retval ::WIMLIB_ERR_DECOMPRESSION 2905 * The WIM file contains invalid compressed data. 2906 * @retval ::WIMLIB_ERR_INVALID_IMAGE 2907 * @p image does not exist in @p wim. 2908 * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE 2909 * The metadata for an image to extract was invalid. 2910 * @retval ::WIMLIB_ERR_INVALID_PARAM 2911 * The extraction flags were invalid; more details may be found in the 2912 * documentation for the specific extraction flags that were specified. Or 2913 * @p target was @c NULL or an empty string, or @p wim was @c NULL. 2914 * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH 2915 * The data of a file that needed to be extracted was corrupt. 2916 * @retval ::WIMLIB_ERR_LINK 2917 * Failed to create a symbolic link or a hard link. 2918 * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND 2919 * @p wim does not contain image metadata; for example, it represents a 2920 * non-first part of a split WIM. 2921 * @retval ::WIMLIB_ERR_MKDIR 2922 * Failed create a directory. 2923 * @retval ::WIMLIB_ERR_NTFS_3G 2924 * libntfs-3g reported that a problem occurred while writing to the NTFS 2925 * volume. 2926 * @retval ::WIMLIB_ERR_OPEN 2927 * Could not create a file, or failed to open an already-extracted file. 2928 * @retval ::WIMLIB_ERR_READ 2929 * Failed to read data from the WIM. 2930 * @retval ::WIMLIB_ERR_READLINK 2931 * Failed to determine the target of a symbolic link in the WIM. 2932 * @retval ::WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED 2933 * Failed to fix the target of an absolute symbolic link (e.g. if the 2934 * target would have exceeded the maximum allowed length). (Only if 2935 * reparse data was supported by the extraction mode and 2936 * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS was specified in @p 2937 * extract_flags.) 2938 * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND 2939 * A file data blob that needed to be extracted could not be found in the 2940 * blob lookup table of @p wim. See @ref G_nonstandalone_wims. 2941 * @retval ::WIMLIB_ERR_SET_ATTRIBUTES 2942 * Failed to set attributes on a file. 2943 * @retval ::WIMLIB_ERR_SET_REPARSE_DATA 2944 * Failed to set reparse data on a file (only if reparse data was supported 2945 * by the extraction mode). 2946 * @retval ::WIMLIB_ERR_SET_SECURITY 2947 * Failed to set security descriptor on a file. 2948 * @retval ::WIMLIB_ERR_SET_SHORT_NAME 2949 * Failed to set the short name of a file. 2950 * @retval ::WIMLIB_ERR_SET_TIMESTAMPS 2951 * Failed to set timestamps on a file. 2952 * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE 2953 * Unexpected end-of-file occurred when reading data from the WIM. 2954 * @retval ::WIMLIB_ERR_UNSUPPORTED 2955 * A requested extraction flag, or the data or metadata that must be 2956 * extracted to support it, is unsupported in the build and configuration 2957 * of wimlib, or on the current platform or extraction mode or target 2958 * volume. Flags affected by this include ::WIMLIB_EXTRACT_FLAG_NTFS, 2959 * ::WIMLIB_EXTRACT_FLAG_UNIX_DATA, ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS, 2960 * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES, 2961 * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS, and 2962 * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS. For example, if 2963 * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES is specified in @p 2964 * extract_flags, ::WIMLIB_ERR_UNSUPPORTED will be returned if the WIM 2965 * image contains one or more files with short names, but extracting short 2966 * names is not supported --- on Windows, this occurs if the target volume 2967 * does not support short names, while on non-Windows, this occurs if 2968 * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags. 2969 * @retval ::WIMLIB_ERR_WIMBOOT 2970 * ::WIMLIB_EXTRACT_FLAG_WIMBOOT was specified in @p extract_flags, but 2971 * there was a problem creating WIMBoot pointer files or registering a 2972 * source WIM file with the Windows Overlay Filesystem (WOF) driver. 2973 * @retval ::WIMLIB_ERR_WRITE 2974 * Failed to write data to a file being extracted. 2975 * 2976 * If a progress function is registered with @p wim, then as each image is 2977 * extracted it will receive ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, then 2978 * zero or more ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE messages, then zero 2979 * or more ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then zero or more 2980 * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, then 2981 * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. 2982 */ 2983 extern int 2984 wimlib_extract_image(WIMStruct *wim, int image, 2985 const wimlib_tchar *target, int extract_flags); 2986 2987 /** 2988 * @ingroup G_extracting_wims 2989 * 2990 * Extract one image from a pipe on which a pipable WIM is being sent. 2991 * 2992 * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE, and @ref 2993 * subsec_pipable_wims, for more information about pipable WIMs. 2994 * 2995 * This function operates in a special way to read the WIM fully sequentially. 2996 * As a result, there is no ::WIMStruct is made visible to library users, and 2997 * you cannot call wimlib_open_wim() on the pipe. (You can, however, use 2998 * wimlib_open_wim() to transparently open a pipable WIM if it's available as a 2999 * seekable file, not a pipe.) 3000 * 3001 * @param pipe_fd 3002 * File descriptor, which may be a pipe, opened for reading and positioned 3003 * at the start of the pipable WIM. 3004 * @param image_num_or_name 3005 * String that specifies the 1-based index or name of the image to extract. 3006 * It is translated to an image index using the same rules that 3007 * wimlib_resolve_image() uses. However, unlike wimlib_extract_image(), 3008 * only a single image (not all images) can be specified. Alternatively, 3009 * specify @p NULL here to use the first image in the WIM if it contains 3010 * exactly one image but otherwise return ::WIMLIB_ERR_INVALID_IMAGE. 3011 * @param target 3012 * Same as the corresponding parameter to wimlib_extract_image(). 3013 * @param extract_flags 3014 * Same as the corresponding parameter to wimlib_extract_image(). 3015 * 3016 * @return 0 on success; a ::wimlib_error_code value on failure. The possible 3017 * error codes include those returned by wimlib_extract_image() and 3018 * wimlib_open_wim() as well as the following: 3019 * 3020 * @retval ::WIMLIB_ERR_INVALID_PIPABLE_WIM 3021 * Data read from the pipable WIM was invalid. 3022 * @retval ::WIMLIB_ERR_NOT_PIPABLE 3023 * The WIM being piped over @p pipe_fd is a normal WIM, not a pipable WIM. 3024 */ 3025 extern int 3026 wimlib_extract_image_from_pipe(int pipe_fd, 3027 const wimlib_tchar *image_num_or_name, 3028 const wimlib_tchar *target, int extract_flags); 3029 3030 /** 3031 * @ingroup G_extracting_wims 3032 * 3033 * Same as wimlib_extract_image_from_pipe(), but allows specifying a progress 3034 * function. The progress function will be used while extracting the image and 3035 * will receive the normal extraction progress messages, such as 3036 * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, in addition to 3037 * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. 3038 */ 3039 extern int 3040 wimlib_extract_image_from_pipe_with_progress(int pipe_fd, 3041 const wimlib_tchar *image_num_or_name, 3042 const wimlib_tchar *target, 3043 int extract_flags, 3044 wimlib_progress_func_t progfunc, 3045 void *progctx); 3046 3047 /** 3048 * @ingroup G_extracting_wims 3049 * 3050 * Similar to wimlib_extract_paths(), but the paths to extract from the WIM 3051 * image are specified in the ASCII, UTF-8, or UTF-16LE text file named by @p 3052 * path_list_file which itself contains the list of paths to use, one per line. 3053 * Leading and trailing whitespace is ignored. Empty lines and lines beginning 3054 * with the ';' or '#' characters are ignored. No quotes are needed, as paths 3055 * are otherwise delimited by the newline character. However, quotes will be 3056 * stripped if present. 3057 * 3058 * If @p path_list_file is @c NULL, then the pathlist file is read from standard 3059 * input. 3060 * 3061 * The error codes are the same as those returned by wimlib_extract_paths(), 3062 * except that wimlib_extract_pathlist() returns an appropriate error code if it 3063 * cannot read the path list file (e.g. ::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT, 3064 * ::WIMLIB_ERR_READ). 3065 */ 3066 extern int 3067 wimlib_extract_pathlist(WIMStruct *wim, int image, 3068 const wimlib_tchar *target, 3069 const wimlib_tchar *path_list_file, 3070 int extract_flags); 3071 3072 /** 3073 * @ingroup G_extracting_wims 3074 * 3075 * Extract zero or more paths (files or directory trees) from the specified WIM 3076 * image. 3077 * 3078 * By default, each path will be extracted to a corresponding subdirectory of 3079 * the target based on its location in the image. For example, if one of the 3080 * paths to extract is <c>/Windows/explorer.exe</c> and the target is 3081 * <c>outdir</c>, the file will be extracted to 3082 * <c>outdir/Windows/explorer.exe</c>. This behavior can be changed by 3083 * providing the flag ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE, which 3084 * will cause each file or directory tree to be placed directly in the target 3085 * directory --- so the same example would extract <c>/Windows/explorer.exe</c> 3086 * to <c>outdir/explorer.exe</c>. 3087 * 3088 * With globbing turned off (the default), paths are always checked for 3089 * existence strictly; that is, if any path to extract does not exist in the 3090 * image, then nothing is extracted and the function fails with 3091 * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST. But with globbing turned on 3092 * (::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified), globs are by default permitted 3093 * to match no files, and there is a flag (::WIMLIB_EXTRACT_FLAG_STRICT_GLOB) to 3094 * enable the strict behavior if desired. 3095 * 3096 * Symbolic links are not dereferenced when paths in the image are interpreted. 3097 * 3098 * @param wim 3099 * WIM from which to extract the paths, specified as a pointer to the 3100 * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a 3101 * split WIM. In the case of a WIM file that is not standalone, this 3102 * ::WIMStruct must have had any needed external resources previously 3103 * referenced using wimlib_reference_resources() or 3104 * wimlib_reference_resource_files(). 3105 * @param image 3106 * The 1-based index of the WIM image from which to extract the paths. 3107 * @param paths 3108 * Array of paths to extract. Each element must be the absolute path to a 3109 * file or directory within the image. Path separators may be either 3110 * forwards or backwards slashes, and leading path separators are optional. 3111 * The paths will be interpreted either case-sensitively (UNIX default) or 3112 * case-insensitively (Windows default); however, the case sensitivity can 3113 * be configured explicitly at library initialization time by passing an 3114 * appropriate flag to wimlib_global_init(). 3115 * <br/> 3116 * By default, "globbing" is disabled, so the characters @c * and @c ? are 3117 * interpreted literally. This can be changed by specifying 3118 * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p extract_flags. 3119 * @param num_paths 3120 * Number of paths specified in @p paths. 3121 * @param target 3122 * Directory to which to extract the paths. 3123 * @param extract_flags 3124 * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG. 3125 * 3126 * @return 0 on success; a ::wimlib_error_code value on failure. Most of the 3127 * error codes are the same as those returned by wimlib_extract_image(). Below, 3128 * some of the error codes returned in situations specific to path-mode 3129 * extraction are documented: 3130 * 3131 * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE 3132 * ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified in @p extract_flags, but 3133 * one of the paths to extract did not name a regular file. 3134 * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST 3135 * One of the paths to extract does not exist in the image; see discussion 3136 * above about strict vs. non-strict behavior. 3137 * 3138 * If a progress function is registered with @p wim, then it will receive 3139 * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. 3140 */ 3141 extern int 3142 wimlib_extract_paths(WIMStruct *wim, 3143 int image, 3144 const wimlib_tchar *target, 3145 const wimlib_tchar * const *paths, 3146 size_t num_paths, 3147 int extract_flags); 3148 3149 /** 3150 * @ingroup G_wim_information 3151 * 3152 * Similar to wimlib_get_xml_data(), but the XML document will be written to the 3153 * specified standard C <c>FILE*</c> instead of retrieved in an in-memory 3154 * buffer. 3155 * 3156 * @return 0 on success; a ::wimlib_error_code value on failure. This may 3157 * return any error code which can be returned by wimlib_get_xml_data() as well 3158 * as the following error codes: 3159 * 3160 * @retval ::WIMLIB_ERR_WRITE 3161 * Failed to write the data to the requested file. 3162 */ 3163 extern int 3164 wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); 3165 3166 /** 3167 * @ingroup G_general 3168 * 3169 * Release a reference to a ::WIMStruct. If the ::WIMStruct is still referenced 3170 * by other ::WIMStruct's (e.g. following calls to wimlib_export_image() or 3171 * wimlib_reference_resources()), then the library will free it later, when the 3172 * last reference is released; otherwise it is freed immediately and any 3173 * associated file descriptors are closed. 3174 * 3175 * @param wim 3176 * Pointer to the ::WIMStruct to release. If @c NULL, no action is taken. 3177 */ 3178 extern void 3179 wimlib_free(WIMStruct *wim); 3180 3181 /** 3182 * @ingroup G_general 3183 * 3184 * Convert a ::wimlib_compression_type value into a string. 3185 * 3186 * @param ctype 3187 * The compression type value to convert. 3188 * 3189 * @return 3190 * A statically allocated string naming the compression type, such as 3191 * "None", "LZX", or "XPRESS". If the value was unrecognized, then 3192 * the resulting string will be "Invalid". 3193 */ 3194 extern const wimlib_tchar * 3195 wimlib_get_compression_type_string(enum wimlib_compression_type ctype); 3196 3197 /** 3198 * @ingroup G_general 3199 * 3200 * Convert a wimlib error code into a string describing it. 3201 * 3202 * @param code 3203 * An error code returned by one of wimlib's functions. 3204 * 3205 * @return 3206 * Pointer to a statically allocated string describing the error code. If 3207 * the value was unrecognized, then the resulting string will be "Unknown 3208 * error". 3209 */ 3210 extern const wimlib_tchar * 3211 wimlib_get_error_string(enum wimlib_error_code code); 3212 3213 /** 3214 * @ingroup G_wim_information 3215 * 3216 * Get the description of the specified image. Equivalent to 3217 * <tt>wimlib_get_image_property(wim, image, "DESCRIPTION")</tt>. 3218 */ 3219 extern const wimlib_tchar * 3220 wimlib_get_image_description(const WIMStruct *wim, int image); 3221 3222 /** 3223 * @ingroup G_wim_information 3224 * 3225 * Get the name of the specified image. Equivalent to 3226 * <tt>wimlib_get_image_property(wim, image, "NAME")</tt>, except that 3227 * wimlib_get_image_name() will return an empty string if the image is unnamed 3228 * whereas wimlib_get_image_property() may return @c NULL in that case. 3229 */ 3230 extern const wimlib_tchar * 3231 wimlib_get_image_name(const WIMStruct *wim, int image); 3232 3233 /** 3234 * @ingroup G_wim_information 3235 * 3236 * Since wimlib v1.8.3: get a per-image property from the WIM's XML document. 3237 * This is an alternative to wimlib_get_image_name() and 3238 * wimlib_get_image_description() which allows getting any simple string 3239 * property. 3240 * 3241 * @param wim 3242 * Pointer to the ::WIMStruct for the WIM. 3243 * @param image 3244 * The 1-based index of the image for which to get the property. 3245 * @param property_name 3246 * The name of the image property, for example "NAME", "DESCRIPTION", or 3247 * "TOTALBYTES". The name can contain forward slashes to indicate a nested 3248 * XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD 3249 * element nested within the VERSION element nested within the WINDOWS 3250 * element. Since wimlib v1.9.0, a bracketed number can be used to 3251 * indicate one of several identically-named elements; for example, 3252 * "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element 3253 * nested within the "WINDOWS/LANGUAGES" element. Note that element names 3254 * are case sensitive. 3255 * 3256 * @return 3257 * The property's value as a ::wimlib_tchar string, or @c NULL if there is 3258 * no such property. The string may not remain valid after later library 3259 * calls, so the caller should duplicate it if needed. 3260 */ 3261 extern const wimlib_tchar * 3262 wimlib_get_image_property(const WIMStruct *wim, int image, 3263 const wimlib_tchar *property_name); 3264 3265 /** 3266 * @ingroup G_general 3267 * 3268 * Return the version of wimlib as a 32-bit number whose top 12 bits contain the 3269 * major version, the next 10 bits contain the minor version, and the low 10 3270 * bits contain the patch version. 3271 * 3272 * In other words, the returned value is equal to <c>((WIMLIB_MAJOR_VERSION << 3273 * 20) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</c> for the 3274 * corresponding header file. 3275 */ 3276 extern uint32_t 3277 wimlib_get_version(void); 3278 3279 /** 3280 * @ingroup G_general 3281 * 3282 * Since wimlib v1.13.0: like wimlib_get_version(), but returns the full 3283 * PACKAGE_VERSION string that was set at build time. (This allows a beta 3284 * release to be distinguished from an official release.) 3285 */ 3286 extern const wimlib_tchar * 3287 wimlib_get_version_string(void); 3288 3289 /** 3290 * @ingroup G_wim_information 3291 * 3292 * Get basic information about a WIM file. 3293 * 3294 * @param wim 3295 * Pointer to the ::WIMStruct to query. This need not represent a 3296 * standalone WIM (e.g. it could represent part of a split WIM). 3297 * @param info 3298 * A ::wimlib_wim_info structure that will be filled in with information 3299 * about the WIM file. 3300 * 3301 * @return 0 3302 */ 3303 extern int 3304 wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); 3305 3306 /** 3307 * @ingroup G_wim_information 3308 * 3309 * Read a WIM file's XML document into an in-memory buffer. 3310 * 3311 * The XML document contains metadata about the WIM file and the images stored 3312 * in it. 3313 * 3314 * @param wim 3315 * Pointer to the ::WIMStruct to query. This need not represent a 3316 * standalone WIM (e.g. it could represent part of a split WIM). 3317 * @param buf_ret 3318 * On success, a pointer to an allocated buffer containing the raw UTF16-LE 3319 * XML document is written to this location. 3320 * @param bufsize_ret 3321 * The size of the XML document in bytes is written to this location. 3322 * 3323 * @return 0 on success; a ::wimlib_error_code value on failure. 3324 * 3325 * @retval ::WIMLIB_ERR_NO_FILENAME 3326 * @p wim is not backed by a file and therefore does not have an XML 3327 * document. 3328 * @retval ::WIMLIB_ERR_READ 3329 * Failed to read the XML document from the WIM file. 3330 * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE 3331 * Failed to read the XML document from the WIM file. 3332 */ 3333 extern int 3334 wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); 3335 3336 /** 3337 * @ingroup G_general 3338 * 3339 * Initialization function for wimlib. Call before using any other wimlib 3340 * function (except possibly wimlib_set_print_errors()). If not done manually, 3341 * this function will be called automatically with a flags argument of 0. This 3342 * function does nothing if called again after it has already successfully run. 3343 * 3344 * @param init_flags 3345 * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. 3346 * 3347 * @return 0 on success; a ::wimlib_error_code value on failure. 3348 * 3349 * @retval ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES 3350 * ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES and/or 3351 * ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES were specified in @p 3352 * init_flags, but the corresponding privileges could not be acquired. 3353 */ 3354 extern int 3355 wimlib_global_init(int init_flags); 3356 3357 /** 3358 * @ingroup G_general 3359 * 3360 * Cleanup function for wimlib. You are not required to call this function, but 3361 * it will release any global resources allocated by the library. 3362 */ 3363 extern void 3364 wimlib_global_cleanup(void); 3365 3366 /** 3367 * @ingroup G_wim_information 3368 * 3369 * Determine if an image name is already used by some image in the WIM. 3370 * 3371 * @param wim 3372 * Pointer to the ::WIMStruct to query. This need not represent a 3373 * standalone WIM (e.g. it could represent part of a split WIM). 3374 * @param name 3375 * The name to check. 3376 * 3377 * @return 3378 * @c true if there is already an image in @p wim named @p name; @c false 3379 * if there is no image named @p name in @p wim. If @p name is @c NULL or 3380 * the empty string, then @c false is returned. 3381 */ 3382 extern bool 3383 wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); 3384 3385 /** 3386 * @ingroup G_wim_information 3387 * 3388 * Iterate through a file or directory tree in a WIM image. By specifying 3389 * appropriate flags and a callback function, you can get the attributes of a 3390 * file in the image, get a directory listing, or even get a listing of the 3391 * entire image. 3392 * 3393 * @param wim 3394 * The ::WIMStruct containing the image(s) over which to iterate. This 3395 * ::WIMStruct must contain image metadata, so it cannot be the non-first 3396 * part of a split WIM (for example). 3397 * @param image 3398 * The 1-based index of the image that contains the files or directories to 3399 * iterate over, or ::WIMLIB_ALL_IMAGES to iterate over all images. 3400 * @param path 3401 * Path in the image at which to do the iteration. 3402 * @param flags 3403 * Bitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG. 3404 * @param cb 3405 * A callback function that will receive each directory entry. 3406 * @param user_ctx 3407 * An extra parameter that will always be passed to the callback function 3408 * @p cb. 3409 * 3410 * @return Normally, returns 0 if all calls to @p cb returned 0; otherwise the 3411 * first nonzero value that was returned from @p cb. However, additional 3412 * ::wimlib_error_code values may be returned, including the following: 3413 * 3414 * @retval ::WIMLIB_ERR_INVALID_IMAGE 3415 * @p image does not exist in @p wim. 3416 * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST 3417 * @p path does not exist in the image. 3418 * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND 3419 * ::WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED was specified, but the 3420 * data for some files could not be found in the blob lookup table of @p 3421 * wim. 3422 * 3423 * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, 3424 * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, 3425 * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which 3426 * indicate failure (for different reasons) to read the metadata resource for an 3427 * image over which iteration needed to be done. 3428 */ 3429 extern int 3430 wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, 3431 int flags, 3432 wimlib_iterate_dir_tree_callback_t cb, void *user_ctx); 3433 3434 /** 3435 * @ingroup G_wim_information 3436 * 3437 * Iterate through the blob lookup table of a ::WIMStruct. This can be used to 3438 * directly get a listing of the unique "blobs" contained in a WIM file, which 3439 * are deduplicated over all images. 3440 * 3441 * Specifically, each listed blob may be from any of the following sources: 3442 * 3443 * - Metadata blobs, if the ::WIMStruct contains image metadata 3444 * - File blobs from the on-disk WIM file (if any) backing the ::WIMStruct 3445 * - File blobs from files that have been added to the in-memory ::WIMStruct, 3446 * e.g. by using wimlib_add_image() 3447 * - File blobs from external WIMs referenced by 3448 * wimlib_reference_resource_files() or wimlib_reference_resources() 3449 * 3450 * @param wim 3451 * Pointer to the ::WIMStruct for which to get the blob listing. 3452 * @param flags 3453 * Reserved; set to 0. 3454 * @param cb 3455 * A callback function that will receive each blob. 3456 * @param user_ctx 3457 * An extra parameter that will always be passed to the callback function 3458 * @p cb. 3459 * 3460 * @return 0 if all calls to @p cb returned 0; otherwise the first nonzero value 3461 * that was returned from @p cb. 3462 */ 3463 extern int 3464 wimlib_iterate_lookup_table(WIMStruct *wim, int flags, 3465 wimlib_iterate_lookup_table_callback_t cb, 3466 void *user_ctx); 3467 3468 /** 3469 * @ingroup G_nonstandalone_wims 3470 * 3471 * Join a split WIM into a stand-alone (one-part) WIM. 3472 * 3473 * @param swms 3474 * An array of strings that gives the filenames of all parts of the split 3475 * WIM. No specific order is required, but all parts must be included with 3476 * no duplicates. 3477 * @param num_swms 3478 * Number of filenames in @p swms. 3479 * @param swm_open_flags 3480 * Open flags for the split WIM parts (e.g. 3481 * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). 3482 * @param wim_write_flags 3483 * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will 3484 * be used to write the joined WIM. 3485 * @param output_path 3486 * The path to write the joined WIM file to. 3487 * 3488 * @return 0 on success; a ::wimlib_error_code value on failure. This function 3489 * may return most error codes that can be returned by wimlib_open_wim() and 3490 * wimlib_write(), as well as the following error codes: 3491 * 3492 * @retval ::WIMLIB_ERR_SPLIT_INVALID 3493 * The split WIMs do not form a valid WIM because they do not include all 3494 * the parts of the original WIM, there are duplicate parts, or not all the 3495 * parts have the same GUID and compression type. 3496 * 3497 * Note: wimlib is generalized enough that this function is not actually needed 3498 * to join a split WIM; instead, you could open the first part of the split WIM, 3499 * then reference the other parts with wimlib_reference_resource_files(), then 3500 * write the joined WIM using wimlib_write(). However, wimlib_join() provides 3501 * an easy-to-use wrapper around this that has some advantages (e.g. extra 3502 * sanity checks). 3503 */ 3504 extern int 3505 wimlib_join(const wimlib_tchar * const *swms, 3506 unsigned num_swms, 3507 const wimlib_tchar *output_path, 3508 int swm_open_flags, 3509 int wim_write_flags); 3510 3511 /** 3512 * @ingroup G_nonstandalone_wims 3513 * 3514 * Same as wimlib_join(), but allows specifying a progress function. The 3515 * progress function will receive the write progress messages, such as 3516 * ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, while writing the joined WIM. In 3517 * addition, if ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p 3518 * swm_open_flags, the progress function will receive a series of 3519 * ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY messages when each of the split WIM 3520 * parts is opened. 3521 */ 3522 extern int 3523 wimlib_join_with_progress(const wimlib_tchar * const *swms, 3524 unsigned num_swms, 3525 const wimlib_tchar *output_path, 3526 int swm_open_flags, 3527 int wim_write_flags, 3528 wimlib_progress_func_t progfunc, 3529 void *progctx); 3530 3531 3532 /** 3533 * @ingroup G_mounting_wim_images 3534 * 3535 * Mount an image from a WIM file on a directory read-only or read-write. 3536 * 3537 * @param wim 3538 * Pointer to the ::WIMStruct containing the image to be mounted. This 3539 * ::WIMStruct must have a backing file. 3540 * @param image 3541 * The 1-based index of the image to mount. This image cannot have been 3542 * previously modified in memory. 3543 * @param dir 3544 * The path to an existing empty directory on which to mount the image. 3545 * @param mount_flags 3546 * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. Use 3547 * ::WIMLIB_MOUNT_FLAG_READWRITE to request a read-write mount instead of a 3548 * read-only mount. 3549 * @param staging_dir 3550 * If non-NULL, the name of a directory in which a temporary directory for 3551 * storing modified or added files will be created. Ignored if 3552 * ::WIMLIB_MOUNT_FLAG_READWRITE is not specified in @p mount_flags. If 3553 * left @c NULL, the staging directory is created in the same directory as 3554 * the backing WIM file. The staging directory is automatically deleted 3555 * when the image is unmounted. 3556 * 3557 * @return 0 on success; a ::wimlib_error_code value on failure. 3558 * 3559 * @retval ::WIMLIB_ERR_ALREADY_LOCKED 3560 * Another process is currently modifying the WIM file. 3561 * @retval ::WIMLIB_ERR_FUSE 3562 * A non-zero status code was returned by @c fuse_main(). 3563 * @retval ::WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES 3564 * There are currently multiple references to the image as a result of a 3565 * call to wimlib_export_image(). Free one before attempting the 3566 * read-write mount. 3567 * @retval ::WIMLIB_ERR_INVALID_IMAGE 3568 * @p image does not exist in @p wim. 3569 * @retval ::WIMLIB_ERR_INVALID_PARAM 3570 * @p wim was @c NULL; or @p dir was NULL or an empty string; or an 3571 * unrecognized flag was specified in @p mount_flags; or the image has 3572 * already been modified in memory (e.g. by wimlib_update_image()). 3573 * @retval ::WIMLIB_ERR_MKDIR 3574 * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the 3575 * staging directory could not be created. 3576 * @retval ::WIMLIB_ERR_WIM_IS_READONLY 3577 * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the 3578 * WIM file is considered read-only because of any of the reasons mentioned 3579 * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. 3580 * @retval ::WIMLIB_ERR_UNSUPPORTED 3581 * Mounting is not supported in this build of the library. 3582 * 3583 * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, 3584 * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, 3585 * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which 3586 * indicate failure (for different reasons) to read the metadata resource for 3587 * the image to mount. 3588 * 3589 * The ability to mount WIM images is implemented using FUSE (Filesystem in 3590 * UserSpacE). Depending on how FUSE is set up on your system, this function 3591 * may work as normal users in addition to the root user. 3592 * 3593 * Mounting WIM images is not supported if wimlib was configured 3594 * <c>--without-fuse</c>. This includes Windows builds of wimlib; 3595 * ::WIMLIB_ERR_UNSUPPORTED will be returned in such cases. 3596 * 3597 * Calling this function daemonizes the process, unless 3598 * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early error occurs. 3599 * 3600 * It is safe to mount multiple images from the same WIM file read-only at the 3601 * same time, but only if different ::WIMStruct's are used. It is @b not safe 3602 * to mount multiple images from the same WIM file read-write at the same time. 3603 * 3604 * To unmount the image, call wimlib_unmount_image(). This may be done in a 3605 * different process. 3606 */ 3607 extern int 3608 wimlib_mount_image(WIMStruct *wim, 3609 int image, 3610 const wimlib_tchar *dir, 3611 int mount_flags, 3612 const wimlib_tchar *staging_dir); 3613 3614 /** 3615 * @ingroup G_creating_and_opening_wims 3616 * 3617 * Open a WIM file and create a ::WIMStruct for it. 3618 * 3619 * @param wim_file 3620 * The path to the WIM file to open. 3621 * @param open_flags 3622 * Bitwise OR of flags prefixed with WIMLIB_OPEN_FLAG. 3623 * @param wim_ret 3624 * On success, a pointer to a new ::WIMStruct backed by the specified 3625 * on-disk WIM file is written to the memory location pointed to by this 3626 * parameter. This ::WIMStruct must be freed using using wimlib_free() 3627 * when finished with it. 3628 * 3629 * @return 0 on success; a ::wimlib_error_code value on failure. 3630 * 3631 * @retval ::WIMLIB_ERR_IMAGE_COUNT 3632 * The number of metadata resources found in the WIM did not match the 3633 * image count specified in the WIM header, or the number of <IMAGE> 3634 * elements in the XML data of the WIM did not match the image count 3635 * specified in the WIM header. 3636 * @retval ::WIMLIB_ERR_INTEGRITY 3637 * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags, and 3638 * the WIM file failed the integrity check. 3639 * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE 3640 * The library did not recognize the compression chunk size of the WIM as 3641 * valid for its compression type. 3642 * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE 3643 * The library did not recognize the compression type of the WIM. 3644 * @retval ::WIMLIB_ERR_INVALID_HEADER 3645 * The header of the WIM was otherwise invalid. 3646 * @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE 3647 * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and 3648 * the WIM contained an integrity table, but the integrity table was 3649 * invalid. 3650 * @retval ::WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY 3651 * The lookup table of the WIM was invalid. 3652 * @retval ::WIMLIB_ERR_INVALID_PARAM 3653 * @p wim_ret was @c NULL; or, @p wim_file was not a nonempty string. 3654 * @retval ::WIMLIB_ERR_IS_SPLIT_WIM 3655 * The WIM was a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was 3656 * specified in @p open_flags. 3657 * @retval ::WIMLIB_ERR_NOT_A_WIM_FILE 3658 * The file did not begin with the magic characters that identify a WIM 3659 * file. 3660 * @retval ::WIMLIB_ERR_OPEN 3661 * Failed to open the WIM file for reading. Some possible reasons: the WIM 3662 * file does not exist, or the calling process does not have permission to 3663 * open it. 3664 * @retval ::WIMLIB_ERR_READ 3665 * Failed to read data from the WIM file. 3666 * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE 3667 * Unexpected end-of-file while reading data from the WIM file. 3668 * @retval ::WIMLIB_ERR_UNKNOWN_VERSION 3669 * The WIM version number was not recognized. (May be a pre-Vista WIM.) 3670 * @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED 3671 * The WIM cannot be opened because it contains encrypted segments. (It 3672 * may be a Windows 8 "ESD" file.) 3673 * @retval ::WIMLIB_ERR_WIM_IS_INCOMPLETE 3674 * The WIM file is not complete (e.g. the program which wrote it was 3675 * terminated before it finished) 3676 * @retval ::WIMLIB_ERR_WIM_IS_READONLY 3677 * ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was 3678 * considered read-only because of any of the reasons mentioned in the 3679 * documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. 3680 * @retval ::WIMLIB_ERR_XML 3681 * The XML data of the WIM was invalid. 3682 */ 3683 extern int 3684 wimlib_open_wim(const wimlib_tchar *wim_file, 3685 int open_flags, 3686 WIMStruct **wim_ret); 3687 3688 /** 3689 * @ingroup G_creating_and_opening_wims 3690 * 3691 * Same as wimlib_open_wim(), but allows specifying a progress function and 3692 * progress context. If successful, the progress function will be registered in 3693 * the newly open ::WIMStruct, as if by an automatic call to 3694 * wimlib_register_progress_function(). In addition, if 3695 * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p open_flags, then the 3696 * progress function will receive ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY 3697 * messages while checking the WIM file's integrity. 3698 */ 3699 extern int 3700 wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, 3701 int open_flags, 3702 WIMStruct **wim_ret, 3703 wimlib_progress_func_t progfunc, 3704 void *progctx); 3705 3706 /** 3707 * @ingroup G_writing_and_overwriting_wims 3708 * 3709 * Commit a ::WIMStruct to disk, updating its backing file. 3710 * 3711 * There are several alternative ways in which changes may be committed: 3712 * 3713 * 1. Full rebuild: write the updated WIM to a temporary file, then rename the 3714 * temporary file to the original. 3715 * 2. Appending: append updates to the new original WIM file, then overwrite 3716 * its header such that those changes become visible to new readers. 3717 * 3. Compaction: normally should not be used; see 3718 * ::WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details. 3719 * 3720 * Append mode is often much faster than a full rebuild, but it wastes some 3721 * amount of space due to leaving "holes" in the WIM file. Because of the 3722 * greater efficiency, wimlib_overwrite() normally defaults to append mode. 3723 * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full 3724 * rebuild. In addition, if wimlib_delete_image() has been used on the 3725 * ::WIMStruct, then the default mode switches to rebuild mode, and 3726 * ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append 3727 * mode. 3728 * 3729 * If this function completes successfully, then no more functions can be called 3730 * on the ::WIMStruct other than wimlib_free(). If you need to continue using 3731 * the WIM file, you must use wimlib_open_wim() to open a new ::WIMStruct for 3732 * it. 3733 * 3734 * @param wim 3735 * Pointer to a ::WIMStruct to commit to its backing file. 3736 * @param write_flags 3737 * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. 3738 * @param num_threads 3739 * The number of threads to use for compressing data, or 0 to have the 3740 * library automatically choose an appropriate number. 3741 * 3742 * @return 0 on success; a ::wimlib_error_code value on failure. This function 3743 * may return most error codes returned by wimlib_write() as well as the 3744 * following error codes: 3745 * 3746 * @retval ::WIMLIB_ERR_ALREADY_LOCKED 3747 * Another process is currently modifying the WIM file. 3748 * @retval ::WIMLIB_ERR_NO_FILENAME 3749 * @p wim is not backed by an on-disk file. In other words, it is a 3750 * ::WIMStruct created by wimlib_create_new_wim() rather than 3751 * wimlib_open_wim(). 3752 * @retval ::WIMLIB_ERR_RENAME 3753 * The temporary file to which the WIM was written could not be renamed to 3754 * the original file. 3755 * @retval ::WIMLIB_ERR_WIM_IS_READONLY 3756 * The WIM file is considered read-only because of any of the reasons 3757 * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS 3758 * flag. 3759 * 3760 * If a progress function is registered with @p wim, then it will receive the 3761 * messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, 3762 * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and 3763 * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END. 3764 */ 3765 extern int 3766 wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads); 3767 3768 /** 3769 * @ingroup G_wim_information 3770 * 3771 * (Deprecated) Print information about one image, or all images, contained in a 3772 * WIM. 3773 * 3774 * @param wim 3775 * Pointer to the ::WIMStruct to query. This need not represent a 3776 * standalone WIM (e.g. it could represent part of a split WIM). 3777 * @param image 3778 * The 1-based index of the image for which to print information, or 3779 * ::WIMLIB_ALL_IMAGES to print information about all images. 3780 * 3781 * @return This function has no return value. No error checking is done when 3782 * printing the information. If @p image is invalid, an error message is 3783 * printed. 3784 * 3785 * This function is deprecated; use wimlib_get_xml_data() or 3786 * wimlib_get_image_property() to query image information instead. 3787 */ 3788 extern void 3789 wimlib_print_available_images(const WIMStruct *wim, int image); 3790 3791 /** 3792 * @ingroup G_wim_information 3793 * 3794 * Print the header of the WIM file (intended for debugging only). 3795 */ 3796 extern void 3797 wimlib_print_header(const WIMStruct *wim); 3798 3799 /** 3800 * @ingroup G_nonstandalone_wims 3801 * 3802 * Reference file data from other WIM files or split WIM parts. This function 3803 * can be used on WIMs that are not standalone, such as split or "delta" WIMs, 3804 * to load additional file data before calling a function such as 3805 * wimlib_extract_image() that requires the file data to be present. 3806 * 3807 * @param wim 3808 * The ::WIMStruct for a WIM that contains metadata resources, but is not 3809 * necessarily "standalone". In the case of split WIMs, this should be the 3810 * first part, since only the first part contains the metadata resources. 3811 * In the case of delta WIMs, this should be the delta WIM rather than the 3812 * WIM on which it is based. 3813 * @param resource_wimfiles_or_globs 3814 * Array of paths to WIM files and/or split WIM parts to reference. 3815 * Alternatively, when ::WIMLIB_REF_FLAG_GLOB_ENABLE is specified in @p 3816 * ref_flags, these are treated as globs rather than literal paths. That 3817 * is, using this function you can specify zero or more globs, each of 3818 * which expands to one or more literal paths. 3819 * @param count 3820 * Number of entries in @p resource_wimfiles_or_globs. 3821 * @param ref_flags 3822 * Bitwise OR of ::WIMLIB_REF_FLAG_GLOB_ENABLE and/or 3823 * ::WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH. 3824 * @param open_flags 3825 * Additional open flags, such as ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY, to 3826 * pass to internal calls to wimlib_open_wim() on the reference files. 3827 * 3828 * @return 0 on success; a ::wimlib_error_code value on failure. 3829 * 3830 * @retval ::WIMLIB_ERR_GLOB_HAD_NO_MATCHES 3831 * One of the specified globs did not match any paths (only with both 3832 * ::WIMLIB_REF_FLAG_GLOB_ENABLE and ::WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 3833 * specified in @p ref_flags). 3834 * @retval ::WIMLIB_ERR_READ 3835 * I/O or permissions error while processing a file glob. 3836 * 3837 * This function can additionally return most values that can be returned by 3838 * wimlib_open_wim(). 3839 */ 3840 extern int 3841 wimlib_reference_resource_files(WIMStruct *wim, 3842 const wimlib_tchar * const *resource_wimfiles_or_globs, 3843 unsigned count, 3844 int ref_flags, 3845 int open_flags); 3846 3847 /** 3848 * @ingroup G_nonstandalone_wims 3849 * 3850 * Similar to wimlib_reference_resource_files(), but operates at a lower level 3851 * where the caller must open the ::WIMStruct for each referenced file itself. 3852 * 3853 * @param wim 3854 * The ::WIMStruct for a WIM that contains metadata resources, but is not 3855 * necessarily "standalone". In the case of split WIMs, this should be the 3856 * first part, since only the first part contains the metadata resources. 3857 * @param resource_wims 3858 * Array of pointers to the ::WIMStruct's for additional resource WIMs or 3859 * split WIM parts to reference. 3860 * @param num_resource_wims 3861 * Number of entries in @p resource_wims. 3862 * @param ref_flags 3863 * Reserved; must be 0. 3864 * 3865 * @return 0 on success; a ::wimlib_error_code value on failure. 3866 */ 3867 extern int 3868 wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, 3869 unsigned num_resource_wims, int ref_flags); 3870 3871 /** 3872 * @ingroup G_modifying_wims 3873 * 3874 * Declare that a newly added image is mostly the same as a prior image, but 3875 * captured at a later point in time, possibly with some modifications in the 3876 * intervening time. This is designed to be used in incremental backups of the 3877 * same filesystem or directory tree. 3878 * 3879 * This function compares the metadata of the directory tree of the newly added 3880 * image against that of the old image. Any files that are present in both the 3881 * newly added image and the old image and have timestamps that indicate they 3882 * haven't been modified are deemed not to have been modified and have their 3883 * checksums copied from the old image. Because of this and because WIM uses 3884 * single-instance streams, such files need not be read from the filesystem when 3885 * the WIM is being written or overwritten. Note that these unchanged files 3886 * will still be "archived" and will be logically present in the new image; the 3887 * optimization is that they don't need to actually be read from the filesystem 3888 * because the WIM already contains them. 3889 * 3890 * This function is provided to optimize incremental backups. The resulting WIM 3891 * file will still be the same regardless of whether this function is called. 3892 * (This is, however, assuming that timestamps have not been manipulated or 3893 * unmaintained as to trick this function into thinking a file has not been 3894 * modified when really it has. To partly guard against such cases, other 3895 * metadata such as file sizes will be checked as well.) 3896 * 3897 * This function must be called after adding the new image (e.g. with 3898 * wimlib_add_image()), but before writing the updated WIM file (e.g. with 3899 * wimlib_overwrite()). 3900 * 3901 * @param wim 3902 * Pointer to the ::WIMStruct containing the newly added image. 3903 * @param new_image 3904 * The 1-based index in @p wim of the newly added image. 3905 * @param template_wim 3906 * Pointer to the ::WIMStruct containing the template image. This can be, 3907 * but does not have to be, the same ::WIMStruct as @p wim. 3908 * @param template_image 3909 * The 1-based index in @p template_wim of the template image. 3910 * @param flags 3911 * Reserved; must be 0. 3912 * 3913 * @return 0 on success; a ::wimlib_error_code value on failure. 3914 * 3915 * @retval ::WIMLIB_ERR_INVALID_IMAGE 3916 * @p new_image does not exist in @p wim or @p template_image does not 3917 * exist in @p template_wim. 3918 * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND 3919 * At least one of @p wim and @p template_wim does not contain image 3920 * metadata; for example, one of them represents a non-first part of a 3921 * split WIM. 3922 * @retval ::WIMLIB_ERR_INVALID_PARAM 3923 * Identical values were provided for the template and new image; or @p 3924 * new_image specified an image that had not been modified since opening 3925 * the WIM. 3926 * 3927 * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, 3928 * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, 3929 * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which 3930 * indicate failure (for different reasons) to read the metadata resource for 3931 * the template image. 3932 */ 3933 extern int 3934 wimlib_reference_template_image(WIMStruct *wim, int new_image, 3935 WIMStruct *template_wim, int template_image, 3936 int flags); 3937 3938 /** 3939 * @ingroup G_general 3940 * 3941 * Register a progress function with a ::WIMStruct. 3942 * 3943 * @param wim 3944 * The ::WIMStruct for which to register the progress function. 3945 * @param progfunc 3946 * Pointer to the progress function to register. If the WIM already has a 3947 * progress function registered, it will be replaced with this one. If @p 3948 * NULL, the current progress function (if any) will be unregistered. 3949 * @param progctx 3950 * The value which will be passed as the third argument to calls to @p 3951 * progfunc. 3952 */ 3953 extern void 3954 wimlib_register_progress_function(WIMStruct *wim, 3955 wimlib_progress_func_t progfunc, 3956 void *progctx); 3957 3958 /** 3959 * @ingroup G_modifying_wims 3960 * 3961 * Rename the @p source_path to the @p dest_path in the specified @p image of 3962 * the @p wim. 3963 * 3964 * This just builds an appropriate ::wimlib_rename_command and passes it to 3965 * wimlib_update_image(). 3966 */ 3967 extern int 3968 wimlib_rename_path(WIMStruct *wim, int image, 3969 const wimlib_tchar *source_path, const wimlib_tchar *dest_path); 3970 3971 /** 3972 * @ingroup G_wim_information 3973 * 3974 * Translate a string specifying the name or number of an image in the WIM into 3975 * the number of the image. The images are numbered starting at 1. 3976 * 3977 * @param wim 3978 * Pointer to the ::WIMStruct for a WIM. 3979 * @param image_name_or_num 3980 * A string specifying the name or number of an image in the WIM. If it 3981 * parses to a positive integer, this integer is taken to specify the 3982 * number of the image, indexed starting at 1. Otherwise, it is taken to 3983 * be the name of an image, as given in the XML data for the WIM file. It 3984 * also may be the keyword "all" or the string "*", both of which will 3985 * resolve to ::WIMLIB_ALL_IMAGES. 3986 * <br/> <br/> 3987 * There is no way to search for an image actually named "all", "*", or an 3988 * integer number, or an image that has no name. However, you can use 3989 * wimlib_get_image_name() to get the name of any image. 3990 * 3991 * @return 3992 * If the string resolved to a single existing image, the number of that 3993 * image, indexed starting at 1, is returned. If the keyword "all" or "*" 3994 * was specified, ::WIMLIB_ALL_IMAGES is returned. Otherwise, 3995 * ::WIMLIB_NO_IMAGE is returned. If @p image_name_or_num was @c NULL or 3996 * the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more 3997 * images in @p wim has no name. (Since a WIM may have multiple unnamed 3998 * images, an unnamed image must be specified by index to eliminate the 3999 * ambiguity.) 4000 */ 4001 extern int 4002 wimlib_resolve_image(WIMStruct *wim, 4003 const wimlib_tchar *image_name_or_num); 4004 4005 /** 4006 * @ingroup G_general 4007 * 4008 * Set the file to which the library will print error and warning messages. 4009 * 4010 * This version of the function takes a C library <c>FILE*</c> opened for 4011 * writing (or appending). Use wimlib_set_error_file_by_name() to specify the 4012 * file by name instead. 4013 * 4014 * This also enables error messages, as if by a call to 4015 * wimlib_set_print_errors(true). 4016 * 4017 * @return 0 on success; a ::wimlib_error_code value on failure. 4018 * 4019 * @retval ::WIMLIB_ERR_UNSUPPORTED 4020 * wimlib was compiled using the <c>--without-error-messages</c> option. 4021 */ 4022 extern int 4023 wimlib_set_error_file(FILE *fp); 4024 4025 /** 4026 * @ingroup G_general 4027 * 4028 * Set the path to the file to which the library will print error and warning 4029 * messages. The library will open this file for appending. 4030 * 4031 * This also enables error messages, as if by a call to 4032 * wimlib_set_print_errors(true). 4033 * 4034 * @return 0 on success; a ::wimlib_error_code value on failure. 4035 * 4036 * @retval ::WIMLIB_ERR_OPEN 4037 * The file named by @p path could not be opened for appending. 4038 * @retval ::WIMLIB_ERR_UNSUPPORTED 4039 * wimlib was compiled using the <c>--without-error-messages</c> option. 4040 */ 4041 extern int 4042 wimlib_set_error_file_by_name(const wimlib_tchar *path); 4043 4044 /** 4045 * @ingroup G_modifying_wims 4046 * 4047 * Change the description of a WIM image. Equivalent to 4048 * <tt>wimlib_set_image_property(wim, image, "DESCRIPTION", description)</tt>. 4049 * 4050 * Note that "description" is misspelled in the name of this function. 4051 */ 4052 extern int 4053 wimlib_set_image_descripton(WIMStruct *wim, int image, 4054 const wimlib_tchar *description); 4055 4056 /** 4057 * @ingroup G_modifying_wims 4058 * 4059 * Change what is stored in the \<FLAGS\> element in the WIM XML document 4060 * (usually something like "Core" or "Ultimate"). Equivalent to 4061 * <tt>wimlib_set_image_property(wim, image, "FLAGS", flags)</tt>. 4062 */ 4063 extern int 4064 wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); 4065 4066 /** 4067 * @ingroup G_modifying_wims 4068 * 4069 * Change the name of a WIM image. Equivalent to 4070 * <tt>wimlib_set_image_property(wim, image, "NAME", name)</tt>. 4071 */ 4072 extern int 4073 wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); 4074 4075 /** 4076 * @ingroup G_modifying_wims 4077 * 4078 * Since wimlib v1.8.3: add, modify, or remove a per-image property from the 4079 * WIM's XML document. This is an alternative to wimlib_set_image_name(), 4080 * wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows 4081 * manipulating any simple string property. 4082 * 4083 * @param wim 4084 * Pointer to the ::WIMStruct for the WIM. 4085 * @param image 4086 * The 1-based index of the image for which to set the property. 4087 * @param property_name 4088 * The name of the image property in the same format documented for 4089 * wimlib_get_image_property(). 4090 * <br/> 4091 * Note: if creating a new element using a bracketed index such as 4092 * "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified 4093 * is one greater than the number of existing elements with that same name, 4094 * excluding the index. That means that if you are adding a list of new 4095 * elements, they must be added sequentially from the first index (1) to 4096 * the last index (n). 4097 * @param property_value 4098 * If not NULL and not empty, the property is set to this value. 4099 * Otherwise, the property is removed from the XML document. 4100 * 4101 * @return 0 on success; a ::wimlib_error_code value on failure. 4102 * 4103 * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION 4104 * The user requested to set the image name (the <tt>NAME</tt> property), 4105 * but another image in the WIM already had the requested name. 4106 * @retval ::WIMLIB_ERR_INVALID_IMAGE 4107 * @p image does not exist in @p wim. 4108 * @retval ::WIMLIB_ERR_INVALID_PARAM 4109 * @p property_name has an unsupported format, or @p property_name included 4110 * a bracketed index that was too high. 4111 */ 4112 extern int 4113 wimlib_set_image_property(WIMStruct *wim, int image, 4114 const wimlib_tchar *property_name, 4115 const wimlib_tchar *property_value); 4116 4117 /** 4118 * @ingroup G_general 4119 * 4120 * Set the functions that wimlib uses to allocate and free memory. 4121 * 4122 * These settings are global and not per-WIM. 4123 * 4124 * The default is to use the default @c malloc(), @c free(), and @c realloc() 4125 * from the standard C library. 4126 * 4127 * Note: some external functions, such as those in @c libntfs-3g, may use the 4128 * standard memory allocation functions regardless of this setting. 4129 * 4130 * @param malloc_func 4131 * A function equivalent to @c malloc() that wimlib will use to allocate 4132 * memory. If @c NULL, the allocator function is set back to the default 4133 * @c malloc() from the C library. 4134 * @param free_func 4135 * A function equivalent to @c free() that wimlib will use to free memory. 4136 * If @c NULL, the free function is set back to the default @c free() from 4137 * the C library. 4138 * @param realloc_func 4139 * A function equivalent to @c realloc() that wimlib will use to reallocate 4140 * memory. If @c NULL, the free function is set back to the default @c 4141 * realloc() from the C library. 4142 * 4143 * @return 0 4144 */ 4145 extern int 4146 wimlib_set_memory_allocator(void *(*malloc_func)(size_t), 4147 void (*free_func)(void *), 4148 void *(*realloc_func)(void *, size_t)); 4149 4150 /** 4151 * @ingroup G_writing_and_overwriting_wims 4152 * 4153 * Set a ::WIMStruct's output compression chunk size. This is the compression 4154 * chunk size that will be used for writing non-solid resources in subsequent 4155 * calls to wimlib_write() or wimlib_overwrite(). A larger compression chunk 4156 * size often results in a better compression ratio, but compression may be 4157 * slower and the speed of random access to data may be reduced. In addition, 4158 * some chunk sizes are not compatible with Microsoft software. 4159 * 4160 * @param wim 4161 * The ::WIMStruct for which to set the output chunk size. 4162 * @param chunk_size 4163 * The chunk size (in bytes) to set. The valid chunk sizes are dependent 4164 * on the compression type. See the documentation for each 4165 * ::wimlib_compression_type constant for more information. As a special 4166 * case, if @p chunk_size is specified as 0, then the chunk size will be 4167 * reset to the default for the currently selected output compression type. 4168 * 4169 * @return 0 on success; a ::wimlib_error_code value on failure. 4170 * 4171 * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE 4172 * @p chunk_size was not 0 or a supported chunk size for the currently 4173 * selected output compression type. 4174 */ 4175 extern int 4176 wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); 4177 4178 /** 4179 * @ingroup G_writing_and_overwriting_wims 4180 * 4181 * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing 4182 * solid resources. 4183 */ 4184 extern int 4185 wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size); 4186 4187 /** 4188 * @ingroup G_writing_and_overwriting_wims 4189 * 4190 * Set a ::WIMStruct's output compression type. This is the compression type 4191 * that will be used for writing non-solid resources in subsequent calls to 4192 * wimlib_write() or wimlib_overwrite(). 4193 * 4194 * @param wim 4195 * The ::WIMStruct for which to set the output compression type. 4196 * @param ctype 4197 * The compression type to set. If this compression type is incompatible 4198 * with the current output chunk size, then the output chunk size will be 4199 * reset to the default for the new compression type. 4200 * 4201 * @return 0 on success; a ::wimlib_error_code value on failure. 4202 * 4203 * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE 4204 * @p ctype did not specify a valid compression type. 4205 */ 4206 extern int 4207 wimlib_set_output_compression_type(WIMStruct *wim, 4208 enum wimlib_compression_type ctype); 4209 4210 /** 4211 * @ingroup G_writing_and_overwriting_wims 4212 * 4213 * Similar to wimlib_set_output_compression_type(), but set the compression type 4214 * for writing solid resources. This cannot be ::WIMLIB_COMPRESSION_TYPE_NONE. 4215 */ 4216 extern int 4217 wimlib_set_output_pack_compression_type(WIMStruct *wim, 4218 enum wimlib_compression_type ctype); 4219 4220 /** 4221 * @ingroup G_general 4222 * 4223 * Set whether wimlib can print error and warning messages to the error file, 4224 * which defaults to standard error. Error and warning messages may provide 4225 * information that cannot be determined only from returned error codes. 4226 * 4227 * By default, error messages are not printed. 4228 * 4229 * This setting applies globally (it is not per-WIM). 4230 * 4231 * This can be called before wimlib_global_init(). 4232 * 4233 * @param show_messages 4234 * @c true if messages are to be printed; @c false if messages are not to 4235 * be printed. 4236 * 4237 * @return 0 on success; a ::wimlib_error_code value on failure. 4238 * 4239 * @retval ::WIMLIB_ERR_UNSUPPORTED 4240 * wimlib was compiled using the <c>--without-error-messages</c> option. 4241 */ 4242 extern int 4243 wimlib_set_print_errors(bool show_messages); 4244 4245 /** 4246 * @ingroup G_modifying_wims 4247 * 4248 * Set basic information about a WIM. 4249 * 4250 * @param wim 4251 * Pointer to the ::WIMStruct for a WIM. 4252 * @param info 4253 * Pointer to a ::wimlib_wim_info structure that contains the information 4254 * to set. Only the information explicitly specified in the @p which flags 4255 * need be valid. 4256 * @param which 4257 * Flags that specify which information to set. This is a bitwise OR of 4258 * ::WIMLIB_CHANGE_READONLY_FLAG, ::WIMLIB_CHANGE_GUID, 4259 * ::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG. 4260 * 4261 * @return 0 on success; a ::wimlib_error_code value on failure. 4262 * 4263 * @retval ::WIMLIB_ERR_IMAGE_COUNT 4264 * ::WIMLIB_CHANGE_BOOT_INDEX was specified, but 4265 * ::wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image 4266 * index in the WIM. 4267 */ 4268 extern int 4269 wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info, 4270 int which); 4271 4272 /** 4273 * @ingroup G_nonstandalone_wims 4274 * 4275 * Split a WIM into multiple parts. 4276 * 4277 * @param wim 4278 * The ::WIMStruct for the WIM to split. 4279 * @param swm_name 4280 * Name of the split WIM (SWM) file to create. This will be the name of 4281 * the first part. The other parts will, by default, have the same name 4282 * with 2, 3, 4, ..., etc. appended before the suffix. However, the exact 4283 * names can be customized using the progress function. 4284 * @param part_size 4285 * The maximum size per part, in bytes. Unfortunately, it is not 4286 * guaranteed that this will really be the maximum size per part, because 4287 * some file resources in the WIM may be larger than this size, and the WIM 4288 * file format provides no way to split up file resources among multiple 4289 * WIMs. 4290 * @param write_flags 4291 * Bitwise OR of relevant flags prefixed with @c WIMLIB_WRITE_FLAG. These 4292 * flags will be used to write each split WIM part. Specify 0 here to get 4293 * the default behavior. 4294 * 4295 * @return 0 on success; a ::wimlib_error_code value on failure. This function 4296 * may return most error codes that can be returned by wimlib_write() as well as 4297 * the following error codes: 4298 * 4299 * @retval ::WIMLIB_ERR_INVALID_PARAM 4300 * @p swm_name was not a nonempty string, or @p part_size was 0. 4301 * @retval ::WIMLIB_ERR_UNSUPPORTED 4302 * The WIM contains solid resources. Splitting a WIM containing solid 4303 * resources is not supported. 4304 * 4305 * If a progress function is registered with @p wim, then for each split WIM 4306 * part that is written it will receive the messages 4307 * ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and 4308 * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART. 4309 */ 4310 extern int 4311 wimlib_split(WIMStruct *wim, 4312 const wimlib_tchar *swm_name, 4313 uint64_t part_size, 4314 int write_flags); 4315 4316 /** 4317 * @ingroup G_general 4318 * 4319 * Perform verification checks on a WIM file. 4320 * 4321 * This function is intended for safety checking and/or debugging. If used on a 4322 * well-formed WIM file, it should always succeed. 4323 * 4324 * @param wim 4325 * The ::WIMStruct for the WIM file to verify. Note: for an extra layer of 4326 * verification, it is a good idea to have used 4327 * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY when you opened the file. 4328 * <br/> 4329 * If verifying a split WIM, specify the first part of the split WIM here, 4330 * and reference the other parts using wimlib_reference_resource_files() 4331 * before calling this function. 4332 * @param verify_flags 4333 * Reserved; must be 0. 4334 * 4335 * @return 0 if the WIM file was successfully verified; a ::wimlib_error_code 4336 * value if it failed verification or another error occurred. 4337 * 4338 * @retval ::WIMLIB_ERR_DECOMPRESSION 4339 * The WIM file contains invalid compressed data. 4340 * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE 4341 * The metadata resource for an image is invalid. 4342 * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH 4343 * File data stored in the WIM file is corrupt. 4344 * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND 4345 * The data for a file in an image could not be found. See @ref 4346 * G_nonstandalone_wims. 4347 * 4348 * If a progress function is registered with @p wim, then it will receive the 4349 * following progress messages: ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE, 4350 * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE, and 4351 * ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS. 4352 */ 4353 extern int 4354 wimlib_verify_wim(WIMStruct *wim, int verify_flags); 4355 4356 /** 4357 * @ingroup G_mounting_wim_images 4358 * 4359 * Unmount a WIM image that was mounted using wimlib_mount_image(). 4360 * 4361 * When unmounting a read-write mounted image, the default behavior is to 4362 * discard changes to the image. Use ::WIMLIB_UNMOUNT_FLAG_COMMIT to cause the 4363 * image to be committed. 4364 * 4365 * @param dir 4366 * The directory on which the WIM image is mounted. 4367 * @param unmount_flags 4368 * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG. 4369 * 4370 * @return 0 on success; a ::wimlib_error_code value on failure. 4371 * 4372 * @retval ::WIMLIB_ERR_NOT_A_MOUNTPOINT 4373 * There is no WIM image mounted on the specified directory. 4374 * @retval ::WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY 4375 * The read-write mounted image cannot be committed because there are file 4376 * descriptors open to it, and ::WIMLIB_UNMOUNT_FLAG_FORCE was not 4377 * specified. 4378 * @retval ::WIMLIB_ERR_MQUEUE 4379 * Could not create a POSIX message queue. 4380 * @retval ::WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT 4381 * The image was mounted by a different user. 4382 * @retval ::WIMLIB_ERR_UNSUPPORTED 4383 * Mounting is not supported in this build of the library. 4384 * 4385 * Note: you can also unmount the image by using the @c umount() system call, or 4386 * by using the @c umount or @c fusermount programs. However, you need to call 4387 * this function if you want changes to be committed. 4388 */ 4389 extern int 4390 wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags); 4391 4392 /** 4393 * @ingroup G_mounting_wim_images 4394 * 4395 * Same as wimlib_unmount_image(), but allows specifying a progress function. 4396 * The progress function will receive a ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN 4397 * message. In addition, if changes are committed from a read-write mount, the 4398 * progress function will receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages. 4399 */ 4400 extern int 4401 wimlib_unmount_image_with_progress(const wimlib_tchar *dir, 4402 int unmount_flags, 4403 wimlib_progress_func_t progfunc, 4404 void *progctx); 4405 4406 /** 4407 * @ingroup G_modifying_wims 4408 * 4409 * Update a WIM image by adding, deleting, and/or renaming files or directories. 4410 * 4411 * @param wim 4412 * Pointer to the ::WIMStruct containing the image to update. 4413 * @param image 4414 * The 1-based index of the image to update. 4415 * @param cmds 4416 * An array of ::wimlib_update_command's that specify the update operations 4417 * to perform. 4418 * @param num_cmds 4419 * Number of commands in @p cmds. 4420 * @param update_flags 4421 * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0. 4422 * 4423 * @return 0 on success; a ::wimlib_error_code value on failure. On failure, 4424 * all update commands will be rolled back, and no visible changes will have 4425 * been made to @p wim. 4426 * 4427 * @retval ::WIMLIB_ERR_FVE_LOCKED_VOLUME 4428 * Windows-only: One of the "add" commands attempted to add files from an 4429 * encrypted BitLocker volume that hasn't yet been unlocked. 4430 * @retval ::WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES 4431 * There are currently multiple references to the image as a result of a 4432 * call to wimlib_export_image(). Free one before attempting the update. 4433 * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG 4434 * The contents of a capture configuration file were invalid. 4435 * @retval ::WIMLIB_ERR_INVALID_IMAGE 4436 * @p image did not exist in @p wim. 4437 * @retval ::WIMLIB_ERR_INVALID_OVERLAY 4438 * An add command with ::WIMLIB_ADD_FLAG_NO_REPLACE specified attempted to 4439 * replace an existing nondirectory file. 4440 * @retval ::WIMLIB_ERR_INVALID_PARAM 4441 * An unknown operation type was provided in the update commands; or 4442 * unknown or incompatible flags were provided in a flags parameter; or 4443 * there was another problem with the provided parameters. 4444 * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA 4445 * While executing an add command, a reparse point had invalid data. 4446 * @retval ::WIMLIB_ERR_IS_DIRECTORY 4447 * An add command attempted to replace a directory with a non-directory; or 4448 * a delete command without ::WIMLIB_DELETE_FLAG_RECURSIVE attempted to 4449 * delete a directory; or a rename command attempted to rename a directory 4450 * to a non-directory. 4451 * @retval ::WIMLIB_ERR_NOTDIR 4452 * An add command attempted to replace a non-directory with a directory; or 4453 * an add command attempted to set the root of the image to a 4454 * non-directory; or a rename command attempted to rename a directory to a 4455 * non-directory; or a component of an image path that was used as a 4456 * directory was not, in fact, a directory. 4457 * @retval ::WIMLIB_ERR_NOTEMPTY 4458 * A rename command attempted to rename a directory to a non-empty 4459 * directory; or a rename command would have created a loop. 4460 * @retval ::WIMLIB_ERR_NTFS_3G 4461 * While executing an add command with ::WIMLIB_ADD_FLAG_NTFS specified, an 4462 * error occurred while reading data from the NTFS volume using libntfs-3g. 4463 * @retval ::WIMLIB_ERR_OPEN 4464 * Failed to open a file to be captured while executing an add command. 4465 * @retval ::WIMLIB_ERR_OPENDIR 4466 * Failed to open a directory to be captured while executing an add 4467 * command. 4468 * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST 4469 * A delete command without ::WIMLIB_DELETE_FLAG_FORCE specified was for a 4470 * WIM path that did not exist; or a rename command attempted to rename a 4471 * file that does not exist. 4472 * @retval ::WIMLIB_ERR_READ 4473 * While executing an add command, failed to read data from a file or 4474 * directory to be captured. 4475 * @retval ::WIMLIB_ERR_READLINK 4476 * While executing an add command, failed to read the target of a symbolic 4477 * link, junction, or other reparse point. 4478 * @retval ::WIMLIB_ERR_STAT 4479 * While executing an add command, failed to read metadata for a file or 4480 * directory. 4481 * @retval ::WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG 4482 * A capture configuration file could not be read. 4483 * @retval ::WIMLIB_ERR_UNSUPPORTED 4484 * A command had flags provided that are not supported on this platform or 4485 * in this build of the library. 4486 * @retval ::WIMLIB_ERR_UNSUPPORTED_FILE 4487 * An add command with ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified 4488 * discovered a file that was not of a supported type. 4489 * 4490 * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, 4491 * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, 4492 * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which 4493 * indicate failure (for different reasons) to read the metadata resource for an 4494 * image that needed to be updated. 4495 */ 4496 extern int 4497 wimlib_update_image(WIMStruct *wim, 4498 int image, 4499 const struct wimlib_update_command *cmds, 4500 size_t num_cmds, 4501 int update_flags); 4502 4503 /** 4504 * @ingroup G_writing_and_overwriting_wims 4505 * 4506 * Persist a ::WIMStruct to a new on-disk WIM file. 4507 * 4508 * This brings in file data from any external locations, such as directory trees 4509 * or NTFS volumes scanned with wimlib_add_image(), or other WIM files via 4510 * wimlib_export_image(), and incorporates it into a new on-disk WIM file. 4511 * 4512 * By default, the new WIM file is written as stand-alone. Using the 4513 * ::WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS flag, a "delta" WIM can be written 4514 * instead. However, this function cannot directly write a "split" WIM; use 4515 * wimlib_split() for that. 4516 * 4517 * @param wim 4518 * Pointer to the ::WIMStruct being persisted. 4519 * @param path 4520 * The path to the on-disk file to write. 4521 * @param image 4522 * Normally, specify ::WIMLIB_ALL_IMAGES here. This indicates that all 4523 * images are to be included in the new on-disk WIM file. If for some 4524 * reason you only want to include a single image, specify the 1-based 4525 * index of that image instead. 4526 * @param write_flags 4527 * Bitwise OR of flags prefixed with @c WIMLIB_WRITE_FLAG. 4528 * @param num_threads 4529 * The number of threads to use for compressing data, or 0 to have the 4530 * library automatically choose an appropriate number. 4531 * 4532 * @return 0 on success; a ::wimlib_error_code value on failure. 4533 * 4534 * @retval ::WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED 4535 * A file that had previously been scanned for inclusion in the WIM was 4536 * concurrently modified. 4537 * @retval ::WIMLIB_ERR_INVALID_IMAGE 4538 * @p image did not exist in @p wim. 4539 * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH 4540 * A file, stored in another WIM, which needed to be written was corrupt. 4541 * @retval ::WIMLIB_ERR_INVALID_PARAM 4542 * @p path was not a nonempty string, or invalid flags were passed. 4543 * @retval ::WIMLIB_ERR_OPEN 4544 * Failed to open the output WIM file for writing, or failed to open a file 4545 * whose data needed to be included in the WIM. 4546 * @retval ::WIMLIB_ERR_READ 4547 * Failed to read data that needed to be included in the WIM. 4548 * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND 4549 * A file data blob that needed to be written could not be found in the 4550 * blob lookup table of @p wim. See @ref G_nonstandalone_wims. 4551 * @retval ::WIMLIB_ERR_WRITE 4552 * An error occurred when trying to write data to the new WIM file. 4553 * 4554 * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, 4555 * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, 4556 * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which 4557 * indicate failure (for different reasons) to read the data from a WIM file. 4558 * 4559 * If a progress function is registered with @p wim, then it will receive the 4560 * messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, 4561 * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and 4562 * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END. 4563 */ 4564 extern int 4565 wimlib_write(WIMStruct *wim, 4566 const wimlib_tchar *path, 4567 int image, 4568 int write_flags, 4569 unsigned num_threads); 4570 4571 /** 4572 * @ingroup G_writing_and_overwriting_wims 4573 * 4574 * Same as wimlib_write(), but write the WIM directly to a file descriptor, 4575 * which need not be seekable if the write is done in a special pipable WIM 4576 * format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p write_flags. This can, 4577 * for example, allow capturing a WIM image and streaming it over the network. 4578 * See @ref subsec_pipable_wims for more information about pipable WIMs. 4579 * 4580 * The file descriptor @p fd will @b not be closed when the write is complete; 4581 * the calling code is responsible for this. 4582 * 4583 * @return 0 on success; a ::wimlib_error_code value on failure. The possible 4584 * error codes include those that can be returned by wimlib_write() as well as 4585 * the following: 4586 * 4587 * @retval ::WIMLIB_ERR_INVALID_PARAM 4588 * @p fd was not seekable, but ::WIMLIB_WRITE_FLAG_PIPABLE was not 4589 * specified in @p write_flags. 4590 */ 4591 extern int 4592 wimlib_write_to_fd(WIMStruct *wim, 4593 int fd, 4594 int image, 4595 int write_flags, 4596 unsigned num_threads); 4597 4598 /** 4599 * @defgroup G_compression Compression and decompression functions 4600 * 4601 * @brief Functions for XPRESS, LZX, and LZMS compression and decompression. 4602 * 4603 * These functions are already used by wimlib internally when appropriate for 4604 * reading and writing WIM archives. But they are exported and documented so 4605 * that they can be used in other applications or libraries for general-purpose 4606 * lossless data compression. They are implemented in highly optimized C code, 4607 * using state-of-the-art compression techniques. The main limitation is the 4608 * lack of sliding window support; this has, however, allowed the algorithms to 4609 * be optimized for block-based compression. 4610 * 4611 * @{ 4612 */ 4613 4614 /** Opaque compressor handle. */ 4615 struct wimlib_compressor; 4616 4617 /** Opaque decompressor handle. */ 4618 struct wimlib_decompressor; 4619 4620 /** 4621 * Set the default compression level for the specified compression type. This 4622 * is the compression level that wimlib_create_compressor() assumes if it is 4623 * called with @p compression_level specified as 0. 4624 * 4625 * wimlib's WIM writing code (e.g. wimlib_write()) will pass 0 to 4626 * wimlib_create_compressor() internally. Therefore, calling this function will 4627 * affect the compression level of any data later written to WIM files using the 4628 * specified compression type. 4629 * 4630 * The initial state, before this function is called, is that all compression 4631 * types have a default compression level of 50. 4632 * 4633 * @param ctype 4634 * Compression type for which to set the default compression level, as one 4635 * of the ::wimlib_compression_type constants. Or, if this is the special 4636 * value -1, the default compression levels for all compression types will 4637 * be set. 4638 * @param compression_level 4639 * The default compression level to set. If 0, the "default default" level 4640 * of 50 is restored. Otherwise, a higher value indicates higher 4641 * compression, whereas a lower value indicates lower compression. See 4642 * wimlib_create_compressor() for more information. 4643 * 4644 * @return 0 on success; a ::wimlib_error_code value on failure. 4645 * 4646 * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE 4647 * @p ctype was neither a supported compression type nor -1. 4648 */ 4649 extern int 4650 wimlib_set_default_compression_level(int ctype, unsigned int compression_level); 4651 4652 /** 4653 * Return the approximate number of bytes needed to allocate a compressor with 4654 * wimlib_create_compressor() for the specified compression type, maximum block 4655 * size, and compression level. @p compression_level may be 0, in which case 4656 * the current default compression level for @p ctype is used. Returns 0 if the 4657 * compression type is invalid, or the @p max_block_size for that compression 4658 * type is invalid. 4659 */ 4660 extern uint64_t 4661 wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype, 4662 size_t max_block_size, 4663 unsigned int compression_level); 4664 4665 #define WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE 0x80000000 4666 4667 /** 4668 * Allocate a compressor for the specified compression type using the specified 4669 * parameters. This function is part of wimlib's compression API; it is not 4670 * necessary to call this to process a WIM file. 4671 * 4672 * @param ctype 4673 * Compression type for which to create the compressor, as one of the 4674 * ::wimlib_compression_type constants. 4675 * @param max_block_size 4676 * The maximum compression block size to support. This specifies the 4677 * maximum allowed value for the @p uncompressed_size parameter of 4678 * wimlib_compress() when called using this compressor. 4679 * <br/> 4680 * Usually, the amount of memory used by the compressor will scale in 4681 * proportion to the @p max_block_size parameter. 4682 * wimlib_get_compressor_needed_memory() can be used to query the specific 4683 * amount of memory that will be required. 4684 * <br/> 4685 * This parameter must be at least 1 and must be less than or equal to a 4686 * compression-type-specific limit. 4687 * <br/> 4688 * In general, the same value of @p max_block_size must be passed to 4689 * wimlib_create_decompressor() when the data is later decompressed. 4690 * However, some compression types have looser requirements regarding this. 4691 * @param compression_level 4692 * The compression level to use. If 0, the default compression level (50, 4693 * or another value as set through wimlib_set_default_compression_level()) 4694 * is used. Otherwise, a higher value indicates higher compression. The 4695 * values are scaled so that 10 is low compression, 50 is medium 4696 * compression, and 100 is high compression. This is not a percentage; 4697 * values above 100 are also valid. 4698 * <br/> 4699 * Using a higher-than-default compression level can result in a better 4700 * compression ratio, but can significantly reduce performance. Similarly, 4701 * using a lower-than-default compression level can result in better 4702 * performance, but can significantly worsen the compression ratio. The 4703 * exact results will depend heavily on the compression type and what 4704 * algorithms are implemented for it. If you are considering using a 4705 * non-default compression level, you should run benchmarks to see if it is 4706 * worthwhile for your application. 4707 * <br/> 4708 * The compression level does not affect the format of the compressed data. 4709 * Therefore, it is a compressor-only parameter and does not need to be 4710 * passed to the decompressor. 4711 * <br/> 4712 * Since wimlib v1.8.0, this parameter can be OR-ed with the flag 4713 * ::WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE. This creates the compressor in a 4714 * mode where it is allowed to modify the input buffer. Specifically, in 4715 * this mode, if compression succeeds, the input buffer may have been 4716 * modified, whereas if compression does not succeed the input buffer still 4717 * may have been written to but will have been restored exactly to its 4718 * original state. This mode is designed to save some memory when using 4719 * large buffer sizes. 4720 * @param compressor_ret 4721 * A location into which to return the pointer to the allocated compressor. 4722 * The allocated compressor can be used for any number of calls to 4723 * wimlib_compress() before being freed with wimlib_free_compressor(). 4724 * 4725 * @return 0 on success; a ::wimlib_error_code value on failure. 4726 * 4727 * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE 4728 * @p ctype was not a supported compression type. 4729 * @retval ::WIMLIB_ERR_INVALID_PARAM 4730 * @p max_block_size was invalid for the compression type, or @p 4731 * compressor_ret was @c NULL. 4732 * @retval ::WIMLIB_ERR_NOMEM 4733 * Insufficient memory to allocate the compressor. 4734 */ 4735 extern int 4736 wimlib_create_compressor(enum wimlib_compression_type ctype, 4737 size_t max_block_size, 4738 unsigned int compression_level, 4739 struct wimlib_compressor **compressor_ret); 4740 4741 /** 4742 * Compress a buffer of data. 4743 * 4744 * @param uncompressed_data 4745 * Buffer containing the data to compress. 4746 * @param uncompressed_size 4747 * Size, in bytes, of the data to compress. This cannot be greater than 4748 * the @p max_block_size with which wimlib_create_compressor() was called. 4749 * (If it is, the data will not be compressed and 0 will be returned.) 4750 * @param compressed_data 4751 * Buffer into which to write the compressed data. 4752 * @param compressed_size_avail 4753 * Number of bytes available in @p compressed_data. 4754 * @param compressor 4755 * A compressor previously allocated with wimlib_create_compressor(). 4756 * 4757 * @return 4758 * The size of the compressed data, in bytes, or 0 if the data could not be 4759 * compressed to @p compressed_size_avail or fewer bytes. 4760 */ 4761 extern size_t 4762 wimlib_compress(const void *uncompressed_data, size_t uncompressed_size, 4763 void *compressed_data, size_t compressed_size_avail, 4764 struct wimlib_compressor *compressor); 4765 4766 /** 4767 * Free a compressor previously allocated with wimlib_create_compressor(). 4768 * 4769 * @param compressor 4770 * The compressor to free. If @c NULL, no action is taken. 4771 */ 4772 extern void 4773 wimlib_free_compressor(struct wimlib_compressor *compressor); 4774 4775 /** 4776 * Allocate a decompressor for the specified compression type. This function is 4777 * part of wimlib's compression API; it is not necessary to call this to process 4778 * a WIM file. 4779 * 4780 * @param ctype 4781 * Compression type for which to create the decompressor, as one of the 4782 * ::wimlib_compression_type constants. 4783 * @param max_block_size 4784 * The maximum compression block size to support. This specifies the 4785 * maximum allowed value for the @p uncompressed_size parameter of 4786 * wimlib_decompress(). 4787 * <br/> 4788 * In general, this parameter must be the same as the @p max_block_size 4789 * that was passed to wimlib_create_compressor() when the data was 4790 * compressed. However, some compression types have looser requirements 4791 * regarding this. 4792 * @param decompressor_ret 4793 * A location into which to return the pointer to the allocated 4794 * decompressor. The allocated decompressor can be used for any number of 4795 * calls to wimlib_decompress() before being freed with 4796 * wimlib_free_decompressor(). 4797 * 4798 * @return 0 on success; a ::wimlib_error_code value on failure. 4799 * 4800 * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE 4801 * @p ctype was not a supported compression type. 4802 * @retval ::WIMLIB_ERR_INVALID_PARAM 4803 * @p max_block_size was invalid for the compression type, or @p 4804 * decompressor_ret was @c NULL. 4805 * @retval ::WIMLIB_ERR_NOMEM 4806 * Insufficient memory to allocate the decompressor. 4807 */ 4808 extern int 4809 wimlib_create_decompressor(enum wimlib_compression_type ctype, 4810 size_t max_block_size, 4811 struct wimlib_decompressor **decompressor_ret); 4812 4813 /** 4814 * Decompress a buffer of data. 4815 * 4816 * @param compressed_data 4817 * Buffer containing the data to decompress. 4818 * @param compressed_size 4819 * Size, in bytes, of the data to decompress. 4820 * @param uncompressed_data 4821 * Buffer into which to write the uncompressed data. 4822 * @param uncompressed_size 4823 * Size, in bytes, of the data when uncompressed. This cannot exceed the 4824 * @p max_block_size with which wimlib_create_decompressor() was called. 4825 * (If it does, the data will not be decompressed and a nonzero value will 4826 * be returned.) 4827 * @param decompressor 4828 * A decompressor previously allocated with wimlib_create_decompressor(). 4829 * 4830 * @return 0 on success; nonzero on failure. 4831 * 4832 * No specific error codes are defined; any nonzero value indicates that the 4833 * decompression failed. This can only occur if the data is truly invalid; 4834 * there will never be transient errors like "out of memory", for example. 4835 * 4836 * This function requires that the exact uncompressed size of the data be passed 4837 * as the @p uncompressed_size parameter. If this is not done correctly, 4838 * decompression may fail or the data may be decompressed incorrectly. 4839 */ 4840 extern int 4841 wimlib_decompress(const void *compressed_data, size_t compressed_size, 4842 void *uncompressed_data, size_t uncompressed_size, 4843 struct wimlib_decompressor *decompressor); 4844 4845 /** 4846 * Free a decompressor previously allocated with wimlib_create_decompressor(). 4847 * 4848 * @param decompressor 4849 * The decompressor to free. If @c NULL, no action is taken. 4850 */ 4851 extern void 4852 wimlib_free_decompressor(struct wimlib_decompressor *decompressor); 4853 4854 4855 /** 4856 * @} 4857 */ 4858 4859 4860 #ifdef __cplusplus 4861 } 4862 #endif 4863 4864 #endif /* _WIMLIB_H */ 4865