X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=ac42e81a8f7f9f24b288ae00bf30d79915e5e010;hp=ee0bb9bb459a5aa5eaa834d1355cad49d228f4a0;hb=21da2526eff64cdb8e3cb509d34af182d764c701;hpb=50a73294df28e50188565ea88b72ed13c87ce4bf diff --git a/include/wimlib.h b/include/wimlib.h index ee0bb9bb..ac42e81a 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -3,52 +3,48 @@ * @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 http://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.0, a C + * This is the documentation for the library interface of wimlib 1.8.2, 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="http://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 http://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 + * http://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 - * source code of wimlib-imagex, which is complicated but uses most + * href="http://wimlib.net/gitlist/wimlib/blob/master/programs/imagex.c"> source + * code of wimlib-imagex, which is complicated but uses most * capabilities of wimlib. * * @section backwards_compatibility Backwards Compatibility @@ -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. @@ -383,7 +380,7 @@ #define WIMLIB_MINOR_VERSION 8 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 0 +#define WIMLIB_PATCH_VERSION 2 #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 @@ -1944,6 +1941,28 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 +/** + * 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. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000 + +/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with + * 16384 byte chunks. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000 + +/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with + * 32768 byte chunks. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000 + /** @} */ /** @addtogroup G_mounting_wim_images * @{ */ @@ -2235,12 +2254,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 * @{ */ @@ -2251,12 +2288,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, @@ -2411,7 +2449,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, @@ -2458,6 +2495,8 @@ 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, + WIMLIB_ERR_COMPACTION_NOT_POSSIBLE = 85, }; @@ -2833,7 +2872,8 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags. * @retval ::WIMLIB_ERR_WIMBOOT * ::WIMLIB_EXTRACT_FLAG_WIMBOOT was specified in @p extract_flags, but - * there was a problem creating WIMBoot pointer files. + * there was a problem creating WIMBoot pointer files or registering a + * source WIM file with the Windows Overlay Filesystem (WOF) driver. * @retval ::WIMLIB_ERR_WRITE * Failed to write data to a file being extracted. * @@ -3111,6 +3151,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 * @@ -3504,6 +3572,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 @@ -3537,22 +3608,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. * @@ -3938,6 +4010,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 *