X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=32482032149e7e43df140eef5a9b5b39d832693f;hp=1655f5c6ec918ebf1f2238309950cb4d9f36e275;hb=82bfc7bdc6a85406dff3fa4f9fcc7b9fc0ae5de5;hpb=c55f2da2961e8412e93722b2e8b6ec7c9779d80b diff --git a/include/wimlib.h b/include/wimlib.h index 1655f5c6..32482032 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -180,6 +180,10 @@ /** Patch version of the library (for example, the 5 in 1.2.5). */ #define WIMLIB_PATCH_VERSION 0 +#ifdef __cplusplus +extern "C" { +#endif + /** * Opaque structure that represents a WIM file. This is an in-memory structure * and need not correspond to a specific on-disk file. However, a ::WIMStruct @@ -900,6 +904,14 @@ typedef int (*wimlib_iterate_dir_tree_callback_t)(const struct wimlib_dir_entry typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resource_entry *resource, void *user_ctx); +/** + * @name Directory tree iteration flags + * + * The following flags can be passed to wimlib_iterate_dir_tree(). + * + * @{ + */ + /** For wimlib_iterate_dir_tree(): Iterate recursively on children rather than * just on the specified path. */ #define WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE 0x00000001 @@ -910,9 +922,15 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour -/***************************** - * WIMLIB_ADD_FLAG_* - *****************************/ +/** + * @name Add flags + * + * The following flags can be passed to wimlib_add_image(), + * wimlib_add_image_multisource(), and add commands passed to + * wimlib_update_image(). + * + * @{ + */ /** Directly capture a NTFS volume rather than a generic directory. This flag * cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or @@ -936,7 +954,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * contain this information. Please note that this flag is for convenience * only; Microsoft's @a imagex.exe will not understand this special information. * This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */ -#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 +#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 /** Do not capture security descriptors. Only has an effect in NTFS capture * mode, or in Win32 native builds. */ @@ -971,12 +989,31 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * documentation for ::WIMLIB_ADD_FLAG_RPFIX. */ #define WIMLIB_ADD_FLAG_NORPFIX 0x00000200 -/** Do not exclude unsupported files or directories from capture; e.g. encrypted - * directories in NTFS-3g capture mode, or device files and FIFOs on UNIX-like - * systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when such a file - * is encountered. */ +/** Do not automatically exclude unsupported files or directories from capture; + * e.g. encrypted directories in NTFS-3g capture mode, or device files and FIFOs + * on UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when + * such a file is encountered. */ #define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400 +/** Automatically select a capture configuration appropriate for capturing + * filesystems containing Windows operating systems. When this flag is + * specified, the corresponding @p config parameter or member must be @c NULL. + * + * Currently, selecting this capture configuration will cause the following + * files and directories to be excluded from capture: + * + * - "\$ntfs.log" + * - "\hiberfil.sys" + * - "\pagefile.sys" + * - "\System Volume Information" + * - "\RECYCLER" + * - "\Windows\CSC" + * + * Note that the default behavior--- that is, when this flag is not specified + * and @p config is @c NULL--- is to use no capture configuration, meaning that + * no files are excluded from capture. + */ +#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800 #define WIMLIB_ADD_IMAGE_FLAG_NTFS WIMLIB_ADD_FLAG_NTFS #define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE WIMLIB_ADD_FLAG_DEREFERENCE @@ -990,10 +1027,16 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #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 -/****************************** - * WIMLIB_DELETE_FLAG_* - ******************************/ +/** + * @name Delete flags + * + * The following flags can be specified in delete commands passed to + * wimlib_update_image(). + * + * @{ + */ /** Do not issue an error if the path to delete does not exist. */ #define WIMLIB_DELETE_FLAG_FORCE 0x00000001 @@ -1002,16 +1045,38 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * issued if the path to delete is a directory. */ #define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002 -/****************************** - * WIMLIB_EXPORT_FLAG_* - ******************************/ +/** + * @name Export flags + * + * The following flags can be passed to wimlib_export_image(). + * + * @{ + */ -/** See documentation for wimlib_export_image(). */ +/** + * If a single image is being exported, mark it bootable in the destination WIM. + * Alternatively, if ::WIMLIB_ALL_IMAGES is specified as the image to export, + * the image in the source WIM (if any) that is marked as bootable is also + * marked as bootable in the destination WIM. + */ #define WIMLIB_EXPORT_FLAG_BOOT 0x00000001 -/****************************** - * WIMLIB_EXTRACT_FLAG_* - ******************************/ +/** Give the exported image(s) no names. Avoids problems with image name + * collisions. + */ +#define WIMLIB_EXPORT_FLAG_NO_NAMES 0x00000002 + +/** Give the exported image(s) no descriptions. */ +#define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS 0x00000004 + +/** + * @name Extract flags + * + * The following flags can be passed to wimlib_extract_image(), + * wimlib_extract_files(), and wimlib_extract_image_from_pipe(). + * + * @{ + */ /** Extract the image directly to a NTFS volume rather than a generic directory. * This mode is only available if wimlib was compiled with libntfs-3g support; @@ -1037,8 +1102,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Read the WIM file sequentially while extracting the image. */ #define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010 -/** Extract special UNIX data captured with ::WIMLIB_ADD_FLAG_UNIX_DATA. - * Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */ +/** Extract special UNIX data captured with ::WIMLIB_ADD_FLAG_UNIX_DATA. Only + * valid on UNIX-like platforms, and when ::WIMLIB_EXTRACT_FLAG_NTFS was not + * specified. */ #define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020 /** Do not extract security descriptors. */ @@ -1092,13 +1158,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * create symbolic links. */ #define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000 -/** TODO */ +/** TODO: this flag is intended to allow resuming an aborted extraction, but the + * behavior is currently less than satisfactory. Do not use (yet). */ #define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000 - -/****************************** - * WIMLIB_MOUNT_FLAG_* - ******************************/ +/** + * @name Mount flags + * + * The following flags can be passed to wimlib_mount_image(). + * + * @{ + */ /** Mount the WIM image read-write rather than the default of read-only. */ #define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001 @@ -1125,60 +1195,76 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * allow_other option to FUSE mount) */ #define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 -/****************************** - * WIMLIB_OPEN_FLAG_* - ******************************/ +/** + * @name Open flags + * + * The following flags can be passed to wimlib_open_wim() and several other + * functions such as wimlib_join(). + * @{ + */ /** Verify the WIM contents against the WIM's integrity table, if present. This * causes the raw data of the WIM file, divided into 10 MB chunks, to be * checksummed and checked against the SHA1 message digests specified in the * integrity table. ::WIMLIB_ERR_INTEGRITY is returned if there are any - * mismatches. */ + * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the + * integrity table is invalid). */ #define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001 -/** Do not issue an error if the WIM is part of a split WIM. */ +/** Do not issue an error if the WIM is part of a split WIM. Programs must + * specify this flag if they intend to open part of a split WIM, rather than + * only supporting standalone WIMs. */ #define WIMLIB_OPEN_FLAG_SPLIT_OK 0x00000002 /** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it * is not. A WIM is considered writable only if it is writable at the * filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its * header, and is not part of a spanned set. It is not required to provide this - * flag to make changes to the WIM, but with this flag you get the error sooner - * rather than later. */ + * flag before attempting to make changes to the WIM, but with this flag you get + * an error sooner rather than later. */ #define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004 -/****************************** - * WIMLIB_UNMOUNT_FLAG_* - ******************************/ +/** + * @name Unmount flags + * + * The following flags can be passed to wimlib_unmount_image(). + * @{ + */ -/** Include an integrity table in the WIM after it's been unmounted. Ignored - * for read-only mounts. */ +/** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */ #define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001 /** Unless this flag is given, changes to a read-write mounted WIM are - * discarded. Ignored for read-only mounts. */ + * discarded. Ignored for read-only mounts. */ #define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002 -/** See ::WIMLIB_WRITE_FLAG_REBUILD */ +/** See ::WIMLIB_WRITE_FLAG_REBUILD. */ #define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004 /** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */ #define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008 -/** Do a "lazy" unmount (detach filesystem immediately, even if busy) */ +/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */ #define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010 -/****************************** - * WIMLIB_UPDATE_FLAG_* - ******************************/ +/** + * @name Update flags + * + * The following flags can be passed to wimlib_update_image(). + * @{ + */ /** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and - * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */ + * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */ #define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001 -/****************************** - * WIMLIB_WRITE_FLAG_* - ******************************/ +/** + * @name Write flags + * + * The following flags can be passed to wimlib_write(), wimlib_overwrite(), + * wimlib_write_to_fd(), and several other functions such as wimlib_join(). + * @{ + */ /** Include an integrity table in the WIM. * @@ -1228,7 +1314,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * only minimal changes to correctly remove the image from the WIM will be * taken. In particular, all streams will be left alone, even if they are no * longer referenced. This is probably not what you want, because almost no - * space will be saved by deleting an image in this way. */ + * space will be saved by deleting an image in this way. */ #define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000080 /** wimlib_overwrite() only: Allow overwriting the WIM even if the readonly @@ -1237,12 +1323,32 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * set the readonly flag on the on-disk WIM file. */ #define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100 -/****************************** - * WIMLIB_INIT_FLAG_* - ******************************/ +/** Do not include non-metadata resources already present in other WIMs. This + * flag can be used to write a "delta" WIM after resources from the WIM on which + * the delta is to be based were referenced with + * wimlib_reference_resource_files() or wimlib_reference_resources(). */ +#define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS 0x00000200 + +/** Asserts that for writes of all WIM images, all streams needed for the WIM + * are already present (not in external resource WIMs) and their reference + * counts are correct, so the code does not need to recalculate which streams + * are referenced. This is for optimization purposes only, since with this flag + * specified, the metadata resources may not need to be decompressed and parsed. + * + * This flag can be passed to wimlib_write() and wimlib_write_to_fd(), but is + * already implied for wimlib_overwrite(). */ +#define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 + +/** + * @name Init flags + * + * The following flags can be passed to wimlib_global_init(). + * @{ + */ /** Assume that strings are represented in UTF-8, even if this is not the - * locale's character encoding. Not used on Windows. */ + * locale's character encoding. This flag is ignored on Windows, where wimlib + * always uses UTF-16LE. */ #define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001 /** Windows-only: do not attempt to acquire additional privileges (currently @@ -1254,6 +1360,88 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * 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, + * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed + * to read all possible data and metadata for a capture operation could not be + * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES. + */ +#define WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES 0x00000004 + +/** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, + * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed + * to restore all possible data and metadata for an apply operation could not be + * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES. + */ +#define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008 + +/** + * @name Resource reference flags + * + * The following flags can be passed to wimlib_reference_resource_files() and + * wimlib_reference_resources(). + * @{ + */ + +/** wimlib_reference_resource_files() only: Enable shell-style filename + * globbing. */ +#define WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001 + +/** wimlib_reference_resource_files() only: 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. */ +#define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002 + +/** + * @} + */ + +/** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */ +struct wimlib_add_command { + /** Filesystem path to the file or directory tree to + * add. */ + wimlib_tchar *fs_source_path; + /** Path, specified from the root of the WIM image, at + * which to add the file or directory tree within the + * WIM image. */ + wimlib_tchar *wim_target_path; + + /** Configuration for excluded files. @c NULL means + * exclude no files (use no configuration), unless + * ::WIMLIB_ADD_FLAG_WINCONFIG is specified in @p + * add_flags. */ + struct wimlib_capture_config *config; + + /** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */ + int add_flags; +}; + +/** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */ +struct wimlib_delete_command { + /** Path, specified from the root of the WIM image, for + * the file or directory tree within the WIM image to be + * deleted. */ + wimlib_tchar *wim_path; + /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ + int delete_flags; +}; + +/** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */ +struct wimlib_rename_command { + /** Path, specified from the root of the WIM image, for + * the source file or directory tree within the WIM + * image. */ + wimlib_tchar *wim_source_path; + /** Path, specified from the root of the WIM image, for + * the destination file or directory tree within the WIM + * image. */ + wimlib_tchar *wim_target_path; + /** Reserved; set to 0. */ + int rename_flags; +}; + /** Specification of an update to perform on a WIM image. */ struct wimlib_update_command { @@ -1270,45 +1458,10 @@ struct wimlib_update_command { WIMLIB_UPDATE_OP_RENAME, } op; union { - /** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */ - struct wimlib_add_command { - /** Filesystem path to the file or directory tree to - * add. */ - wimlib_tchar *fs_source_path; - /** Path, specified from the root of the WIM image, at - * which to add the file or directory tree within the - * WIM image. */ - wimlib_tchar *wim_target_path; - - /** Configuration for excluded files. @c NULL means - * exclude no files. */ - struct wimlib_capture_config *config; - - /** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */ - int add_flags; - } add; - /** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */ - struct wimlib_delete_command { - /** Path, specified from the root of the WIM image, for - * the file or directory tree within the WIM image to be - * deleted. */ - wimlib_tchar *wim_path; - /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ - int delete_flags; - } delete; - /** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */ - struct wimlib_rename_command { - /** Path, specified from the root of the WIM image, for - * the source file or directory tree within the WIM - * image. */ - wimlib_tchar *wim_source_path; - /** Path, specified from the root of the WIM image, for - * the destination file or directory tree within the WIM - * image. */ - wimlib_tchar *wim_target_path; - /** Reserved; set to 0. */ - int rename_flags; - } rename; + struct wimlib_add_command add; + struct wimlib_delete_command delete_; /* Underscore is for C++ + compatibility. */ + struct wimlib_rename_command rename; }; }; @@ -1341,9 +1494,11 @@ enum wimlib_error_code { WIMLIB_ERR_FORK, WIMLIB_ERR_FUSE, WIMLIB_ERR_FUSERMOUNT, + WIMLIB_ERR_GLOB_HAD_NO_MATCHES, WIMLIB_ERR_ICONV_NOT_AVAILABLE, WIMLIB_ERR_IMAGE_COUNT, WIMLIB_ERR_IMAGE_NAME_COLLISION, + WIMLIB_ERR_INSUFFICIENT_PRIVILEGES, WIMLIB_ERR_INTEGRITY, WIMLIB_ERR_INVALID_CAPTURE_CONFIG, WIMLIB_ERR_INVALID_CHUNK_SIZE, @@ -1360,13 +1515,13 @@ enum wimlib_error_code { WIMLIB_ERR_INVALID_PIPABLE_WIM, WIMLIB_ERR_INVALID_REPARSE_DATA, WIMLIB_ERR_INVALID_RESOURCE_HASH, - WIMLIB_ERR_INVALID_SECURITY_DATA, WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE, WIMLIB_ERR_INVALID_UTF16_STRING, WIMLIB_ERR_INVALID_UTF8_STRING, WIMLIB_ERR_IS_DIRECTORY, WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE, WIMLIB_ERR_LINK, + WIMLIB_ERR_METADATA_NOT_FOUND, WIMLIB_ERR_MKDIR, WIMLIB_ERR_MQUEUE, WIMLIB_ERR_NOMEM, @@ -1587,10 +1742,11 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); * flag. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, - * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_NOMEM, - * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which - * indicate failure (for different reasons) to read the metadata resource for an - * image that needed to be deleted. + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be deleted. */ extern int wimlib_delete_image(WIMStruct *wim, int image); @@ -1617,76 +1773,64 @@ wimlib_delete_image(WIMStruct *wim, int image); * Pointer to the ::WIMStruct for a stand-alone WIM or part 1 of a split * WIM that contains the image(s) being exported. * @param src_image - * The image to export from @p src_wim. Can be the number of an image, or - * ::WIMLIB_ALL_IMAGES to export all images. + * The image to export from @p src_wim, as either a 1-based image index to + * export a single image, or ::WIMLIB_ALL_IMAGES to export all images. * @param dest_wim - * Pointer to the ::WIMStruct for a WIM file that will receive the images - * being exported. + * Pointer to the ::WIMStruct for a WIM that will receive the images being + * exported. * @param dest_name - * The name to give the exported image in the new WIM file. If left @c - * NULL, the name from @p src_wim is used. This parameter must be left @c - * NULL if @p src_image is ::WIMLIB_ALL_IMAGES and @p src_wim contains more - * than one image; in that case, the names are all taken from the @p - * src_wim. (This is allowed even if one or more images being exported has - * no name.) + * For single-image exports, the name to give the exported image in @p + * dest_wim. If left @c NULL, the name from @p src_wim is used. For + * ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c NULL; in + * that case, the names are all taken from @p src_wim. This parameter is + * overridden by ::WIMLIB_EXPORT_FLAG_NO_NAMES. * @param dest_description - * The description to give the exported image in the new WIM file. If left - * @c NULL, the description from the @p src_wim is used. This parameter must - * be left @c NULL if @p src_image is ::WIMLIB_ALL_IMAGES and @p src_wim contains - * more than one image; in that case, the descriptions are all taken from - * @p src_wim. (This is allowed even if one or more images being exported - * has no description.) + * For single-image exports, the description to give the exported image in + * the new WIM file. If left @c NULL, the description from @p src_wim is + * used. For ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c + * NULL; in that case, the description are all taken from @p src_wim. This + * parameter is overridden by ::WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS. * @param export_flags - * ::WIMLIB_EXPORT_FLAG_BOOT if the image being exported is to be made - * bootable, or 0 if which image is marked as bootable in the destination - * WIM is to be left unchanged. If @p src_image is ::WIMLIB_ALL_IMAGES and - * there are multiple images in @p src_wim, specifying - * ::WIMLIB_EXPORT_FLAG_BOOT is valid only if one of the exported images is - * currently marked as bootable in @p src_wim; if that is the case, then - * that image is marked as bootable in the destination WIM. - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. + * Bitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG. * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * Currently ignored, but reserved for a function that will be called with + * information about the operation. Use NULL if no additional information + * is desired. * * @return 0 on success; nonzero on error. * @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. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p src_image does not exist in @p src_wim. + * @p src_image does not exist in @p src_wim and was not + * ::WIMLIB_ALL_IMAGES. * @retval ::WIMLIB_ERR_INVALID_PARAM - * ::WIMLIB_EXPORT_FLAG_BOOT was specified in @p flags, @p src_image was - * ::WIMLIB_ALL_IMAGES, @p src_wim contains multiple images, and no images in - * @p src_wim are marked as bootable; or @p dest_name and/or @p - * dest_description were non-NULL, @p src_image was - * ::WIMLIB_ALL_IMAGES, and @p src_wim contains multiple images. + * @p src_wim and/or @p dest_wim were @c NULL; or @p src_image was + * ::WIMLIB_ALL_IMAGES but @p dest_name and/or @p dest_description were not + * @c NULL. + * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND + * Either @p src_wim or @p dest_wim did not contain metadata resources; for + * example, one of them was a non-first part of a split WIM. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_SPLIT_INVALID - * The source WIM is a split WIM, but the parts specified do not form a - * complete split WIM because they do not include all the parts of the - * split WIM, there are duplicate parts, or not all the parts are in fact - * from the same split WIM. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * A resource that needed to be exported could not be found in either the + * source or destination WIMs. This error can occur if, for example, @p + * src_wim is part of a split WIM but needed resources from the other split + * WIM parts were not referenced with wimlib_reference_resources() or + * wimlib_reference_resource_files() before the call to + * wimlib_export_image(). * @retval ::WIMLIB_ERR_WIM_IS_READONLY * @p dest_wim is considered read-only because of any of the reasons * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS * flag. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, - * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_NOMEM, - * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which - * indicate failure (for different reasons) to read the metadata resource for an - * image in @p src_wim that needed to be exported. + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image in @p src_wim + * that needed to be exported. */ extern int wimlib_export_image(WIMStruct *src_wim, int src_image, @@ -1694,8 +1838,6 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, const wimlib_tchar *dest_name, const wimlib_tchar *dest_description, int export_flags, - WIMStruct **additional_swms, - unsigned num_additional_swms, wimlib_progress_func_t progress_func); /** @@ -1725,18 +1867,6 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * been specified in the ::wimlib_extract_command.extract_flags member in * each extraction command, in combination with any flags already present. * - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. - * * @param progress_func * If non-NULL, a function that will be called periodically with the * progress of the current operation. @@ -1769,8 +1899,6 @@ wimlib_extract_files(WIMStruct *wim, const struct wimlib_extract_command *cmds, size_t num_cmds, int default_extract_flags, - WIMStruct **additional_swms, - unsigned num_additional_swms, wimlib_progress_func_t progress_func); /** @@ -1803,25 +1931,13 @@ wimlib_extract_files(WIMStruct *wim, * path to the unmounted NTFS volume to extract the image to. * @param extract_flags * Bitwise OR of the flags prefixed with WIMLIB_EXTRACT_FLAG. - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. - * * @param progress_func * If non-NULL, a function that will be called periodically with the * progress of the current operation. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress a resource to be extracted, or failed to decompress - * a needed metadata resource. + * Failed to decompress a resource to be extracted. * @retval ::WIMLIB_ERR_INVALID_PARAM * Both ::WIMLIB_EXTRACT_FLAG_HARDLINK and ::WIMLIB_EXTRACT_FLAG_SYMLINK * were specified in @p extract_flags; or both @@ -1831,8 +1947,6 @@ wimlib_extract_files(WIMStruct *wim, * ::WIMLIB_EXTRACT_FLAG_RESUME was specified in @p extract_flags; or if * ::WIMLIB_EXTRACT_FLAG_NTFS was specified in @p extract_flags and * @p image was ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE - * The metadata resource for an image being extracted was invalid. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH * The SHA1 message digest of an extracted stream did not match the SHA1 * message digest given in the WIM file. @@ -1872,11 +1986,6 @@ wimlib_extract_files(WIMStruct *wim, * @retval ::WIMLIB_ERR_SET_TIMESTAMPS * Failed to set timestamps on a file (only if * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS was specified in @p extract_flags). - * @retval ::WIMLIB_ERR_SPLIT_INVALID - * The WIM is a split WIM, but the parts specified do not form a complete - * split 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. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE * Unexpected end-of-file occurred when reading data from the WIM file * associated with @p wim. @@ -1899,13 +2008,18 @@ wimlib_extract_files(WIMStruct *wim, * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags. * @retval ::WIMLIB_ERR_WRITE * Failed to write data to a file being extracted. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be extracted. */ extern int wimlib_extract_image(WIMStruct *wim, int image, const wimlib_tchar *target, int extract_flags, - WIMStruct **additional_swms, - unsigned num_additional_swms, wimlib_progress_func_t progress_func); /** @@ -1930,7 +2044,7 @@ wimlib_extract_image(WIMStruct *wim, int image, * wimlib_resolve_image() uses. However, unlike wimlib_extract_image(), * only a single image (not all images) can be specified. Alternatively, * specify @p NULL here to use the first image in the WIM if it contains - * exactly one image but otherwise return @p WIMLIB_ERR_INVALID_IMAGE. + * exactly one image but otherwise return ::WIMLIB_ERR_INVALID_IMAGE. * @param target * Same as the corresponding parameter to wimlib_extract_image(). * @param extract_flags @@ -2081,10 +2195,15 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); * but you should not rely on this behavior.) * * @param init_flags - * Bitwise OR of ::WIMLIB_INIT_FLAG_ASSUME_UTF8 and/or - * ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES. + * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. * - * @return 0; other error codes may be returned in future releases. + * @return 0 on success; nonzero on failure. Currently, only the following + * error code is defined: + * + * @retval ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES + * ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES and/or + * ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES were specified in @p + * init_flags, but the corresponding privileges could not be acquired. */ extern int wimlib_global_init(int init_flags); @@ -2151,10 +2270,11 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * Failed to allocate memory needed to create a ::wimlib_dir_entry. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, - * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_NOMEM, - * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which - * indicate failure (for different reasons) to read the metadata resource for an - * image over which iteration needed to be done. + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image over which + * iteration needed to be done. */ extern int wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, @@ -2200,8 +2320,8 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * Number of filenames in @p swms. * @param swm_open_flags * Open flags for the split WIM parts (e.g. - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). Note: WIMLIB_OPEN_FLAG_SPLIT_OK is - * automatically added to the value specified here. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). Note: ::WIMLIB_OPEN_FLAG_SPLIT_OK + * is automatically added to the value specified here. * @param wim_write_flags * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will * be used to write the joined WIM. @@ -2221,8 +2341,9 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * parts have the same GUID and compression type. * * Note: wimlib_export_image() can provide similar functionality to - * wimlib_join(), since it is possible to export all images from a split WIM. - * Actually, wimlib_join() currently calls wimlib_export_image internally. + * wimlib_join(), since it is possible to export all images from a split WIM + * into a new ::WIMStruct, then write it. However, wimlib_join() may have + * better performance than this method. */ extern int wimlib_join(const wimlib_tchar * const *swms, @@ -2319,16 +2440,6 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * The path to an existing empty directory to mount the image on. * @param mount_flags * Bitwise OR of the flags prefixed with WIMLIB_MOUNT_FLAG. - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. * @param staging_dir * If non-NULL, the name of a directory in which the staging directory will * be created. Ignored if ::WIMLIB_MOUNT_FLAG_READWRITE is not specified @@ -2342,14 +2453,10 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * the on-disk WIM file could not be acquired because another thread or * process has mounted an image from the WIM read-write or is currently * modifying the WIM in-place. - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Could not decompress the metadata resource for @p image in @p wim. * @retval ::WIMLIB_ERR_FUSE * A non-zero status was returned by @c fuse_main(). * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image does not specify an existing, single image in @p wim. - * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE - * The metadata resource for @p image is invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p image is shared among multiple ::WIMStruct's as a result of a call to * wimlib_export_image(), or @p image has been added with @@ -2357,40 +2464,32 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * @retval ::WIMLIB_ERR_MKDIR * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the * staging directory could not be created. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_NOTDIR * Could not determine the current working directory. - * @retval ::WIMLIB_ERR_READ - * Failed to read data from the WIM file associated with @p wim. * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND * One of the dentries in the image referenced a stream not present in the * WIM's lookup table (or in any of the lookup tables of the split WIM * parts). - * @retval ::WIMLIB_ERR_SPLIT_INVALID - * The WIM is a split WIM, but the parts specified do not form a complete - * split 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. * @retval ::WIMLIB_ERR_WIM_IS_READONLY * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but @p * wim is considered read-only because of any of the reasons mentioned in * the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. - * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Unexpected end-of-file occurred while reading data from the WIM file - * associated with @p wim. * @retval ::WIMLIB_ERR_UNSUPPORTED * Mounting is not supported, either because the platform is Windows, or * because the platform is UNIX-like and wimlib was compiled with @c * --without-fuse. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for the image to mount. */ extern int wimlib_mount_image(WIMStruct *wim, int image, const wimlib_tchar *dir, int mount_flags, - WIMStruct **additional_swms, - unsigned num_additional_swms, const wimlib_tchar *staging_dir); /** @@ -2525,8 +2624,9 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * If non-NULL, a function that will be called periodically with the * progress of the current operation. * - * @return 0 on success; nonzero on error. This function may return any value - * returned by wimlib_write() as well as the following error codes: + * @return 0 on success; nonzero on error. This function may return most error + * codes returned by wimlib_write() as well as the following error codes: + * * @retval ::WIMLIB_ERR_ALREADY_LOCKED * The WIM was going to be modified in-place (with no temporary file), but * an exclusive advisory lock on the on-disk WIM file could not be acquired @@ -2578,6 +2678,165 @@ wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; extern int wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; +/** + * Reference resources 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 needed resources (that is, "streams" keyed by SHA1 message digest) + * from other files, before calling a function such as wimlib_extract_image() + * that requires the resources to be present. + * + * @param 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. + * @param 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 @p + * 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. + * @param count + * Number of entries in @p resource_wimfiles_or_globs. + * @param ref_flags + * Bitwise OR of ::WIMLIB_REF_FLAG_GLOB_ENABLE and/or + * ::WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH. + * @param 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. + * Note: ::WIMLIB_OPEN_FLAG_SPLIT_OK will be supplied regardless of this + * parameter. + * @param progress_func + * Passed to internal calls to wimlib_open_wim() on the reference files. + * + * @return 0 on success; nonzero on error. + * + * @retval ::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 @p ref_flags). + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate memory. + * @retval ::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(). + */ +extern int +wimlib_reference_resource_files(WIMStruct *wim, + const wimlib_tchar * const *resource_wimfiles_or_globs, + unsigned count, + int ref_flags, + int open_flags, + wimlib_progress_func_t progress_func); + +/** + * Similar to wimlib_reference_resource_files(), but operates at a lower level + * where the caller must open the ::WIMStruct for each referenced file itself. + * + * @param 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. + * @param resource_wims + * Array of pointers to the ::WIMStruct's for additional resource WIMs or + * split WIM parts to reference. + * @param num_resource_wims + * Number of entries in @p resource_wims. + * @param ref_flags + * Currently ignored (set to 0). + * + * @return 0 on success; nonzero on error. 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(). + * + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p wim was @c NULL, or @p num_resource_wims was nonzero but @p + * resource_wims was @c NULL, or an entry in @p resource_wims was @p NULL. + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate memory. + */ +extern int +wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, + unsigned num_resource_wims, int ref_flags); + +/** + * Declares that a newly added image is mostly the same as a prior image, but + * captured at a later point in time, possibly with some modifications in the + * intervening time. This is designed to be used in incremental backups of the + * same filesystem or directory tree. + * + * This function compares the metadata of the directory tree of the newly added + * image against that of the old image. Any files that are present in both the + * newly added image and the old image and have timestamps that indicate they + * haven't been modified are deemed not to have been modified and have their + * SHA1 message digest copied from the old image. Because of this and because + * WIM uses single-instance streams, such files need not be read from the + * filesystem when the WIM is being written or overwritten. Note that these + * unchanged files will still be "archived" and will be logically present in the + * new image; the optimization is that they don't need to actually be read from + * the filesystem because the WIM already contains them. + * + * This function is provided to optimize incremental backups. The resulting WIM + * file will still be the same regardless of whether this function is called. + * (This is, however, assuming that timestamps have not been manipulated or + * unmaintained as to trick this function into thinking a file has not been + * modified when really it has. To partly guard against such cases, other + * metadata such as file sizes will be checked as well.) + * + * This function must be called after adding the new image (e.g. with + * wimlib_add_image()), but before writing the updated WIM file (e.g. with + * wimlib_overwrite()). + * + * @param wim + * Pointer to the ::WIMStruct for a WIM. + * @param new_image + * 1-based index in the WIM of the newly added image. This image can have + * been added with wimlib_add_image() or wimlib_add_image_multisource(), or + * wimlib_add_empty_image() followed by wimlib_update_image(). + * @param template_wim + * The ::WIMStruct for the WIM containing the template image. This can be + * the same as @p wim, or it can be a different ::WIMStruct. + * @param template_image + * 1-based index in the WIM of a template image that reflects a prior state + * of the directory tree being captured. + * @param flags + * Reserved; must be 0. + * @param progress_func + * Currently ignored, but reserved for a function that will be called with + * information about the operation. Use NULL if no additional information + * is desired. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_IMAGE + * @p new_image and/or @p template_image were not a valid image indices in + * the WIM. + * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND + * The specified ::WIMStruct did not actually contain the metadata resource + * for the new or template image; for example, it was a non-first part of a + * split WIM. + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate needed memory. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p new_image was equal to @p template_image, or @p new_image specified + * an image that had not been modified since opening the WIM. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for the template image. + */ +extern int +wimlib_reference_template_image(WIMStruct *wim, int new_image, + WIMStruct *template_wim, int template_image, + int flags, wimlib_progress_func_t progress_func); + /** * Translates a string specifying the name or number of an image in the WIM into * the number of the image. The images are numbered starting at 1. @@ -2716,8 +2975,8 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); * @p wim is considered read-only because of any of the reasons mentioned * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. */ -extern int wimlib_set_image_name(WIMStruct *wim, int image, - const wimlib_tchar *name); +extern int +wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); /** * Set the functions that wimlib uses to allocate and free memory. @@ -2807,8 +3066,6 @@ wimlib_set_print_errors(bool show_messages); * codes that can be returned by wimlib_write() as well as the following error * codes: * - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @p wim was not part 1 of a stand-alone WIM. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p swm_name was not a nonempty string, or @p part_size was 0. * @@ -2914,8 +3171,6 @@ wimlib_unmount_image(const wimlib_tchar *dir, * update commands may have been executed. No individual update command will * have been partially executed. Possible error codes include: * - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress the metadata resource from @p image in @p wim. * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG * The capture configuration structure specified for an add command was * invalid. @@ -2936,10 +3191,6 @@ wimlib_unmount_image(const wimlib_tchar *dir, * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA * (Windows only): While executing an add command, tried to capture a * reparse point with invalid data. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for @p image in @p wim is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for image @p image in @p wim is invalid. * @retval ::WIMLIB_ERR_IS_DIRECTORY * A delete command without ::WIMLIB_DELETE_FLAG_RECURSIVE specified was * for a WIM path that corresponded to a directory; or, a rename command @@ -2966,20 +3217,14 @@ wimlib_unmount_image(const wimlib_tchar *dir, * WIM path that did not exist; or, a rename command attempted to rename a * file that does not exist. * @retval ::WIMLIB_ERR_READ - * Failed to read the metadata resource for @p image in @p wim; or, while - * executing an add command, failed to read data from a file or directory - * to be captured. + * While executing an add command, failed to read data from a file or + * directory to be captured. * @retval ::WIMLIB_ERR_READLINK * While executing an add command, failed to read the target of a symbolic * link or junction point. * @retval ::WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED * (Windows only) Failed to perform a reparse point fixup because of * problems with the data of a reparse point. - * @retval ::WIMLIB_ERR_UNSUPPORTED_FILE - * While executing an add command, attempted to capture a file that was not - * a supported file type (e.g. a device file). Only if - * ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified in @p the add_flags - * for an update command. * @retval ::WIMLIB_ERR_STAT * While executing an add command, failed to get attributes for a file or * directory. @@ -2989,10 +3234,22 @@ wimlib_unmount_image(const wimlib_tchar *dir, * or, the platform is Windows and either the ::WIMLIB_ADD_FLAG_UNIX_DATA * or the ::WIMLIB_ADD_FLAG_DEREFERENCE flags were specified in the @p * add_flags for an update command. + * @retval ::WIMLIB_ERR_UNSUPPORTED_FILE + * While executing an add command, attempted to capture a file that was not + * a supported file type (e.g. a device file). Only if + * ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified in @p the add_flags + * for an update command. * @retval ::WIMLIB_ERR_WIM_IS_READONLY * The WIM file is considered read-only because of any of the reasons * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS * flag. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be updated. */ extern int wimlib_update_image(WIMStruct *wim, @@ -3036,8 +3293,6 @@ wimlib_update_image(WIMStruct *wim, * * @return 0 on success; nonzero on error. * - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress a metadata or file resource in @p wim. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image does not specify a single existing image in @p wim, and is not * ::WIMLIB_ALL_IMAGES. @@ -3047,8 +3302,6 @@ wimlib_update_image(WIMStruct *wim, * message digest check. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p path was @c NULL. - * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE - * The metadata resource for @p image in @p wim is invalid. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_OPEN @@ -3060,10 +3313,21 @@ wimlib_update_image(WIMStruct *wim, * with @p wim, or some file resources in @p wim refer to files in the * outside filesystem, and a read error occurred when reading one of these * files. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @p wim is part of a split WIM, not a standalone WIM. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * A stream that needed to be written could not be found in the stream + * lookup table of @p wim. This error can occur if, for example, @p wim is + * part of a split WIM but needed resources from the other split WIM parts + * were not referenced with wimlib_reference_resources() or + * wimlib_reference_resource_files() before the call to wimlib_write(). * @retval ::WIMLIB_ERR_WRITE * An error occurred when trying to write data to the new WIM file. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be written. */ extern int wimlib_write(WIMStruct *wim, @@ -3114,4 +3378,8 @@ extern int wimlib_xpress_decompress(const void *compressed_data, unsigned compressed_len, void *uncompressed_data, unsigned uncompressed_len); +#ifdef __cplusplus +} +#endif + #endif /* _WIMLIB_H */