X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;ds=sidebyside;f=src%2Fwimlib.h;h=fa27fc1c27d0f55f667c70c7761584a78ae07b36;hb=8e4a9a0129dabaddef33ee0a99f7f8b221bdf483;hp=240004739c2374422923e36a4d81c284cf1f0636;hpb=c21b75e8ec69a7fa8d915faf439bdcf1389247cd;p=wimlib

diff --git a/src/wimlib.h b/src/wimlib.h
index 24000473..fa27fc1c 100644
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -134,20 +134,19 @@
  *
  * While wimlib supports the main features of WIM files, wimlib currently has
  * the following limitations:
- * - wimlib does not support "security data", which describes the access rights
- *   of the files in the WIM.  This data is very Windows-specific, and it would
- *   be difficult to do anything with it.  Microsoft's software can still read a
- *   WIM without security data, including a boot.wim for Windows PE, but <b>do
- *   not expect to be able to use wimlib to image a Windows installation and
- *   preserve file attributes</b>.
- * - There is no support for split WIMs, which have an image divided up between
- *   multiple WIM files.
+ * - wimlib does not support modifying or creating "security data", which
+ *   describes the access rights of the files in the WIM.  This data is very
+ *   Windows-specific, and it would be difficult to do anything with it.
+ *   Microsoft's software can still read a WIM without security data, including
+ *   a boot.wim for Windows PE, but <b>do not expect to be able to use wimlib to
+ *   image a Windows installation and preserve file attributes</b>.  However, by
+ *   default, wimlib will preserve security data for existing WIMs.
+ * - There is no way to directly extract or mount split WIMs.
  * - There is not yet any code to verify that there are no collisions between
  *   different files that happen to have the same SHA1 message digest.
  *   This is extremely unlikely, but could result in something bad such as a
  *   file going missing.
