/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.8.2, 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
#define WIMLIB_MINOR_VERSION 8
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 3
#ifdef __cplusplus
extern "C" {
*
* 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
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_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,
};
*
* 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.
/**
* @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);
* 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
* @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,
* @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 contents of a capture configuration file were invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
*
* @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