|
wimlib
|
Macros | |
| #define | WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001 |
| For wimlib_reference_resource_files(), enable shell-style filename globbing. | |
| #define | WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002 |
| For wimlib_reference_resource_files(), issue an error (WIMLIB_ERR_GLOB_HAD_NO_MATCHES) if a glob did not match any files. | |
Functions | |
| WIMLIBAPI int | wimlib_join (const wimlib_tchar *const *swms, unsigned num_swms, const wimlib_tchar *output_path, int swm_open_flags, int wim_write_flags) |
| Join a split WIM into a stand-alone (one-part) WIM. | |
| WIMLIBAPI int | wimlib_join_with_progress (const wimlib_tchar *const *swms, unsigned num_swms, const wimlib_tchar *output_path, int swm_open_flags, int wim_write_flags, wimlib_progress_func_t progfunc, void *progctx) |
| Same as wimlib_join(), but allows specifying a progress function. | |
| WIMLIBAPI int | wimlib_reference_resource_files (WIMStruct *wim, const wimlib_tchar *const *resource_wimfiles_or_globs, unsigned count, int ref_flags, int open_flags) |
| Reference file data from other WIM files or split WIM parts. | |
| WIMLIBAPI int | wimlib_reference_resources (WIMStruct *wim, WIMStruct **resource_wims, unsigned num_resource_wims, int ref_flags) |
| Similar to wimlib_reference_resource_files(), but operates at a lower level where the caller must open the WIMStruct for each referenced file itself. | |
| WIMLIBAPI int | wimlib_split (WIMStruct *wim, const wimlib_tchar *swm_name, uint64_t part_size, int write_flags) |
| Split a WIM into multiple parts. | |
Create and handle non-standalone WIMs, such as split and delta WIMs.
A WIMStruct backed by an on-disk file normally represents a fully standalone WIM archive. However, WIM archives can also be arranged in non-standalone ways, such as a set of on-disk files that together form a single "split WIM" or "delta WIM". Such arrangements are fully supported by wimlib. However, as a result, in such cases a WIMStruct created from one of these on-disk files initially only partially represents the full WIM and needs to, in effect, be logically combined with other WIMStruct's before performing certain operations, such as extracting files with wimlib_extract_image() or wimlib_extract_paths(). This is done by calling wimlib_reference_resource_files() or wimlib_reference_resources(). Note: if you fail to do so, you may see the error code WIMLIB_ERR_RESOURCE_NOT_FOUND; this just indicates that data is not available because the appropriate WIM files have not yet been referenced.
wimlib_write() can create delta WIMs as well as standalone WIMs, but a specialized function (wimlib_split()) is needed to create a split WIM.
| #define WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001 |
For wimlib_reference_resource_files(), enable shell-style filename globbing.
Ignored by wimlib_reference_resources().
| #define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002 |
For wimlib_reference_resource_files(), issue an error (WIMLIB_ERR_GLOB_HAD_NO_MATCHES) if a glob did not match any files.
The default behavior without this flag is to issue no error at that point, but then attempt to open the glob as a literal path, which of course will fail anyway if no file exists at that path. No effect if WIMLIB_REF_FLAG_GLOB_ENABLE is not also specified. Ignored by wimlib_reference_resources().
| WIMLIBAPI int wimlib_join | ( | const wimlib_tchar *const * | swms, |
| unsigned | num_swms, | ||
| const wimlib_tchar * | output_path, | ||
| int | swm_open_flags, | ||
| int | wim_write_flags ) |
Join a split WIM into a stand-alone (one-part) WIM.
| swms | An array of strings that gives the filenames of all parts of the split WIM. No specific order is required, but all parts must be included with no duplicates. |
| num_swms | Number of filenames in swms. |
| swm_open_flags | Open flags for the split WIM parts (e.g. WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). |
| wim_write_flags | Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will be used to write the joined WIM. |
| output_path | The path to write the joined WIM file to. |
| WIMLIB_ERR_SPLIT_INVALID | The split WIMs do not form a valid WIM because they do not include all the parts of the original WIM, there are duplicate parts, or not all the parts have the same GUID and compression type. |
Note: wimlib is generalized enough that this function is not actually needed to join a split WIM; instead, you could open the first part of the split WIM, then reference the other parts with wimlib_reference_resource_files(), then write the joined WIM using wimlib_write(). However, wimlib_join() provides an easy-to-use wrapper around this that has some advantages (e.g. extra sanity checks).
| WIMLIBAPI int wimlib_join_with_progress | ( | const wimlib_tchar *const * | swms, |
| unsigned | num_swms, | ||
| const wimlib_tchar * | output_path, | ||
| int | swm_open_flags, | ||
| int | wim_write_flags, | ||
| wimlib_progress_func_t | progfunc, | ||
| void * | progctx ) |
Same as wimlib_join(), but allows specifying a progress function.
The progress function will receive the write progress messages, such as WIMLIB_PROGRESS_MSG_WRITE_STREAMS, while writing the joined WIM. In addition, if WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in swm_open_flags, the progress function will receive a series of WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY messages when each of the split WIM parts is opened.
| WIMLIBAPI int wimlib_reference_resource_files | ( | WIMStruct * | wim, |
| const wimlib_tchar *const * | resource_wimfiles_or_globs, | ||
| unsigned | count, | ||
| int | ref_flags, | ||
| int | open_flags ) |
Reference file data from other WIM files or split WIM parts.
This function can be used on WIMs that are not standalone, such as split or "delta" WIMs, to load additional file data before calling a function such as wimlib_extract_image() that requires the file data to be present.
| wim | The WIMStruct for a WIM that contains metadata resources, but is not necessarily "standalone". In the case of split WIMs, this should be the first part, since only the first part contains the metadata resources. In the case of delta WIMs, this should be the delta WIM rather than the WIM on which it is based. |
| resource_wimfiles_or_globs | Array of paths to WIM files and/or split WIM parts to reference. Alternatively, when WIMLIB_REF_FLAG_GLOB_ENABLE is specified in ref_flags, these are treated as globs rather than literal paths. That is, using this function you can specify zero or more globs, each of which expands to one or more literal paths. |
| count | Number of entries in resource_wimfiles_or_globs. |
| ref_flags | Bitwise OR of WIMLIB_REF_FLAG_GLOB_ENABLE and/or WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH. |
| open_flags | Additional open flags, such as WIMLIB_OPEN_FLAG_CHECK_INTEGRITY, to pass to internal calls to wimlib_open_wim() on the reference files. |
| WIMLIB_ERR_GLOB_HAD_NO_MATCHES | One of the specified globs did not match any paths (only with both WIMLIB_REF_FLAG_GLOB_ENABLE and WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH specified in ref_flags). |
| WIMLIB_ERR_READ | I/O or permissions error while processing a file glob. |
This function can additionally return most values that can be returned by wimlib_open_wim().
| WIMLIBAPI int wimlib_reference_resources | ( | WIMStruct * | wim, |
| WIMStruct ** | resource_wims, | ||
| unsigned | num_resource_wims, | ||
| int | ref_flags ) |
Similar to wimlib_reference_resource_files(), but operates at a lower level where the caller must open the WIMStruct for each referenced file itself.
| wim | The WIMStruct for a WIM that contains metadata resources, but is not necessarily "standalone". In the case of split WIMs, this should be the first part, since only the first part contains the metadata resources. |
| resource_wims | Array of pointers to the WIMStruct's for additional resource WIMs or split WIM parts to reference. |
| num_resource_wims | Number of entries in resource_wims. |
| ref_flags | Reserved; must be 0. |
| WIMLIBAPI int wimlib_split | ( | WIMStruct * | wim, |
| const wimlib_tchar * | swm_name, | ||
| uint64_t | part_size, | ||
| int | write_flags ) |
Split a WIM into multiple parts.
| wim | The WIMStruct for the WIM to split. |
| swm_name | Name of the split WIM (SWM) file to create. This will be the name of the first part. The other parts will, by default, have the same name with 2, 3, 4, ..., etc. appended before the suffix. However, the exact names can be customized using the progress function. |
| part_size | The maximum size per part, in bytes. Unfortunately, it is not guaranteed that this will really be the maximum size per part, because some file resources in the WIM may be larger than this size, and the WIM file format provides no way to split up file resources among multiple WIMs. |
| write_flags | Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. These flags will be used to write each split WIM part. Specify 0 here to get the default behavior. |
| WIMLIB_ERR_INVALID_PARAM | swm_name was not a nonempty string, or part_size was 0. |
| WIMLIB_ERR_UNSUPPORTED | The WIM contains solid resources. Splitting a WIM containing solid resources is not supported. |
If a progress function is registered with wim, then for each split WIM part that is written it will receive the messages WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and WIMLIB_PROGRESS_MSG_SPLIT_END_PART. Since wimlib v1.13.4 it will also receive WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages while writing each part; these messages will report the progress of the current part only.
1.10.0