*
* 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,
* 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
*
/** 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.
*
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,
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,
*/
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.
*
* @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);
/**
*/
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.
*
* 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
* 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
* @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.
*/
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().
*
* 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);