X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=10f9bb7eb36dee1ebed7284849d715c7d3666c9b;hp=98f3d0234535c5c7ba3b943c10351d811c715d47;hb=f249ba1f7198e491c8e0b794a748095cdd1278a7;hpb=53588a19dc7176736cf1791b75584314cab3d8f2 diff --git a/include/wimlib.h b/include/wimlib.h index 98f3d023..10f9bb7e 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.8.3, 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 @@ -380,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 2 +#define WIMLIB_PATCH_VERSION 3 #ifdef __cplusplus extern "C" { @@ -503,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 @@ -776,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 @@ -1721,6 +1721,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 @@ -2254,7 +2259,7 @@ 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. */ @@ -2493,10 +2498,13 @@ 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_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, }; @@ -2715,13 +2723,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 @@ -2752,6 +2764,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. @@ -3071,11 +3086,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); @@ -3168,7 +3186,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.8.4, 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 @@ -3466,6 +3488,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 @@ -3760,11 +3786,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, @@ -4025,6 +4047,13 @@ 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. @@ -4034,7 +4063,8 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *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, @@ -4353,6 +4383,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 @@ -4459,12 +4492,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