X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=087868a59d70ba4cca9a536e92a67be2752e4dd8;hp=a5a73e3895883a7243b8beda78d61a36f1438aaa;hb=b8096559f39fa8b526e47fca249fa98ef1890315;hpb=037dc6208a1e57910a46e05f5de2788d8adfa207;ds=sidebyside diff --git a/include/wimlib.h b/include/wimlib.h index a5a73e38..087868a5 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -156,6 +156,7 @@ #include #include #include +#include /** Major version of the library (for example, the 1 in 1.2.5). */ #define WIMLIB_MAJOR_VERSION 1 @@ -200,6 +201,13 @@ typedef char wimlib_tchar; # define WIMLIB_WIM_PATH_SEPARATOR '/' # define WIMLIB_WIM_PATH_SEPARATOR_STRING "/" #endif + +#ifdef __GNUC__ +# define _wimlib_deprecated __attribute__((deprecated)) +#else +# define _wimlib_deprecated +#endif + /** * Specifies the compression type of a WIM file. */ @@ -615,6 +623,265 @@ struct wimlib_capture_config { size_t _prefix_num_tchars; }; +/** Set or unset the WIM header flag that marks it read-only + * (WIM_HDR_FLAG_READONLY in Microsoft's documentation), based on the + * ::wimlib_wim_info.is_marked_readonly member of the @a info parameter. This + * is distinct from basic file permissions; this flag can be set on a WIM file + * that is physically writable. If this flag is set, all further operations to + * modify the WIM will fail, except calling wimlib_overwrite() with + * ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG specified, which is a loophole that + * allows you to set this flag persistently on the underlying WIM file. + */ +#define WIMLIB_CHANGE_READONLY_FLAG 0x00000001 + +/** Set the GUID (globally unique identifier) of the WIM file to the value + * specified in ::wimlib_wim_info.guid of the @a info parameter. */ +#define WIMLIB_CHANGE_GUID 0x00000002 + +/** Change the bootable image of the WIM to the value specified in + * ::wimlib_wim_info.boot_index of the @a info parameter. */ +#define WIMLIB_CHANGE_BOOT_INDEX 0x00000004 + +/** Change the WIM_HDR_FLAG_RP_FIX flag of the WIM file to the value specified + * in ::wimlib_wim_info.has_rpfix of the @a info parameter. This flag generally + * indicates whether an image in the WIM has been captured with reparse-point + * fixups enabled. wimlib also treats this flag as specifying whether to do + * reparse-point fixups by default when capturing or applying WIM images. */ +#define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 + +#define WIMLIB_GUID_LEN 16 + +/** General information about a WIM file. */ +struct wimlib_wim_info { + + /** Globally unique identifier for the WIM file. Note: all parts of a + * split WIM should have an identical value in this field. */ + uint8_t guid[WIMLIB_GUID_LEN]; + + /** Number of images in the WIM. */ + uint32_t image_count; + + /** 1-based index of the bootable image in the WIM, or 0 if no image is + * bootable. */ + uint32_t boot_index; + + /** Version of the WIM file. */ + uint32_t wim_version; + + /** Chunk size used for compression. */ + uint32_t chunk_size; + + /** 1-based index of this part within a split WIM, or 1 if the WIM is + * standalone. */ + uint16_t part_number; + + /** Total number of parts in the split WIM, or 1 if the WIM is + * standalone. */ + uint16_t total_parts; + + /** One of the ::wimlib_compression_type values that specifies the + * method used to compress resources in the WIM. */ + int32_t compression_type; + + /** Size of the WIM file in bytes, excluding the XML data and integrity + * table. */ + uint64_t total_bytes; + + /** 1 if the WIM has an integrity table. Note: if the ::WIMStruct was + * created via wimlib_create_new_wim() rather than wimlib_open_wim(), + * this will always be 0, even if the ::WIMStruct was written to + * somewhere by calling wimlib_write() with the + * ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY flag specified. */ + uint32_t has_integrity_table : 1; + + /** 1 if the ::WIMStruct was created via wimlib_open_wim() rather than + * wimlib_create_new_wim(). */ + uint32_t opened_from_file : 1; + + /** 1 if the WIM is considered readonly for any reason. */ + uint32_t is_readonly : 1; + + /** 1 if reparse-point fixups are supposedly enabled for one or more + * images in the WIM. */ + uint32_t has_rpfix : 1; + + /** 1 if the WIM is marked as read-only. */ + uint32_t is_marked_readonly : 1; + + /** 1 if the WIM is part of a spanned set. */ + uint32_t spanned : 1; + + uint32_t write_in_progress : 1; + uint32_t metadata_only : 1; + uint32_t resource_only : 1; + uint32_t reserved_flags : 23; + uint32_t reserved[9]; +}; + +/** Information about a unique resource in the WIM file. + */ +struct wimlib_resource_entry { + /** Uncompressed size of the resource in bytes. */ + uint64_t uncompressed_size; + + /** Compressed size of the resource in bytes. This will be the same as + * @a uncompressed_size if the resource is uncompressed. */ + uint64_t compressed_size; + + /** Offset, in bytes, of this resource from the start of the WIM file. + */ + uint64_t offset; + + /** SHA1 message digest of the resource's uncompressed contents. */ + uint8_t sha1_hash[20]; + + /** Which part number of the split WIM this resource is in. This should + * be the same as the part number provided by wimlib_get_wim_info(). */ + uint32_t part_number; + + /** Number of times this resource is referenced over all WIM images. */ + uint32_t reference_count; + + /** 1 if this resource is compressed. */ + uint32_t is_compressed : 1; + + /** 1 if this resource is a metadata resource rather than a file + * resource. */ + uint32_t is_metadata : 1; + + uint32_t is_free : 1; + uint32_t is_spanned : 1; + uint32_t reserved_flags : 28; + uint64_t reserved[4]; +}; + +/** A stream of a file in the WIM. */ +struct wimlib_stream_entry { + /** Name of the stream, or NULL if the stream is unnamed. */ + const wimlib_tchar *stream_name; + /** Location, size, etc. of the stream within the WIM file. */ + struct wimlib_resource_entry resource; + uint64_t reserved[4]; +}; + +/** Structure passed to the wimlib_iterate_dir_tree() callback function. + * Roughly, the information about a "file" in the WIM--- but really a directory + * entry ("dentry") because hard links are allowed. The hard_link_group_id + * field can be used to distinguish actual file inodes. */ +struct wimlib_dir_entry { + /** Name of the file, or NULL if this file is unnamed (only possible for + * the root directory) */ + const wimlib_tchar *filename; + + /** 8.3 DOS name of this file, or NULL if this file has no such name. + * */ + const wimlib_tchar *dos_name; + + /** Full path to this file within the WIM image. */ + const wimlib_tchar *full_path; + + /** Depth of this directory entry, where 0 is the root, 1 is the root's + * children, ..., etc. */ + size_t depth; + + /** Pointer to the security descriptor for this file, in Windows + * SECURITY_DESCRIPTOR_RELATIVE format, or NULL if this file has no + * security descriptor. */ + const char *security_descriptor; + + /** Length of the above security descriptor. */ + size_t security_descriptor_size; + +#define WIMLIB_FILE_ATTRIBUTE_READONLY 0x00000001 +#define WIMLIB_FILE_ATTRIBUTE_HIDDEN 0x00000002 +#define WIMLIB_FILE_ATTRIBUTE_SYSTEM 0x00000004 +#define WIMLIB_FILE_ATTRIBUTE_DIRECTORY 0x00000010 +#define WIMLIB_FILE_ATTRIBUTE_ARCHIVE 0x00000020 +#define WIMLIB_FILE_ATTRIBUTE_DEVICE 0x00000040 +#define WIMLIB_FILE_ATTRIBUTE_NORMAL 0x00000080 +#define WIMLIB_FILE_ATTRIBUTE_TEMPORARY 0x00000100 +#define WIMLIB_FILE_ATTRIBUTE_SPARSE_FILE 0x00000200 +#define WIMLIB_FILE_ATTRIBUTE_REPARSE_POINT 0x00000400 +#define WIMLIB_FILE_ATTRIBUTE_COMPRESSED 0x00000800 +#define WIMLIB_FILE_ATTRIBUTE_OFFLINE 0x00001000 +#define WIMLIB_FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 0x00002000 +#define WIMLIB_FILE_ATTRIBUTE_ENCRYPTED 0x00004000 +#define WIMLIB_FILE_ATTRIBUTE_VIRTUAL 0x00010000 + /** File attributes, such as whether the file is a directory or not. + * These are the "standard" Windows FILE_ATTRIBUTE_* values, although in + * wimlib.h they are defined as WIMLIB_FILE_ATTRIBUTE_* for convenience + * on other platforms. */ + uint32_t attributes; + +#define WIMLIB_REPARSE_TAG_RESERVED_ZERO 0x00000000 +#define WIMLIB_REPARSE_TAG_RESERVED_ONE 0x00000001 +#define WIMLIB_REPARSE_TAG_MOUNT_POINT 0xA0000003 +#define WIMLIB_REPARSE_TAG_HSM 0xC0000004 +#define WIMLIB_REPARSE_TAG_HSM2 0x80000006 +#define WIMLIB_REPARSE_TAG_DRIVER_EXTENDER 0x80000005 +#define WIMLIB_REPARSE_TAG_SIS 0x80000007 +#define WIMLIB_REPARSE_TAG_DFS 0x8000000A +#define WIMLIB_REPARSE_TAG_DFSR 0x80000012 +#define WIMLIB_REPARSE_TAG_FILTER_MANAGER 0x8000000B +#define WIMLIB_REPARSE_TAG_SYMLINK 0xA000000C + /** If the file is a reparse point (FILE_ATTRIBUTE_DIRECTORY set in the + * attributes), this will give the reparse tag. This tells you whether + * the reparse point is a symbolic link, junction point, or some other, + * more unusual kind of reparse point. */ + uint32_t reparse_tag; + + /* Number of (hard) links to this file. */ + uint32_t num_links; + + /** Number of named data streams that this file has. Normally 0. */ + uint32_t num_named_streams; + + /** Roughly, the inode number of this file. However, it may be 0 if + * @a num_links == 1. */ + uint64_t hard_link_group_id; + + /** Time this file was created. */ + struct timespec creation_time; + + /** Time this file was last written to. */ + struct timespec last_write_time; + + /** Time this file was last accessed. */ + struct timespec last_access_time; + uint64_t reserved[16]; + + /** Array of streams that make up this file. The first entry will + * always exist and will correspond to the unnamed data stream (default + * file contents), so it will have @a stream_name == @c NULL. There + * will then be @a num_named_streams additional entries that specify the + * named data streams, if any, each of which will have @a stream_name != + * @c NULL. */ + struct wimlib_stream_entry streams[]; +}; + +/** + * Type of a callback function to wimlib_iterate_dir_tree(). Must return 0 on + * success. + */ +typedef int (*wimlib_iterate_dir_tree_callback_t)(const struct wimlib_dir_entry *dentry, + void *user_ctx); + +/** + * Type of a callback function to wimlib_iterate_lookup_table(). Must return 0 + * on success. + */ +typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resource_entry *resource, + void *user_ctx); + +/** For wimlib_iterate_dir_tree(): Iterate recursively on children rather than + * just on the specified path. */ +#define WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE 0x00000001 + +/** For wimlib_iterate_dir_tree(): Don't iterate on the file or directory + * itself; only its children (in the case of a non-empty directory) */ +#define WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN 0x00000002 + + /***************************** * WIMLIB_ADD_FLAG_* @@ -818,9 +1085,9 @@ struct wimlib_capture_config { /** 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 (note: wimlib currently never sets this flag), 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. */ + * 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. */ #define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004 /****************************** @@ -882,6 +1149,12 @@ struct wimlib_capture_config { * deleting an image in this way. */ #define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000010 +/** With wimlib_overwrite(), allow overwriting the WIM even if the readonly flag + * is set in the WIM header; this can be used in combination with + * wimlib_set_wim_info() with the ::WIMLIB_CHANGE_READONLY_FLAG flag to actually + * set the readonly flag on the on-disk WIM file. */ +#define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000020 + /****************************** * WIMLIB_INIT_FLAG_* ******************************/ @@ -1035,6 +1308,7 @@ enum wimlib_error_code { WIMLIB_ERR_WRITE, WIMLIB_ERR_XML, WIMLIB_ERR_WIM_IS_READONLY, + WIMLIB_ERR_RESOURCE_NOT_FOUND, }; @@ -1518,6 +1792,10 @@ wimlib_extract_files(WIMStruct *wim, * @retval ::WIMLIB_ERR_READ * A unexpected end-of-file or read error occurred when trying to read data * from the WIM file associated with @a 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, @@ -1574,30 +1852,16 @@ extern void wimlib_free(WIMStruct *wim); /** - * Returns the index of the bootable image of the WIM. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * - * @return - * 0 if no image is marked as bootable, or the number of the image marked - * as bootable (numbered starting at 1). + * Deprecated in favor of wimlib_get_wim_info(). */ extern int -wimlib_get_boot_idx(const WIMStruct *wim); +wimlib_get_boot_idx(const WIMStruct *wim) _wimlib_deprecated; /** - * Returns the compression type used in the WIM. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file - * - * @return - * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX, or - * ::WIMLIB_COMPRESSION_TYPE_XPRESS. + * Deprecated in favor of wimlib_get_wim_info(). */ extern int -wimlib_get_compression_type(const WIMStruct *wim); +wimlib_get_compression_type(const WIMStruct *wim) _wimlib_deprecated; /** * Converts a ::wimlib_compression_type value into a string. @@ -1669,33 +1933,31 @@ wimlib_get_image_name(const WIMStruct *wim, int image); /** - * Returns the number of images contained in a WIM. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or a split WIM part. - * - * @return - * The number of images contained in the WIM file. + * Deprecated in favor of wimlib_get_wim_info(). + */ +extern int +wimlib_get_num_images(const WIMStruct *wim) _wimlib_deprecated; + +/** + * Deprecated in favor of wimlib_get_wim_info(). */ extern int -wimlib_get_num_images(const WIMStruct *wim); +wimlib_get_part_number(const WIMStruct *wim, int *total_parts_ret) _wimlib_deprecated; /** - * Returns the part number of a WIM in a split WIM and the total number of parts - * of the split WIM. + * Get basic information about a WIM file. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @param total_parts_ret - * If non-@c NULL, the total number of parts in the split WIM (1 for - * non-split WIMs) is written to this location. - * + * Pointer to the ::WIMStruct for a WIM file. It may be for either a + * standalone WIM or part of a split WIM. + * @param info + * A ::wimlib_wim_info structure that will be filled in with information + * about the WIM file. * @return - * The part number of the WIM (1 for non-split WIMs) + * 0 */ extern int -wimlib_get_part_number(const WIMStruct *wim, int *total_parts_ret); +wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); /** * Initialization function for wimlib. Call before using any other wimlib @@ -1722,18 +1984,10 @@ extern void wimlib_global_cleanup(void); /** - * Returns true if the WIM has an integrity table. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @return - * @c true if the WIM has an integrity table; @c false otherwise. If @a - * wim is a ::WIMStruct created with wimlib_create_new_wim() rather than - * wimlib_open_wim(), @c false will be returned, even if wimlib_write() has - * been called on @a wim with ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY set. + * Deprecated in favor of wimlib_get_wim_info(). */ extern bool -wimlib_has_integrity_table(const WIMStruct *wim); +wimlib_has_integrity_table(const WIMStruct *wim) _wimlib_deprecated; /** * Determines if an image name is already used by some image in the WIM. @@ -1751,6 +2005,76 @@ wimlib_has_integrity_table(const WIMStruct *wim); extern bool wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); +/** + * Iterate through a file or directory tree in the WIM image. By specifying + * appropriate flags and a callback function, you can get the attributes of a + * file in the WIM, get a directory listing, or even get a listing of the entire + * WIM image. + * + * @param wim + * Pointer to the ::WIMStruct for a standalone WIM file, or part 1 of a + * split WIM. + * + * @param image + * The 1-based number of the image in @a wim that contains the files or + * directories to iterate over. + * + * @param path + * Path in the WIM image at which to do the iteration. + * + * @param flags + * Bitwise OR of ::WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE and/or + * ::WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN. + * + * @param cb + * A callback function that will receive each directory entry. + * + * @param user_ctx + * An extra parameter that will always be passed to the callback function + * @a cb. + * + * @return Normally, returns 0 if all calls to @a cb returned 0; otherwise the + * first nonzero value that was returned from @a cb. However, additional error + * codes may be returned, including the following: + * + * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST + * @a path did not exist in the WIM image. + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate memory needed to create a ::wimlib_dir_entry. + */ +extern int +wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, + int flags, + wimlib_iterate_dir_tree_callback_t cb, void *user_ctx); + +/** + * Iterate through the lookup table of a WIM file. This can be used to directly + * get a listing of the unique resources contained in a WIM file. Both file + * resources and metadata resources are included. + * + * @param wim + * Pointer to the ::WIMStruct of a standalone WIM file or a split WIM part. + * Note: metadata resources will only be included if the WIM is standalone + * or the first part of the split WIM. + * + * @param flags + * Reserved; set to 0. + * + * @param cb + * A callback function that will receive each resource. + * + * @param user_ctx + * An extra parameter that will always be passed to the callback function + * @a cb. + * + * @return 0 if all calls to @a cb returned 0; otherwise the first nonzero value + * that was returned from @a cb. + */ +extern int +wimlib_iterate_lookup_table(WIMStruct *wim, int flags, + wimlib_iterate_lookup_table_callback_t cb, + void *user_ctx); + /** * Joins a split WIM into a stand-alone one-part WIM. * @@ -1937,6 +2261,10 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * @retval ::WIMLIB_ERR_READ * An unexpected end-of-file or read error occurred when trying to read * data from the WIM file associated with @a 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, @@ -2133,119 +2461,39 @@ extern void wimlib_print_available_images(const WIMStruct *wim, int image); /** - * Prints the full paths to all files contained in an image, or all images, in a - * WIM file. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @param image - * Which image to print files for. Can be the number of an image, or - * ::WIMLIB_ALL_IMAGES to print the files contained in all images. - * - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_DECOMPRESSION - * The metadata resource for one of the specified images could not be - * decompressed. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for one of the specified - * images is invaled. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a valid image in @a wim, and is not - * ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for one of the specified images is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for one of the specified images is invalid. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_READ - * An unexpected read error or end-of-file occurred when reading the - * metadata resource for one of the specified images. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim was not a standalone WIM and was not the first part of a split - * WIM. + * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the + * information in a way that can be accessed programatically. */ extern int -wimlib_print_files(WIMStruct *wim, int image); +wimlib_print_files(WIMStruct *wim, int image) _wimlib_deprecated; /** - * Prints detailed information from the header of a WIM file. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split WIM. - * - * @return This function has no return value. - * + * Deprecated in favor of wimlib_get_wim_info(), which provides the information + * in a way that can be accessed programatically. */ extern void -wimlib_print_header(const WIMStruct *wim); +wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; /** - * Prints the lookup table of a WIM file. The lookup table maps SHA1 message - * digests, as found in the directory entry tree in the WIM file, to file - * resources in the WIM file. This table includes one entry for each unique - * file in the WIM, so it can be quite long. There is only one lookup table per - * WIM file, but each split WIM part has its own lookup table. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * - * @return This function has no return value. + * Deprecated in favor of wimlib_iterate_lookup_table(), which provides the + * information in a way that can be accessed programatically. */ extern void -wimlib_print_lookup_table(WIMStruct *wim); +wimlib_print_lookup_table(WIMStruct *wim) _wimlib_deprecated; /** - * Prints the metadata of the specified image in a WIM file. The metadata - * consists of the security data as well as the directory entry tree. Each - * image has its own metadata. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @param image - * Which image to print the metadata for. Can be the number of an image, - * or ::WIMLIB_ALL_IMAGES to print the metadata for all images in the WIM. - * - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_DECOMPRESSION - * The metadata resource for one of the specified images could not be - * decompressed. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for one of the specified - * images is invaled. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a valid image in @a wim, and is not - * ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for one of the specified images is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for one of the specified images is invalid. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_READ - * An unexpected read error or end-of-file occurred when reading the - * metadata resource for one of the specified images. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim was not a standalone WIM and was not the first part of a split - * WIM. + * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the + * information in a way that can be accessed programatically. */ extern int -wimlib_print_metadata(WIMStruct *wim, int image); +wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; /** - * Prints some basic information about a WIM file. All information printed by - * this function is also printed by wimlib_print_header(), but - * wimlib_print_wim_information() prints some of this information more concisely - * and in a more readable form. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * - * @return This function has no return value. + * Deprecated in favor of wimlib_get_wim_info(), which provides the information + * in a way that can be accessed programatically. */ extern void -wimlib_print_wim_information(const WIMStruct *wim); +wimlib_print_wim_information(const WIMStruct *wim) _wimlib_deprecated; /** * Translates a string specifying the name or number of an image in the WIM into @@ -2278,23 +2526,10 @@ wimlib_resolve_image(WIMStruct *wim, const wimlib_tchar *image_name_or_num); /** - * Sets which image in the WIM is marked as bootable. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @param boot_idx - * The number of the image to mark as bootable, or 0 to mark no image as - * bootable. - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a boot_idx does not specify an existing image in @a wim, and it was not - * 0. - * @retval ::WIMLIB_ERR_WIM_IS_READONLY - * @a wim is considered read-only because of any of the reasons mentioned - * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. + * Deprecated in favor of wimlib_set_wim_info(). */ extern int -wimlib_set_boot_idx(WIMStruct *wim, int boot_idx); +wimlib_set_boot_idx(WIMStruct *wim, int boot_idx) _wimlib_deprecated; /** * Changes the description of an image in the WIM. @@ -2323,6 +2558,36 @@ extern int wimlib_set_image_descripton(WIMStruct *wim, int image, const wimlib_tchar *description); +/** + * Set basic information about a WIM. + * + * @param wim + * A WIMStruct for a standalone WIM file. + * @param info + * A struct ::wimlib_wim_info that contains the information to set. Only + * the information explicitly specified in the @a 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, + * ::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG. + * + * @return 0 on success; nonzero on failure. + * @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. However, as a special case, if you are using + * ::WIMLIB_CHANGE_READONLY_FLAG to unset the readonly flag, then this + * function will not fail due to the readonly flag being previously set. + * @retval ::WIMLIB_ERR_IMAGE_COUNT + * ::WIMLIB_CHANGE_BOOT_INDEX was specified, but + * ::wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image + * index in the WIM. + */ +extern int +wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info, + int which); + /** * Changes what is written in the \ element in the WIM XML data * (something like "Core" or "Ultimate") @@ -2346,8 +2611,8 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * @a 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_flags(WIMStruct *wim, int image, - const wimlib_tchar *flags); +extern int +wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); /** * Changes the name of an image in the WIM.