X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=6a1fbde6df13394577a98db27e56f78d5dc3119f;hp=63cc3e200c2b0e486a24ec65606019f3d18f7d15;hb=e2fb429bf5041bcf5cde3f523bb7f2543586c0f9;hpb=8b709192cd2811b83c248fbe61ca4f11ee9de797 diff --git a/include/wimlib.h b/include/wimlib.h index 63cc3e20..6a1fbde6 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -3,51 +3,47 @@ * @brief External header for wimlib. * * This file contains comments for generating documentation with Doxygen. The - * built HTML documentation can be viewed at http://wimlib.sourceforge.net. - * Make sure to see the Modules page to make more - * sense of the declarations in this header. + * built HTML documentation can be viewed at https://wimlib.net/apidoc. Make + * sure to see the Modules page to make more sense of + * the declarations in this header. */ /** * @mainpage * - * This is the documentation for the library interface of wimlib 1.8.1, a C + * This is the documentation for the library interface of wimlib 1.9.0, a C * library for creating, modifying, extracting, and mounting files in the * Windows Imaging Format. This documentation is intended for developers only. * If you have installed wimlib and want to know how to use the @b wimlib-imagex * program, please see the manual pages and also the README + * href="https://wimlib.net/gitlist/wimlib/blob/master/README">README * file. * * @section sec_installing Installing * * @subsection UNIX * - * Download the source code from http://sourceforge.net/projects/wimlib/files. - * Install the library by running configure && make && sudo make install. - * See the README for information about configuration options. To use wimlib in - * your program after installing it, include wimlib.h and link your program with - * -lwim. + * Download the source code from https://wimlib.net. Install the library by + * running configure && make && sudo make install. See the README for + * information about configuration options. To use wimlib in your program after + * installing it, include wimlib.h and link your program with -lwim. * * @subsection Windows * * Download the Windows binary distribution with the appropriate architecture - * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from http://sourceforge.net/projects/wimlib/files. - * Link your program with the libwim-15.dll file. Make sure to also download - * the source code so you can get wimlib.h, as it is not included in the binary - * distribution. If you need to access the DLL from other programming - * languages, note that the calling convention is "cdecl". + * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from + * https://wimlib.net. Link your program with the libwim-15.dll file. Make + * sure to also download the source code so you can get wimlib.h, as it is not + * included in the binary distribution. If you need to access the DLL from + * other programming languages, note that the calling convention is "cdecl". * * @section sec_examples Examples * - * Several examples are located in the examples - * directory of the source distribution. + * Several examples are located in the "examples" directory of the source + * distribution. * * There is also the + * href="https://wimlib.net/gitlist/wimlib/blob/master/programs/imagex.c"> * source code of wimlib-imagex, which is complicated but uses most * capabilities of wimlib. * @@ -263,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. @@ -380,10 +377,10 @@ #define WIMLIB_MAJOR_VERSION 1 /** Minor version of the library (for example, the 2 in 1.2.5). */ -#define WIMLIB_MINOR_VERSION 8 +#define WIMLIB_MINOR_VERSION 9 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 1 +#define WIMLIB_PATCH_VERSION 0 #ifdef __cplusplus extern "C" { @@ -506,7 +503,7 @@ enum wimlib_compression_type { * produce a better compression ratio, and work more quickly, than the * implementation in Microsoft's WIMGAPI (as of Windows 8.1). There is * limited support for non-default compression levels, but compression - * will be noticably faster if you choose a level < 35. + * will be noticeably faster if you choose a level < 35. * * If using wimlib_create_compressor() to create an LZMS compressor * directly, the @p max_block_size parameter may be any positive value @@ -779,7 +776,7 @@ union wimlib_progress_info { uint64_t completed_streams; /** The number of threads being used for data compression; or, - * if no compression is being peformed, this will be 1. */ + * if no compression is being performed, this will be 1. */ uint32_t num_threads; /** The compression type being used, as one of the @@ -859,13 +856,11 @@ union wimlib_progress_info { uint64_t num_dirs_scanned; /** The number of non-directories scanned so far, not counting - * excluded/unsupported files. If a file has multiple names - * (hard links), it is only counted one time. */ + * excluded/unsupported files. */ uint64_t num_nondirs_scanned; /** The number of bytes of file data detected so far, not - * counting excluded/unsupported files. If a file has multiple - * names (hard links), its data is counted only one time. */ + * counting excluded/unsupported files. */ uint64_t num_bytes_scanned; } scan; @@ -1724,6 +1719,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * * 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 @@ -1745,23 +1745,27 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000 -/* Note: the WIMLIB_ADD_IMAGE_FLAG names are retained for source compatibility. - * Use the WIMLIB_ADD_FLAG names in new code. */ -#define WIMLIB_ADD_IMAGE_FLAG_NTFS WIMLIB_ADD_FLAG_NTFS -#define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE WIMLIB_ADD_FLAG_DEREFERENCE -#define WIMLIB_ADD_IMAGE_FLAG_VERBOSE WIMLIB_ADD_FLAG_VERBOSE -#define WIMLIB_ADD_IMAGE_FLAG_BOOT WIMLIB_ADD_FLAG_BOOT -#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA WIMLIB_ADD_FLAG_UNIX_DATA -#define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS WIMLIB_ADD_FLAG_NO_ACLS -#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS WIMLIB_ADD_FLAG_STRICT_ACLS -#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE -#define WIMLIB_ADD_IMAGE_FLAG_RPFIX WIMLIB_ADD_FLAG_RPFIX -#define WIMLIB_ADD_IMAGE_FLAG_NORPFIX WIMLIB_ADD_FLAG_NORPFIX -#define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \ - WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE -#define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG -#define WIMLIB_ADD_IMAGE_FLAG_WIMBOOT WIMLIB_ADD_FLAG_WIMBOOT +/** + * Since wimlib v1.9.0: create a temporary filesystem snapshot of the source + * directory and add the files from it. Currently, this option is only + * supported on Windows, where it uses the Volume Shadow Copy Service (VSS). + * Using this option, you can create a consistent backup of the system volume of + * a running Windows system without running into problems with locked files. + * For the VSS snapshot to be successfully created, your application must be run + * as an Administrator, and it cannot be run in WoW64 mode (i.e. if Windows is + * 64-bit, then your application must be 64-bit as well). + */ +#define WIMLIB_ADD_FLAG_SNAPSHOT 0x00008000 +/** + * Since wimlib v1.9.0: permit the library to discard file paths after the + * initial scan. If the application won't use + * WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES while writing the WIM archive, + * this flag can be used to allow the library to enable optimizations such as + * opening files by inode number rather than by path. Currently this only makes + * a difference on Windows. + */ +#define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED 0x00010000 /** @} */ /** @addtogroup G_modifying_wims @@ -1902,9 +1906,6 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * only allows the Administrator to create symbolic links. */ #define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000 -/** Reserved for future use. */ -#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000 - /** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the * paths to extract as wildcard patterns ("globs") which may contain the * wildcard characters @c ? and @c *. The @c ? character matches any @@ -1944,28 +1945,26 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 -/** EXPERIMENTAL and only works on Windows 10 and later: compress the extracted - * files using the System Compression feature (when possible). System - * Compression is only supported by Windows 10 or later. 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 /** @} */ @@ -2245,12 +2244,6 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_WRITE_FLAG_SOLID 0x00001000 -/** - * Deprecated: this is the old name for ::WIMLIB_WRITE_FLAG_SOLID, retained for - * source compatibility. - */ -#define WIMLIB_WRITE_FLAG_PACK_STREAMS WIMLIB_WRITE_FLAG_SOLID - /** * Send ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM * file. This is only needed in the unusual case that the library user needs to @@ -2259,12 +2252,30 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000 /** - * Do not consider content similarily when arranging file data for solid + * Do not consider content similarity when arranging file data for solid * compression. Providing this flag will typically worsen the compression * ratio, so only provide this flag if you know what you are doing. */ #define WIMLIB_WRITE_FLAG_NO_SOLID_SORT 0x00004000 +/** + * Since wimlib v1.8.3 and for wimlib_overwrite() only: unsafely compact + * the WIM file in-place, without appending. Existing resources are shifted + * down to fill holes and new resources are appended as needed. The WIM file is + * truncated to its final size, which may shrink the on-disk file. This + * operation cannot be safely interrupted. If the operation is interrupted, + * then the WIM file will be corrupted, and it may be impossible (or at least + * very difficult) to recover any data from it. Users of this flag are expected + * to know what they are doing and assume responsibility for any data corruption + * that may result. + * + * If the WIM file cannot be compacted in-place because of its structure, its + * layout, or other requested write parameters, then wimlib_overwrite() fails + * with ::WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry + * the operation without this flag. + */ +#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT 0x00008000 + /** @} */ /** @addtogroup G_general * @{ */ @@ -2275,12 +2286,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001 /** Windows-only: do not attempt to acquire additional privileges (currently - * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and - * SeTakeOwnershipPrivilege) when initializing the library. This flag is - * intended for the case where the calling program manages these privileges - * itself. Note: by default, no error is issued if privileges cannot be - * acquired, although related errors may be reported later, depending on if the - * operations performed actually require additional privileges or not. */ + * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, + * SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the + * library. This flag is intended for the case where the calling program + * manages these privileges itself. Note: by default, no error is issued if + * privileges cannot be acquired, although related errors may be reported later, + * depending on if the operations performed actually require additional + * privileges or not. */ #define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002 /** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, @@ -2435,7 +2447,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, @@ -2480,8 +2491,14 @@ enum wimlib_error_code { WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79, WIMLIB_ERR_NOT_A_MOUNTPOINT = 80, WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81, - WIMLIB_ERR_FVE_LOCKED_VOLUME = 82, + WIMLIB_ERR_FVE_LOCKED_VOLUME = 82, WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83, + WIMLIB_ERR_WIM_IS_INCOMPLETE = 84, + WIMLIB_ERR_COMPACTION_NOT_POSSIBLE = 85, + WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86, + WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87, + WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88, + WIMLIB_ERR_SNAPSHOT_FAILURE = 89, }; @@ -2700,13 +2717,17 @@ wimlib_delete_path(WIMStruct *wim, int image, * * 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 n images, then + * the source image(s) will be appended, in order, starting at destination index + * n + 1. 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 @@ -2737,6 +2758,9 @@ wimlib_delete_path(WIMStruct *wim, int image, * * @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. @@ -3056,11 +3080,14 @@ wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); /** * @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); @@ -3100,19 +3127,8 @@ wimlib_get_error_string(enum wimlib_error_code code); /** * @ingroup G_wim_information * - * Get the description of the specified image. - * - * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). - * @param image - * The 1-based index of the image for which to query the description. - * - * @return - * The description of the image, or @c NULL if there is no such image, or - * @c NULL if the specified image has no description. The string may not - * remain valid after later library calls, so the caller should duplicate - * it if needed. + * Get the description of the specified image. Equivalent to + * wimlib_get_image_property(wim, image, "DESCRIPTION"). */ extern const wimlib_tchar * wimlib_get_image_description(const WIMStruct *wim, int image); @@ -3120,21 +3136,45 @@ wimlib_get_image_description(const WIMStruct *wim, int image); /** * @ingroup G_wim_information * - * Get the name of the specified image. + * Get the name of the specified image. Equivalent to + * wimlib_get_image_property(wim, image, "NAME"), except that + * wimlib_get_image_name() will return an empty string if the image is unnamed + * whereas wimlib_get_image_property() may return @c NULL in that case. + */ +extern const wimlib_tchar * +wimlib_get_image_name(const WIMStruct *wim, int image); + +/** + * @ingroup G_wim_information + * + * Since wimlib v1.8.3: get a per-image property from the WIM's XML document. + * This is an alternative to wimlib_get_image_name() and + * wimlib_get_image_description() which allows getting any simple string + * property. * * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). + * Pointer to the ::WIMStruct for the WIM. * @param image - * The 1-based index of the image for which to query the name. + * The 1-based index of the image for which to get the property. + * @param property_name + * The name of the image property, for example "NAME", "DESCRIPTION", or + * "TOTALBYTES". The name can contain forward slashes to indicate a nested + * XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD + * element nested within the VERSION element nested within the WINDOWS + * element. Since wimlib v1.9.0, a bracketed number can be used to + * indicate one of several identically-named elements; for example, + * "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element + * nested within the "WINDOWS/LANGUAGES" element. Note that element names + * are case sensitive. * * @return - * The name of the image, or @c NULL if there is no such image, or an empty - * string if the image is unnamed. The string may not remain valid after - * later library calls, so the caller should duplicate it if needed. + * The property's value as a ::wimlib_tchar string, or @c NULL if there is + * no such property. The string may not remain valid after later library + * calls, so the caller should duplicate it if needed. */ extern const wimlib_tchar * -wimlib_get_image_name(const WIMStruct *wim, int image); +wimlib_get_image_property(const WIMStruct *wim, int image, + const wimlib_tchar *property_name); /** * @ingroup G_general @@ -3423,6 +3463,10 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, * 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 @@ -3529,6 +3573,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 @@ -3562,22 +3609,23 @@ 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 + * 3. Compaction: normally should not be used; see + * ::WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details. + * + * Append mode is often much faster than a full rebuild, but it wastes some + * amount of space due to leaving "holes" in the WIM file. Because of the + * greater efficiency, wimlib_overwrite() normally defaults to append mode. + * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full + * rebuild. In addition, if wimlib_delete_image() has been used on the + * ::WIMStruct, then the default mode switches to rebuild mode, and * ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append * mode. * @@ -3713,11 +3761,7 @@ wimlib_reference_resource_files(WIMStruct *wim, * @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, @@ -3898,20 +3942,8 @@ wimlib_set_error_file_by_name(const wimlib_tchar *path); /** * @ingroup G_modifying_wims * - * Change the description of a WIM image. - * - * @param wim - * Pointer to the ::WIMStruct for the WIM. - * @param image - * The 1-based index of the image for which to change the description. - * @param description - * The new description to give the image. It may be @c NULL, which - * indicates that the image is to be given no description. - * - * @return 0 on success; a ::wimlib_error_code value on failure. - * - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * Change the description of a WIM image. Equivalent to + * wimlib_set_image_property(wim, image, "DESCRIPTION", description). */ extern int wimlib_set_image_descripton(WIMStruct *wim, int image, @@ -3921,20 +3953,8 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * @ingroup G_modifying_wims * * Change what is stored in the \ element in the WIM XML document - * (usually something like "Core" or "Ultimate") - * - * @param wim - * Pointer to the ::WIMStruct for the WIM. - * @param image - * The 1-based index of the image for which to change the flags. - * @param flags - * The new \ element to give the image. It may be @c NULL, which - * indicates that the image is to be given no \ element. - * - * @return 0 on success; a ::wimlib_error_code value on failure. - * - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * (usually something like "Core" or "Ultimate"). Equivalent to + * wimlib_set_image_property(wim, image, "FLAGS", flags). */ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); @@ -3942,26 +3962,53 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); /** * @ingroup G_modifying_wims * - * Change the name of a WIM image. + * Change the name of a WIM image. Equivalent to + * wimlib_set_image_property(wim, image, "NAME", name). + */ +extern int +wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); + +/** + * @ingroup G_modifying_wims + * + * Since wimlib v1.8.3: add, modify, or remove a per-image property from the + * WIM's XML document. This is an alternative to wimlib_set_image_name(), + * wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows + * manipulating any simple string property. * * @param wim - * Pointer to the ::WIMStruct for the WIM. + * Pointer to the ::WIMStruct for the WIM. * @param image - * The 1-based index of the image for which to change the name. - * @param name - * New name to give the new image. If @c NULL or empty, the new image is - * given no name. Otherwise, it must specify a name that does not already - * exist in @p wim. + * The 1-based index of the image for which to set the property. + * @param property_name + * The name of the image property in the same format documented for + * wimlib_get_image_property(). + *
+ * Note: if creating a new element using a bracketed index such as + * "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified + * is one greater than the number of existing elements with that same name, + * excluding the index. That means that if you are adding a list of new + * elements, they must be added sequentially from the first index (1) to + * the last index (n). + * @param property_value + * If not NULL and not empty, the property is set to this value. + * Otherwise, the property is removed from the XML document. * * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION - * The WIM already contains an image with the requested name. + * The user requested to set the image name (the NAME property), + * but another image in the WIM already had the requested name. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * @p image does not exist in @p wim. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p property_name has an unsupported format, or @p property_name included + * a bracketed index that was too high. */ extern int -wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); +wimlib_set_image_property(WIMStruct *wim, int image, + const wimlib_tchar *property_name, + const wimlib_tchar *property_value); /** * @ingroup G_general @@ -4275,6 +4322,9 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * @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 @@ -4381,12 +4431,13 @@ wimlib_update_image(WIMStruct *wim, * * @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