X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=094622789c07fc264ead7f6c658536a7ece9b640;hp=c5d118064fc31f101465d7cef06fcd526f38ead0;hb=51df3b63c594a7e35446d2e2e19637e54240b0b2;hpb=cf13fe6161a69db6cbf17637b60c978fd746078a
diff --git a/include/wimlib.h b/include/wimlib.h
index c5d11806..09462278 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.
*/
@@ -2288,12 +2293,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,
@@ -2492,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,
};
@@ -2714,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
@@ -2751,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.
@@ -3070,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);
@@ -3465,6 +3484,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
@@ -3759,11 +3782,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,
@@ -4352,6 +4371,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
@@ -4458,12 +4480,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