X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=09a427985469274526e3a80172aafcf4551dedc0;hp=712202d4db8ed7873c8ae41dfc01860b8c696f93;hb=0ae7e5538476723feb14f07a478b92210e24a21b;hpb=be5acf31aa8292dcd4a2829492faefb0b200d28f diff --git a/include/wimlib.h b/include/wimlib.h index 712202d4..09a42798 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 @@ -383,7 +379,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" { @@ -1298,21 +1294,27 @@ struct wimlib_wim_info { */ uint32_t opened_from_file : 1; - /** 1 iff this WIM file is considered readonly for any reason. */ + /** 1 iff this WIM file is considered readonly for any reason (e.g. the + * "readonly" header flag is set, or this is part of a split WIM, or + * filesystem permissions deny writing) */ uint32_t is_readonly : 1; - /** 1 iff reparse-point fixups are enabled for one or more images in - * this WIM file. */ + /** 1 iff the "reparse point fix" flag is set in this WIM's header */ uint32_t has_rpfix : 1; - /** 1 iff this WIM file is marked read-only in its header. */ + /** 1 iff the "readonly" flag is set in this WIM's header */ uint32_t is_marked_readonly : 1; - /** 1 iff this WIM file is part of a spanned set. */ + /** 1 iff the "spanned" flag is set in this WIM's header */ uint32_t spanned : 1; + /** 1 iff the "write in progress" flag is set in this WIM's header */ uint32_t write_in_progress : 1; + + /** 1 iff the "metadata only" flag is set in this WIM's header */ uint32_t metadata_only : 1; + + /** 1 iff the "resource only" flag is set in this WIM's header */ uint32_t resource_only : 1; /** 1 iff this WIM file is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */ @@ -1938,6 +1940,31 @@ 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. */ +#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. */ +#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. */ +#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. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000 + /** @} */ /** @addtogroup G_mounting_wim_images * @{ */ @@ -2451,6 +2478,7 @@ enum wimlib_error_code { WIMLIB_ERR_NOT_A_MOUNTPOINT = 80, WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81, WIMLIB_ERR_FVE_LOCKED_VOLUME = 82, + WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83, }; @@ -2564,15 +2592,9 @@ wimlib_add_image(WIMStruct *wim, * capture for full details on how this mode works. * * In addition to the error codes that wimlib_add_image() can return, - * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY - * when trying to overlay a non-directory on a directory or when otherwise - * trying to overlay multiple conflicting files to the same location in the WIM - * image. It will also return ::WIMLIB_ERR_INVALID_PARAM if - * ::WIMLIB_ADD_FLAG_NTFS was specified in @p add_flags but there - * was not exactly one capture source with the target being the root directory. - * (In this respect, there is no advantage to using - * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting - * NTFS mode.) + * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY when + * trying to overlay a non-directory on a directory or when otherwise trying to + * overlay multiple conflicting files to the same location in the WIM image. */ extern int wimlib_add_image_multisource(WIMStruct *wim, @@ -2832,7 +2854,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. * @@ -4250,20 +4273,16 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * 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_INVALID_CAPTURE_CONFIG - * The capture configuration structure specified for an add command was - * invalid. + * The contents of a capture configuration file were invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image did not exist in @p wim. * @retval ::WIMLIB_ERR_INVALID_OVERLAY * Attempted to perform an add command that conflicted with previously * existing files in the WIM when an overlay was attempted. * @retval ::WIMLIB_ERR_INVALID_PARAM - * An unknown operation type was specified in the update commands; or, - * attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set - * in the @p add_flags, but the same image had previously already been - * added from an NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and - * ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @p add_flags for one add - * command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were + * An unknown operation type was specified in the update commands; or, both + * ::WIMLIB_ADD_FLAG_RPFIX and ::WIMLIB_ADD_FLAG_NORPFIX were specified in + * the @p add_flags for one add command; or ::WIMLIB_ADD_FLAG_RPFIX were * specified in the @p add_flags for an add command in which @p * wim_target_path was not the root directory of the WIM image. * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA @@ -4301,6 +4320,8 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * @retval ::WIMLIB_ERR_STAT * While executing an add command, failed to get attributes for a file or * directory. + * @retval ::WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG + * A capture configuration file could not be read. * @retval ::WIMLIB_ERR_UNSUPPORTED * ::WIMLIB_ADD_FLAG_NTFS was specified in the @p add_flags for an update * command, but wimlib was configured with the @c --without-ntfs-3g flag;