X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=6842e35da43178980dff61213a2df455a12ef8ad;hb=ae7d142ac04cf51ba134750f3338f43af285a433;hp=98f3d0234535c5c7ba3b943c10351d811c715d47;hpb=53588a19dc7176736cf1791b75584314cab3d8f2;p=wimlib

diff --git a/include/wimlib.h b/include/wimlib.h
index 98f3d023..6842e35d 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -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
@@ -2254,7 +2254,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 +2493,12 @@ 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,
 };
 
 
@@ -2715,13 +2717,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 <tt>n</tt> images, then
+ * the source image(s) will be appended, in order, starting at destination index
+ * <tt>n + 1</tt>.  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 +2758,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 +3080,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);
@@ -3466,6 +3478,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 +3776,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,
@@ -4353,6 +4365,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