X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=260f03e88fca6073295b9e95389936b80a0c776a;hp=09a427985469274526e3a80172aafcf4551dedc0;hb=5c39470a315a563ef896bb58e7560164cc24df04;hpb=39edbeed8b1d86646e7a8e457f39244c54b1cf14 diff --git a/include/wimlib.h b/include/wimlib.h index 09a42798..260f03e8 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -259,8 +259,9 @@ * * 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. @@ -1941,28 +1942,25 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 /** - * EXPERIMENTAL, 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. This flag is currently experimental and may be changed or removed - * in future releases of wimlib. */ + * 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. This flag is currently experimental and may be changed - * or removed in future releases of wimlib. */ + * 8192 byte chunks. */ #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with - * 16384 byte chunks. This flag is currently experimental and may be changed - * or removed in future releases of wimlib. */ + * 16384 byte chunks. */ #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with - * 32768 byte chunks. This flag is currently experimental and may be changed - * or removed in future releases of wimlib. */ + * 32768 byte chunks. */ #define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000 /** @} */ @@ -2432,7 +2430,6 @@ enum wimlib_error_code { 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, @@ -2479,6 +2476,7 @@ enum wimlib_error_code { WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81, WIMLIB_ERR_FVE_LOCKED_VOLUME = 82, WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83, + WIMLIB_ERR_WIM_IS_INCOMPLETE = 84, }; @@ -3133,6 +3131,34 @@ wimlib_get_image_description(const WIMStruct *wim, int image); 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 for the WIM. + * @param image + * 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. The [ character is reserved for future use. + * + * @return + * 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_property(const WIMStruct *wim, int image, + const wimlib_tchar *property_name); + /** * @ingroup G_general * @@ -3526,6 +3552,9 @@ wimlib_mount_image(WIMStruct *wim, * @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 @@ -3559,22 +3588,21 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, /** * @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 + * 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. * @@ -3960,6 +3988,37 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); 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. + * @param image + * 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(). + * @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_INVALID_IMAGE + * @p image does not exist in @p wim. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p property_name has an unsupported format. + */ +extern int +wimlib_set_image_property(WIMStruct *wim, int image, + const wimlib_tchar *property_name, + const wimlib_tchar *property_value); + /** * @ingroup G_general *