X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=bdb2c33ea88e4be8fd6401d7f4929481d34426fc;hp=63cc3e200c2b0e486a24ec65606019f3d18f7d15;hb=1e746d17086bb6dcf89906b710d60673261a9935;hpb=8b709192cd2811b83c248fbe61ca4f11ee9de797 diff --git a/include/wimlib.h b/include/wimlib.h index 63cc3e20..bdb2c33e 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.1, 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 1 +#define WIMLIB_PATCH_VERSION 2 #ifdef __cplusplus extern "C" { @@ -1944,28 +1941,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 /** @} */ @@ -2435,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, @@ -2482,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, }; @@ -3136,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 * @@ -3529,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 @@ -3963,6 +3989,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 *