X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=src%2Fwimlib.h;h=fa27fc1c27d0f55f667c70c7761584a78ae07b36;hb=46987f6ff2d27b0224f0ccab1b1e91164cae1d86;hp=c284dbc34802a8d33f0007074247b3329cf936cf;hpb=1449ca7e974c27bec75cb6784873be3c0e6eb78a;p=wimlib
diff --git a/src/wimlib.h b/src/wimlib.h
index c284dbc3..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 do
- * not expect to be able to use wimlib to image a Windows installation and
- * preserve file attributes.
- * - 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 do not expect to be able to use wimlib to
+ * image a Windows installation and preserve file attributes. 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
*
@@ -265,9 +264,7 @@ enum wim_compression_type {
#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. Giving this flag makes the function allows split WIMS to be opened, but
- * beware: wimlib has little support for split WIMs and only certain functions
- * will work on them. */
+ * WIM. */
#define WIMLIB_OPEN_FLAG_SPLIT_OK 0x4
/**
@@ -295,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,
@@ -699,7 +697,20 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name);
* ::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.
+ *
+ * @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);
@@ -771,7 +782,10 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags);
* 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.
+ * 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
@@ -785,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 <IMAGE>
- * 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 <IMAGE> 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
@@ -814,7 +828,7 @@ 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
+ * @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
@@ -1192,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().
*
@@ -1292,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);