- * - Alternate stream entries for directory entries are ignored.  I'm not sure
- *   if these are ever used for anything important.
+ * - Alternate stream entries for directory entries are ignored.
  * - Different versions of the WIM file format, if they even exist, are
  *   unsupported.  Let me know if you notice WIM files with a different version.
  * - Chunk sizes other than 32768 are unsupported (except for uncompressed WIMs,
@@ -175,7 +174,7 @@
  * split up LZX compressed blocks, which is not yet implemented in wimlib.
  *
  * wimlib is experimental and likely contains bugs; use Microsoft's @a
- * imagex.exe if you want to make sure your WIM files are made correctly.
+ * imagex.exe if you want to make sure your WIM files are made "correctly".
  *
  * \section legal License
  *
@@ -264,6 +263,10 @@ enum wim_compression_type {
 /** Print progress information when verifying integrity table. */
 #define WIMLIB_OPEN_FLAG_SHOW_PROGRESS		0x2
 
+/** If this flag is not given, an error is issued if the WIM is part of a split
+ * WIM.  */
+#define WIMLIB_OPEN_FLAG_SPLIT_OK		0x4
+
 /**
  * Possible values of the error code returned by many functions in wimlib.
  *
@@ -289,6 +292,7 @@ enum wimlib_error_code {
 	WIMLIB_ERR_INVALID_INTEGRITY_TABLE,
 	WIMLIB_ERR_INVALID_PARAM,
 	WIMLIB_ERR_INVALID_RESOURCE_SIZE,
+	WIMLIB_ERR_INVALID_SECURITY_DATA,
 	WIMLIB_ERR_LINK,
 	WIMLIB_ERR_MKDIR,
 	WIMLIB_ERR_MQUEUE,
@@ -300,7 +304,8 @@ enum wimlib_error_code {
 	WIMLIB_ERR_OPENDIR,
 	WIMLIB_ERR_READ,
 	WIMLIB_ERR_RENAME,
-	WIMLIB_ERR_SPLIT,
+	WIMLIB_ERR_SPLIT_INVALID,
+	WIMLIB_ERR_SPLIT_UNSUPPORTED,
 	WIMLIB_ERR_STAT,
 	WIMLIB_ERR_TIMEOUT,
 	WIMLIB_ERR_UNKNOWN_VERSION,
@@ -639,6 +644,20 @@ extern const char *wimlib_get_image_name(const WIMStruct *wim, int image);
  */
 extern int wimlib_get_num_images(const WIMStruct *wim);
 
+/**
+ * Gets the part number of the wim (in a split WIM).
+ *
+ * @param wim
+ * 	Pointer to the ::WIMStruct for a WIM file.
+ * @param total_parts_ret
+ * 	If non-@c NULL, the total number of parts in the split WIM (1 for
+ * 	non-split WIMs) is written to this location.
+ *
+ * @return 
+ * 	The part number of the WIM (1 for non-split WIMs)
+ */
+extern int wimlib_get_part_number(const WIMStruct *wim, int *total_parts_ret);
+
 /**
  * Returns true if the WIM has an integrity table.
  *
@@ -647,7 +666,7 @@ extern int wimlib_get_num_images(const WIMStruct *wim);
  * @return
  * 	@c true if the WIM has an integrity table; false otherwise.
  */
-bool wimlib_has_integrity_table(const WIMStruct *wim);
+extern bool wimlib_has_integrity_table(const WIMStruct *wim);
 
 
 /**
@@ -664,6 +683,38 @@ bool wimlib_has_integrity_table(const WIMStruct *wim);
  */
 extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name);
 
+/**
+ * Joins a set of split WIMs into a one-part WIM.
+ *
+ * @param swms
+ * 	An array of strings that give the filenames of all parts of the split
+ * 	WIM.
+ * @param num_swms
+ * 	Number of filenames in @a swms.
+ * @param output_path
+ * 	The path to write the one-part WIM to.
+ * @param flags
+ * 	::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY to check the split WIMs' integrity
+ * 	tables (if present) when opening them, and include an integrity table in
+ * 	the output WIM.
+ *
+ * @return 0 on success; nonzero on error.  This function may return any value
+ * returned by wimlib_open_wim() except ::WIMLIB_ERR_SPLIT_UNSUPPORTED, as well
+ * as the following error codes:
+ *
+ * @retval ::WIMLIB_ERR_SPLIT_INVALID
+ * 	The split WIMs do not form a valid WIM because they do not include all
+ * 	the parts of the original WIM, there are duplicate parts, or not all the
+ * 	parts have the same GUID and compression type.
+ * @retval ::WIMLIB_ERR_WRITE
+ * 	An error occurred when trying to write data to the new WIM at @a output_path.
+ *
+ * Note that this function merely copies the resources, so it will not check to
+ * see if the resources, including the metadata resource, are valid or not.
+ */
+extern int wimlib_join(const char **swms, int num_swms,
+		       const char *output_path, int flags);
+
 /**
  * Mounts an image in a WIM file on a directory read-only or read-write.
  *
@@ -730,6 +781,11 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags);
  * 	digests given in the integrity table.
  * 	If ::WIMLIB_OPEN_FLAG_SHOW_PROGRESS is given, progress information will
  * 	be shown if the integrity of the WIM is checked.
+ * 	If ::WIMLIB_OPEN_FLAG_SPLIT_OK is given, no error will be issued if the
+ * 	WIM is part of a split WIM.  However, wimlib does not fully support
+ * 	split WIMs, so not all functions will work correctly after opening a
+ * 	split WIM.  For example, you cannot use wimlib_mount() or
+ * 	wimlib_extract_image() on a split WIM.
  *
  * @param wim_ret
  * 	On success, a pointer to an opaque ::WIMStruct for the opened WIM file
@@ -743,10 +799,10 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags);
  * 	added to wimlib if needed, but it appears to be the case that the lookup
  * 	table is never compressed.
  * @retval ::WIMLIB_ERR_IMAGE_COUNT
- * 	The number of metadata resources found in the WIM did not match the
- * 	image count given in the WIM header, or the number of &lt;IMAGE&gt;
- * 	elements in the XML data for the WIM did not match the image count given
- * 	in the WIM header.
+ * 	The WIM is not the non-first part of a split WIM, and the number of
+ * 	metadata resources found in the WIM did not match the image count given
+ * 	in the WIM header, or the number of &lt;IMAGE&gt; elements in the XML
+ * 	data for the WIM did not match the image count given in the WIM header.
  * @retval ::WIMLIB_ERR_INTEGRITY
  * 	::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @a flags and @a
  * 	wim_file contains an integrity table, but the SHA1 message digest for a
@@ -772,9 +828,9 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags);
  * @retval ::WIMLIB_ERR_READ
  * 	An unexpected end-of-file or read error occurred when trying to read
  * 	data from @a wim_file.
- * @retval ::WIMLIB_ERR_SPLIT
- * 	@a wim_file is a split WIM. wimlib does not support this kind of
- * 	WIM.
+ * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
+ * 	@a wim_file is a split WIM, but ::WIMLIB_OPEN_FLAG_SPLIT_OK was not
+ * 	givin in @a flags.
  * @retval ::WIMLIB_ERR_UNKNOWN_VERSION
  * 	A number other than 0x10d00 is written in the version field of the WIM
  * 	header of @a wim_file.
@@ -1150,6 +1206,34 @@ extern void wimlib_set_verbose(WIMStruct *wim, bool verbose);
  */
 extern int wimlib_set_output_dir(WIMStruct *wim, const char *dir);
 
+/**
+ * Splits a WIM into multiple parts.
+ *
+ * @param wimfile
+ * 	Name of the WIM file to split.  It must be a standalone, one-part WIM.
+ * @param swm_name
+ * 	Name of the SWM file to create.  This will be the name of the first
+ * 	part.  The other parts will have the same name with 2, 3, 4, ..., etc.
+ * 	appended.
+ * @param part_size
+ * 	The maximum size per part.  It is not guaranteed that this will really
+ * 	be the maximum size per part, because some file resources in the WIM may
+ * 	be larger than this size, and the WIM file format provides no way to
+ * 	split up file resources among multiple WIMs.
+ * @param flags
+ * 	Bitwise OR of ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY and/or
+ * 	::WIMLIB_OPEN_FLAG_SHOW_PROGRESS.
+ *
+ * @return 0 on success; nonzero on error.  This function may return any value
+ * returned by wimlib_open_wim() as well as the following error codes:
+ *
+ * @retval ::WIMLIB_ERR_WRITE
+ * 	An error occurred when trying to write data to one of the split WIMs.
+ *
+ */
+extern int wimlib_split(const char *wimfile, const char *swm_name, 
+			size_t part_size, int flags);
+
 /**
  * Unmounts a WIM image that was mounted using wimlib_mount().
  *
@@ -1250,6 +1334,9 @@ extern int wimlib_unmount(const char *dir, int flags);
  * 	with @a wim, or some file resources in @a wim refer to files in the
  * 	outside filesystem, and a read error occurred when reading one of these
  * 	files.
+ * @retval ::WIMLIB_ERR_WRITE
+ * 	An error occurred when trying to write data to the new WIM file at @a
+ * 	path.
  */
 extern int wimlib_write(WIMStruct *wim, const char *path, int image, int flags);