X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=6a1fbde6df13394577a98db27e56f78d5dc3119f;hp=5bed913b3cef00c015a1d7045f32abff404e2a33;hb=e2fb429bf5041bcf5cde3f523bb7f2543586c0f9;hpb=c5e4bd4c75bf1f1e8c75c460853340a15917d55c diff --git a/include/wimlib.h b/include/wimlib.h index 5bed913b..6a1fbde6 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -3,7 +3,7 @@ * @brief External header for wimlib. * * This file contains comments for generating documentation with Doxygen. The - * built HTML documentation can be viewed at http://wimlib.net/apidoc. Make + * 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. */ @@ -11,19 +11,19 @@ /** * @mainpage * - * This is the documentation for the library interface of wimlib 1.8.2, 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://wimlib.net. Install the library by + * 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. @@ -32,8 +32,8 @@ * * Download the Windows binary distribution with the appropriate architecture * (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 + * 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". * @@ -43,8 +43,8 @@ * distribution. * * There is also the source - * code of wimlib-imagex, which is complicated but uses most + * 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. * * @section backwards_compatibility Backwards Compatibility @@ -377,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 2 +#define WIMLIB_PATCH_VERSION 0 #ifdef __cplusplus extern "C" { @@ -856,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; @@ -1747,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 @@ -1904,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 @@ -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 @@ -2505,6 +2498,7 @@ enum wimlib_error_code { WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86, WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87, WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88, + WIMLIB_ERR_SNAPSHOT_FAILURE = 89, }; @@ -3133,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); @@ -3153,18 +3136,10 @@ wimlib_get_image_description(const WIMStruct *wim, int image); /** * @ingroup G_wim_information * - * Get the name 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 name. - * - * @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. + * 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); @@ -3186,7 +3161,11 @@ wimlib_get_image_name(const WIMStruct *wim, int image); * "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. + * 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 property's value as a ::wimlib_tchar string, or @c NULL if there is @@ -3963,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, @@ -3986,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); @@ -4007,23 +3962,8 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); /** * @ingroup G_modifying_wims * - * Change the name 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 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. - * - * @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. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * 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); @@ -4043,16 +3983,27 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); * @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 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. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p property_name has an unsupported format. + * @p property_name has an unsupported format, or @p property_name included + * a bracketed index that was too high. */ extern int wimlib_set_image_property(WIMStruct *wim, int image,