* @brief External header for wimlib.
*
* This file contains comments for generating documentation with Doxygen. The
- * built HTML documentation can be viewed at http://wimlib.sourceforge.net.
- * Make sure to see the <a href="modules.html">Modules page</a> to make more
- * sense of the declarations in this header.
+ * built HTML documentation can be viewed at https://wimlib.net/apidoc. Make
+ * sure to see the <a href="modules.html">Modules page</a> to make more sense of
+ * the declarations in this header.
*/
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.8.0, a C
+ * This is the documentation for the library interface of wimlib 1.8.3, a C
* library for creating, modifying, extracting, and mounting files in the
* Windows Imaging Format. This documentation is intended for developers only.
* If you have installed wimlib and want to know how to use the @b wimlib-imagex
* program, please see the manual pages and also the <a
- * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/README">README
+ * href="https://wimlib.net/gitlist/wimlib/blob/master/README">README
* file</a>.
*
* @section sec_installing Installing
*
* @subsection UNIX
*
- * Download the source code from <a
- * href="http://sourceforge.net/projects/wimlib/files">http://sourceforge.net/projects/wimlib/files</a>.
- * Install the library by running <c>configure && make && sudo make install</c>.
- * See the README for information about configuration options. To use wimlib in
- * your program after installing it, include wimlib.h and link your program with
- * <c>-lwim</c>.
+ * Download the source code from https://wimlib.net. Install the library by
+ * running <c>configure && make && sudo make install</c>. See the README for
+ * information about configuration options. To use wimlib in your program after
+ * installing it, include wimlib.h and link your program with <c>-lwim</c>.
*
* @subsection Windows
*
* Download the Windows binary distribution with the appropriate architecture
- * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from <a
- * href="http://sourceforge.net/projects/wimlib/files">http://sourceforge.net/projects/wimlib/files</a>.
- * Link your program with the libwim-15.dll file. Make sure to also download
- * the source code so you can get wimlib.h, as it is not included in the binary
- * distribution. If you need to access the DLL from other programming
- * languages, note that the calling convention is "cdecl".
+ * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from
+ * https://wimlib.net. Link your program with the libwim-15.dll file. Make
+ * sure to also download the source code so you can get wimlib.h, as it is not
+ * included in the binary distribution. If you need to access the DLL from
+ * other programming languages, note that the calling convention is "cdecl".
*
* @section sec_examples Examples
*
- * Several examples are located in the <a
- * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/examples">examples</a>
- * directory of the source distribution.
+ * Several examples are located in the "examples" directory of the source
+ * distribution.
*
* There is also the <a
- * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/programs/imagex.c">
+ * href="https://wimlib.net/gitlist/wimlib/blob/master/programs/imagex.c">
* source code of <b>wimlib-imagex</b></a>, which is complicated but uses most
* capabilities of wimlib.
*
*
* wimlib_update_image() can add, delete, and rename files in a WIM image.
*
- * wimlib_set_image_name(), wimlib_set_image_descripton(), and
- * wimlib_set_image_flags() can change other image metadata.
+ * wimlib_set_image_name(), wimlib_set_image_descripton(),
+ * wimlib_set_image_flags(), and wimlib_set_image_property() can change other
+ * image metadata.
*
* wimlib_set_wim_info() can change information about the WIM file itself, such
* as the boot index.
#define WIMLIB_MINOR_VERSION 8
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 3
#ifdef __cplusplus
extern "C" {
* produce a better compression ratio, and work more quickly, than the
* implementation in Microsoft's WIMGAPI (as of Windows 8.1). There is
* limited support for non-default compression levels, but compression
- * will be noticably faster if you choose a level < 35.
+ * will be noticeably faster if you choose a level < 35.
*
* If using wimlib_create_compressor() to create an LZMS compressor
* directly, the @p max_block_size parameter may be any positive value
uint64_t completed_streams;
/** The number of threads being used for data compression; or,
- * if no compression is being peformed, this will be 1. */
+ * if no compression is being performed, this will be 1. */
uint32_t num_threads;
/** The compression type being used, as one of the
uint64_t num_dirs_scanned;
/** The number of non-directories scanned so far, not counting
- * excluded/unsupported files. If a file has multiple names
- * (hard links), it is only counted one time. */
+ * excluded/unsupported files. */
uint64_t num_nondirs_scanned;
/** The number of bytes of file data detected so far, not
- * counting excluded/unsupported files. If a file has multiple
- * names (hard links), its data is counted only one time. */
+ * counting excluded/unsupported files. */
uint64_t num_bytes_scanned;
} scan;
* integrity checks. */
uint64_t total_bytes;
- /** The number of bytes that have been processed so far. This
+ /** The number of bytes that have been checksummed so far. This
* starts at 0 and ends at @p total_bytes. */
uint64_t completed_bytes;
* integrity-checked region is divided into. */
uint32_t total_chunks;
- /** The number of chunks that have been processed so far. This
- * starts at 0 and ends at @p total_chunks. */
+ /** The number of chunks that have been checksummed so far.
+ * This starts at 0 and ends at @p total_chunks. */
uint32_t completed_chunks;
/** The size of each individually checksummed "chunk" in the
*/
uint32_t opened_from_file : 1;
- /** 1 iff this WIM file is considered readonly for any reason. */
+ /** 1 iff this WIM file is considered readonly for any reason (e.g. the
+ * "readonly" header flag is set, or this is part of a split WIM, or
+ * filesystem permissions deny writing) */
uint32_t is_readonly : 1;
- /** 1 iff reparse-point fixups are enabled for one or more images in
- * this WIM file. */
+ /** 1 iff the "reparse point fix" flag is set in this WIM's header */
uint32_t has_rpfix : 1;
- /** 1 iff this WIM file is marked read-only in its header. */
+ /** 1 iff the "readonly" flag is set in this WIM's header */
uint32_t is_marked_readonly : 1;
- /** 1 iff this WIM file is part of a spanned set. */
+ /** 1 iff the "spanned" flag is set in this WIM's header */
uint32_t spanned : 1;
+ /** 1 iff the "write in progress" flag is set in this WIM's header */
uint32_t write_in_progress : 1;
+
+ /** 1 iff the "metadata only" flag is set in this WIM's header */
uint32_t metadata_only : 1;
+
+ /** 1 iff the "resource only" flag is set in this WIM's header */
uint32_t resource_only : 1;
/** 1 iff this WIM file is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */
*
* Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and
* independent from, ::WIMLIB_ADD_FLAG_BOOT.
+ *
+ * Since wimlib v1.8.3, ::WIMLIB_ADD_FLAG_WIMBOOT also causes offline WIM-backed
+ * files to be added as the "real" files rather than as their reparse points,
+ * provided that their data is already present in the WIM. This feature can be
+ * useful when updating a backing WIM file in an "offline" state.
*/
#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
*/
#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000
-/* Note: the WIMLIB_ADD_IMAGE_FLAG names are retained for source compatibility.
- * Use the WIMLIB_ADD_FLAG names in new code. */
-#define WIMLIB_ADD_IMAGE_FLAG_NTFS WIMLIB_ADD_FLAG_NTFS
-#define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE WIMLIB_ADD_FLAG_DEREFERENCE
-#define WIMLIB_ADD_IMAGE_FLAG_VERBOSE WIMLIB_ADD_FLAG_VERBOSE
-#define WIMLIB_ADD_IMAGE_FLAG_BOOT WIMLIB_ADD_FLAG_BOOT
-#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA WIMLIB_ADD_FLAG_UNIX_DATA
-#define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS WIMLIB_ADD_FLAG_NO_ACLS
-#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS WIMLIB_ADD_FLAG_STRICT_ACLS
-#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE
-#define WIMLIB_ADD_IMAGE_FLAG_RPFIX WIMLIB_ADD_FLAG_RPFIX
-#define WIMLIB_ADD_IMAGE_FLAG_NORPFIX WIMLIB_ADD_FLAG_NORPFIX
-#define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \
- WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE
-#define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG
-#define WIMLIB_ADD_IMAGE_FLAG_WIMBOOT WIMLIB_ADD_FLAG_WIMBOOT
-
+/**
+ * EXPERIMENTAL, since wimlib v1.9.0: create a temporary filesystem snapshot of
+ * the source directory and add the files from it. Currently, this option is
+ * only supported on Windows, where it uses the Volume Shadow Copy Service
+ * (VSS). Using this option, you can create a consistent backup of the system
+ * volume of a running Windows system without running into problems with locked
+ * files. For the VSS snapshot to be successfully created, your application
+ * must be run as an Administrator, and it cannot be run in WoW64 mode (i.e. if
+ * Windows is 64-bit, then your application must be 64-bit as well).
+ */
+#define WIMLIB_ADD_FLAG_SNAPSHOT 0x00008000
/** @} */
/** @addtogroup G_modifying_wims
* only allows the Administrator to create symbolic links. */
#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000
-/** Reserved for future use. */
-#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000
-
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the
* paths to extract as wildcard patterns ("globs") which may contain the
* wildcard characters @c ? and @c *. The @c ? character matches any
*/
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
+/**
+ * Since wimlib v1.8.2 and Windows-only: compress the extracted files using
+ * System Compression, when possible. This only works on either Windows 10 or
+ * later, or on an older Windows to which Microsoft's wofadk.sys driver has been
+ * added. Several different compression formats may be used with System
+ * Compression; this particular flag selects the XPRESS compression format with
+ * 4096 byte chunks.
+ */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000
+
+/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
+ * 8192 byte chunks. */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000
+
+/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
+ * 16384 byte chunks. */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000
+
+/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with
+ * 32768 byte chunks. */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000
+
/** @} */
/** @addtogroup G_mounting_wim_images
* @{ */
#define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000
/**
- * Do not consider content similarily when arranging file data for solid
+ * Do not consider content similarity when arranging file data for solid
* compression. Providing this flag will typically worsen the compression
* ratio, so only provide this flag if you know what you are doing.
*/
#define WIMLIB_WRITE_FLAG_NO_SOLID_SORT 0x00004000
+/**
+ * Since wimlib v1.8.3 and for wimlib_overwrite() only: <b>unsafely</b> compact
+ * the WIM file in-place, without appending. Existing resources are shifted
+ * down to fill holes and new resources are appended as needed. The WIM file is
+ * truncated to its final size, which may shrink the on-disk file. <b>This
+ * operation cannot be safely interrupted. If the operation is interrupted,
+ * then the WIM file will be corrupted, and it may be impossible (or at least
+ * very difficult) to recover any data from it. Users of this flag are expected
+ * to know what they are doing and assume responsibility for any data corruption
+ * that may result.</b>
+ *
+ * If the WIM file cannot be compacted in-place because of its structure, its
+ * layout, or other requested write parameters, then wimlib_overwrite() fails
+ * with ::WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry
+ * the operation without this flag.
+ */
+#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT 0x00008000
+
/** @} */
/** @addtogroup G_general
* @{ */
#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
/** Windows-only: do not attempt to acquire additional privileges (currently
- * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and
- * SeTakeOwnershipPrivilege) when initializing the library. This flag is
- * intended for the case where the calling program manages these privileges
- * itself. Note: by default, no error is issued if privileges cannot be
- * acquired, although related errors may be reported later, depending on if the
- * operations performed actually require additional privileges or not. */
+ * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege,
+ * SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the
+ * library. This flag is intended for the case where the calling program
+ * manages these privileges itself. Note: by default, no error is issued if
+ * privileges cannot be acquired, although related errors may be reported later,
+ * depending on if the operations performed actually require additional
+ * privileges or not. */
#define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002
/** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified,
WIMLIB_ERR_INVALID_UTF8_STRING = 31,
WIMLIB_ERR_IS_DIRECTORY = 32,
WIMLIB_ERR_IS_SPLIT_WIM = 33,
- WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE = 34,
WIMLIB_ERR_LINK = 35,
WIMLIB_ERR_METADATA_NOT_FOUND = 36,
WIMLIB_ERR_MKDIR = 37,
WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79,
WIMLIB_ERR_NOT_A_MOUNTPOINT = 80,
WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81,
- WIMLIB_ERR_FVE_LOCKED_VOLUME = 82,
+ WIMLIB_ERR_FVE_LOCKED_VOLUME = 82,
+ WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83,
+ WIMLIB_ERR_WIM_IS_INCOMPLETE = 84,
+ WIMLIB_ERR_COMPACTION_NOT_POSSIBLE = 85,
+ WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86,
+ WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87,
+ WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88,
+ WIMLIB_ERR_SNAPSHOT_FAILURE = 89,
};
* capture</b> for full details on how this mode works.
*
* In addition to the error codes that wimlib_add_image() can return,
- * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY
- * when trying to overlay a non-directory on a directory or when otherwise
- * trying to overlay multiple conflicting files to the same location in the WIM
- * image. It will also return ::WIMLIB_ERR_INVALID_PARAM if
- * ::WIMLIB_ADD_FLAG_NTFS was specified in @p add_flags but there
- * was not exactly one capture source with the target being the root directory.
- * (In this respect, there is no advantage to using
- * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting
- * NTFS mode.)
+ * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY when
+ * trying to overlay a non-directory on a directory or when otherwise trying to
+ * overlay multiple conflicting files to the same location in the WIM image.
*/
extern int
wimlib_add_image_multisource(WIMStruct *wim,
* an on-disk file.
*
* @param ctype
- * The "output compression type" to assign to the ::WIMStruct, given as one
- * of the ::wimlib_compression_type values. This is the compression type
- * that will be used if the ::WIMStruct is later persisted to an on-disk
- * file using wimlib_write().
+ * The "output compression type" to assign to the ::WIMStruct. This is the
+ * compression type that will be used if the ::WIMStruct is later persisted
+ * to an on-disk file using wimlib_write().
* <br/>
* This choice is not necessarily final. If desired, it can still be
* changed at any time before wimlib_write() is called, using
* Insufficient memory to allocate a new ::WIMStruct.
*/
extern int
-wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
+wimlib_create_new_wim(enum wimlib_compression_type ctype, WIMStruct **wim_ret);
/**
* @ingroup G_modifying_wims
*
* Export an image, or all images, from a ::WIMStruct into another ::WIMStruct.
*
- * Note: after calling this function, the exported WIM image(s) cannot be
- * independently modified because the image metadata will be shared between the
- * two ::WIMStruct's. In addition, @p dest_wim will depend on @p src_wim, so @p
- * src_wim cannot be freed until @p dest_wim is ready to be freed as well.
+ * Specifically, if the destination ::WIMStruct contains <tt>n</tt> images, then
+ * the source image(s) will be appended, in order, starting at destination index
+ * <tt>n + 1</tt>. By default, all image metadata will be exported verbatim,
+ * but certain changes can be made by passing appropriate parameters.
*
- * Note: no changes are committed to disk until wimlib_write() or
- * wimlib_overwrite() is called.
+ * wimlib_export_image() is only an in-memory operation; no changes are
+ * committed to disk until wimlib_write() or wimlib_overwrite() is called.
+ *
+ * A limitation of the current implementation of wimlib_export_image() is that
+ * the directory tree of a source or destination image cannot be updated
+ * following an export until one of the two images has been freed from memory.
*
* @param src_wim
* The WIM from which to export the images, specified as a pointer to the
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
+ * @retval ::WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE
+ * One or more of the source images had already been exported into the
+ * destination WIM.
* @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
* One or more of the names being given to an exported image was already in
* use in the destination WIM.
* ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags.
* @retval ::WIMLIB_ERR_WIMBOOT
* ::WIMLIB_EXTRACT_FLAG_WIMBOOT was specified in @p extract_flags, but
- * there was a problem creating WIMBoot pointer files.
+ * there was a problem creating WIMBoot pointer files or registering a
+ * source WIM file with the Windows Overlay Filesystem (WOF) driver.
* @retval ::WIMLIB_ERR_WRITE
* Failed to write data to a file being extracted.
*
/**
* @ingroup G_general
*
- * Free all memory allocated for a WIMStruct and close all files associated with
- * it.
+ * Release a reference to a ::WIMStruct. If the ::WIMStruct is still referenced
+ * by other ::WIMStruct's (e.g. following calls to wimlib_export_image() or
+ * wimlib_reference_resources()), then the library will free it later, when the
+ * last reference is released; otherwise it is freed immediately and any
+ * associated file descriptors are closed.
*
* @param wim
- * Pointer to the ::WIMStruct to free. If @c NULL, no action is taken.
+ * Pointer to the ::WIMStruct to release. If @c NULL, no action is taken.
*/
extern void
wimlib_free(WIMStruct *wim);
* Convert a ::wimlib_compression_type value into a string.
*
* @param ctype
- * The ::wimlib_compression_type value to convert.
+ * The compression type value to convert.
*
* @return
* A statically allocated string naming the compression type, such as
* the resulting string will be "Invalid".
*/
extern const wimlib_tchar *
-wimlib_get_compression_type_string(int ctype);
+wimlib_get_compression_type_string(enum wimlib_compression_type ctype);
/**
* @ingroup G_general
/**
* @ingroup G_wim_information
*
- * Get the description of the specified image.
- *
- * @param wim
- * Pointer to the ::WIMStruct to query. This need not represent a
- * standalone WIM (e.g. it could represent part of a split WIM).
- * @param image
- * The 1-based index of the image for which to query the description.
- *
- * @return
- * The description of the image, or @c NULL if there is no such image, or
- * @c NULL if the specified image has no description. The string may not
- * remain valid after later library calls, so the caller should duplicate
- * it if needed.
+ * Get the description of the specified image. Equivalent to
+ * <tt>wimlib_get_image_property(wim, image, "DESCRIPTION")</tt>.
*/
extern const wimlib_tchar *
wimlib_get_image_description(const WIMStruct *wim, int image);
/**
* @ingroup G_wim_information
*
- * Get the name of the specified image.
+ * Get the name of the specified image. Equivalent to
+ * <tt>wimlib_get_image_property(wim, image, "NAME")</tt>, except that
+ * wimlib_get_image_name() will return an empty string if the image is unnamed
+ * whereas wimlib_get_image_property() may return @c NULL in that case.
+ */
+extern const wimlib_tchar *
+wimlib_get_image_name(const WIMStruct *wim, int image);
+
+/**
+ * @ingroup G_wim_information
+ *
+ * Since wimlib v1.8.3: get a per-image property from the WIM's XML document.
+ * This is an alternative to wimlib_get_image_name() and
+ * wimlib_get_image_description() which allows getting any simple string
+ * property.
*
* @param wim
- * Pointer to the ::WIMStruct to query. This need not represent a
- * standalone WIM (e.g. it could represent part of a split WIM).
+ * Pointer to the ::WIMStruct for the WIM.
* @param image
- * The 1-based index of the image for which to query the name.
+ * The 1-based index of the image for which to get the property.
+ * @param property_name
+ * The name of the image property, for example "NAME", "DESCRIPTION", or
+ * "TOTALBYTES". The name can contain forward slashes to indicate a nested
+ * XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD
+ * element nested within the VERSION element nested within the WINDOWS
+ * element. Since wimlib v1.9.0, a bracketed number can be used to
+ * indicate one of several identically-named elements; for example,
+ * "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element
+ * nested within the "WINDOWS/LANGUAGES" element. Note that element names
+ * are case sensitive.
*
* @return
- * The name of the image, or @c NULL if there is no such image, or an empty
- * string if the image is unnamed. The string may not remain valid after
- * later library calls, so the caller should duplicate it if needed.
+ * The property's value as a ::wimlib_tchar string, or @c NULL if there is
+ * no such property. The string may not remain valid after later library
+ * calls, so the caller should duplicate it if needed.
*/
extern const wimlib_tchar *
-wimlib_get_image_name(const WIMStruct *wim, int image);
+wimlib_get_image_property(const WIMStruct *wim, int image,
+ const wimlib_tchar *property_name);
/**
* @ingroup G_general
* Another process is currently modifying the WIM file.
* @retval ::WIMLIB_ERR_FUSE
* A non-zero status code was returned by @c fuse_main().
+ * @retval ::WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES
+ * There are currently multiple references to the WIM image as a result of
+ * a call to wimlib_export_image(). Free one before attempting the
+ * read-write mount.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not exist in @p wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED
* The WIM cannot be opened because it contains encrypted segments. (It
* may be a Windows 8 "ESD" file.)
+ * @retval ::WIMLIB_ERR_WIM_IS_INCOMPLETE
+ * The WIM file is not complete (e.g. the program which wrote it was
+ * terminated before it finished)
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
* considered read-only because of any of the reasons mentioned in the
/**
* @ingroup G_writing_and_overwriting_wims
*
- * Commit a ::WIMStruct to disk, overwriting its backing file or appending to it
- * as needed.
+ * Commit a ::WIMStruct to disk, updating its backing file.
*
- * There are two alternative ways in which changes may be committed:
+ * There are several alternative ways in which changes may be committed:
*
* 1. Full rebuild: write the updated WIM to a temporary file, then rename the
* temporary file to the original.
* 2. Appending: append updates to the new original WIM file, then overwrite
* its header such that those changes become visible to new readers.
- *
- * Append mode is often much faster, but it wastes some amount of space due to
- * leaving "holes" in the WIM file. Because of the greater efficiency,
- * wimlib_overwrite() normally defaults to append mode. However,
- * ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild.
- * In addition, if wimlib_delete_image() has been used on the ::WIMStruct, then
- * the default mode switches to rebuild mode, and
+ * 3. Compaction: normally should not be used; see
+ * ::WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details.
+ *
+ * Append mode is often much faster than a full rebuild, but it wastes some
+ * amount of space due to leaving "holes" in the WIM file. Because of the
+ * greater efficiency, wimlib_overwrite() normally defaults to append mode.
+ * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full
+ * rebuild. In addition, if wimlib_delete_image() has been used on the
+ * ::WIMStruct, then the default mode switches to rebuild mode, and
* ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append
* mode.
*
* @param ref_flags
* Reserved; must be 0.
*
- * @return 0 on success; a ::wimlib_error_code value on failure. On success,
- * the ::WIMStruct's of the @p resource_wims are referenced internally by @p wim
- * and must not be freed with wimlib_free() or overwritten with
- * wimlib_overwrite() until @p wim has been freed with wimlib_free(), or
- * immediately before freeing @p wim with wimlib_free().
+ * @return 0 on success; a ::wimlib_error_code value on failure.
*/
extern int
wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims,
/**
* @ingroup G_modifying_wims
*
- * Change the description of a WIM image.
- *
- * @param wim
- * Pointer to the ::WIMStruct for the WIM.
- * @param image
- * The 1-based index of the image for which to change the description.
- * @param description
- * The new description to give the image. It may be @c NULL, which
- * indicates that the image is to be given no description.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image does not exist in @p wim.
+ * Change the description of a WIM image. Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "DESCRIPTION", description)</tt>.
*/
extern int
wimlib_set_image_descripton(WIMStruct *wim, int image,
* @ingroup G_modifying_wims
*
* Change what is stored in the \<FLAGS\> element in the WIM XML document
- * (usually something like "Core" or "Ultimate")
- *
- * @param wim
- * Pointer to the ::WIMStruct for the WIM.
- * @param image
- * The 1-based index of the image for which to change the flags.
- * @param flags
- * The new \<FLAGS\> element to give the image. It may be @c NULL, which
- * indicates that the image is to be given no \<FLAGS\> element.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image does not exist in @p wim.
+ * (usually something like "Core" or "Ultimate"). Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "FLAGS", flags)</tt>.
*/
extern int
wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
/**
* @ingroup G_modifying_wims
*
- * Change the name of a WIM image.
+ * Change the name of a WIM image. Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "NAME", name)</tt>.
+ */
+extern int
+wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
+
+/**
+ * @ingroup G_modifying_wims
+ *
+ * Since wimlib v1.8.3: add, modify, or remove a per-image property from the
+ * WIM's XML document. This is an alternative to wimlib_set_image_name(),
+ * wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows
+ * manipulating any simple string property.
*
* @param wim
- * Pointer to the ::WIMStruct for the WIM.
+ * Pointer to the ::WIMStruct for the WIM.
* @param image
- * The 1-based index of the image for which to change the name.
- * @param name
- * New name to give the new image. If @c NULL or empty, the new image is
- * given no name. Otherwise, it must specify a name that does not already
- * exist in @p wim.
+ * The 1-based index of the image for which to set the property.
+ * @param property_name
+ * The name of the image property in the same format documented for
+ * wimlib_get_image_property().
+ * <br/>
+ * Note: if creating a new element using a bracketed index such as
+ * "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified
+ * is one greater than the number of existing elements with that same name,
+ * excluding the index. That means that if you are adding a list of new
+ * elements, they must be added sequentially from the first index (1) to
+ * the last index (n).
+ * @param property_value
+ * If not NULL and not empty, the property is set to this value.
+ * Otherwise, the property is removed from the XML document.
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
* @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
- * The WIM already contains an image with the requested name.
+ * The user requested to set the image name (the <tt>NAME</tt> property),
+ * but another image in the WIM already had the requested name.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image does not exist in @p wim.
+ * @p image does not exist in @p wim.
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p property_name has an unsupported format, or @p property_name included
+ * a bracketed index that was too high.
*/
extern int
-wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
+wimlib_set_image_property(WIMStruct *wim, int image,
+ const wimlib_tchar *property_name,
+ const wimlib_tchar *property_value);
/**
* @ingroup G_general
* @param wim
* The ::WIMStruct for which to set the output compression type.
* @param ctype
- * The compression type to set (one of ::wimlib_compression_type). If this
- * compression type is incompatible with the current output chunk size
- * (either the default or as set with wimlib_set_output_chunk_size()), then
- * the output chunk size will be reset to the default for that compression
- * type.
+ * The compression type to set. If this compression type is incompatible
+ * with the current output chunk size, then the output chunk size will be
+ * reset to the default for the new compression type.
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
* @p ctype did not specify a valid compression type.
*/
extern int
-wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
+wimlib_set_output_compression_type(WIMStruct *wim,
+ enum wimlib_compression_type ctype);
/**
* @ingroup G_writing_and_overwriting_wims
*
* Similar to wimlib_set_output_compression_type(), but set the compression type
- * for writing solid resources.
+ * for writing solid resources. This cannot be ::WIMLIB_COMPRESSION_TYPE_NONE.
*/
extern int
-wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
+wimlib_set_output_pack_compression_type(WIMStruct *wim,
+ enum wimlib_compression_type ctype);
/**
* @ingroup G_general
* @param wim
* Pointer to the ::WIMStruct for a WIM.
* @param info
- * A struct ::wimlib_wim_info that contains the information to set. Only
- * the information explicitly specified in the @p which flags need be
- * valid.
+ * Pointer to a ::wimlib_wim_info structure that contains the information
+ * to set. Only the information explicitly specified in the @p which flags
+ * need be valid.
* @param which
* Flags that specify which information to set. This is a bitwise OR of
* ::WIMLIB_CHANGE_READONLY_FLAG, ::WIMLIB_CHANGE_GUID,
* @retval ::WIMLIB_ERR_FVE_LOCKED_VOLUME
* Windows-only: One of the "add" commands attempted to add files from an
* encrypted BitLocker volume that hasn't yet been unlocked.
+ * @retval ::WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES
+ * There are currently multiple references to the WIM image as a result of
+ * a call to wimlib_export_image(). Free one before attempting the update.
* @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
- * The capture configuration structure specified for an add command was
- * invalid.
+ * The contents of a capture configuration file were invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image did not exist in @p wim.
* @retval ::WIMLIB_ERR_INVALID_OVERLAY
* Attempted to perform an add command that conflicted with previously
* existing files in the WIM when an overlay was attempted.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * An unknown operation type was specified in the update commands; or,
- * attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set
- * in the @p add_flags, but the same image had previously already been
- * added from an NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and
- * ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @p add_flags for one add
- * command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were
+ * An unknown operation type was specified in the update commands; or, both
+ * ::WIMLIB_ADD_FLAG_RPFIX and ::WIMLIB_ADD_FLAG_NORPFIX were specified in
+ * the @p add_flags for one add command; or ::WIMLIB_ADD_FLAG_RPFIX were
* specified in the @p add_flags for an add command in which @p
* wim_target_path was not the root directory of the WIM image.
* @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA
* @retval ::WIMLIB_ERR_STAT
* While executing an add command, failed to get attributes for a file or
* directory.
+ * @retval ::WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG
+ * A capture configuration file could not be read.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* ::WIMLIB_ADD_FLAG_NTFS was specified in the @p add_flags for an update
* command, but wimlib was configured with the @c --without-ntfs-3g flag;
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
+ * @retval ::WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED
+ * A file that had previously been scanned for inclusion in the WIM was
+ * concurrently modified.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image did not exist in @p wim.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
- * A file, stored in another WIM, which needed to be written was corrupt;
- * or a file that had previously been scanned for inclusion in the WIM was
- * concurrently modified.
+ * A file, stored in another WIM, which needed to be written was corrupt.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p path was not a nonempty string, or invalid flags were passed.
* @retval ::WIMLIB_ERR_OPEN