*
* \section intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.4.0, a C
+ * This is the documentation for the library interface of wimlib 1.4.1, 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
#define WIMLIB_MINOR_VERSION 4
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 1
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
typedef char wimlib_tchar;
#endif
+#ifdef __WIN32__
+/** Path separator for WIM paths passed back to progress callbacks. */
+# define WIMLIB_WIM_PATH_SEPARATOR '\\'
+# define WIMLIB_WIM_PATH_SEPARATOR_STRING L"\\"
+#else
+/** Path separator for WIM paths passed back to progress callbacks. */
+# define WIMLIB_WIM_PATH_SEPARATOR '/'
+# define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
+#endif
/**
* Specifies the compression type of a WIM file.
*/
/** A WIM image is about to be extracted. @a info will point to
* ::wimlib_progress_info.extract. */
- WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
+ WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0,
/** A file or directory tree within a WIM image (not the full image) is
* about to be extracted. @a info will point to
/** A wimlib_split() operation is in progress, and a split part has been
* finished. @a info will point to ::wimlib_progress_info.split. */
WIMLIB_PROGRESS_MSG_SPLIT_END_PART,
+
+ /**
+ * A WIM update command is just about to be executed; @a info will point
+ * to ::wimlib_progress_info.update.
+ */
+ WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND,
+
+ /**
+ * A WIM update command has just been executed; @a info will point to
+ * ::wimlib_progress_info.update.
+ */
+ WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND,
+
};
/** A pointer to this union is passed to the user-supplied
const wimlib_tchar *to;
} rename;
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and
+ * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND. */
+ struct wimlib_progress_info_update {
+ /** Pointer to the update command that will be executed or has
+ * just been executed. */
+ const struct wimlib_update_command *command;
+
+ /** Number of update commands that have been completed so far.
+ */
+ size_t completed_commands;
+
+ /** Number of update commands that are being executed as part of
+ * this call to wimlib_update_image(). */
+ size_t total_commands;
+ } update;
+
/** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY and
* ::WIMLIB_PROGRESS_MSG_CALC_INTEGRITY. */
struct wimlib_progress_info_integrity {
* WIMLIB_OPEN_FLAG_*
******************************/
-/** Verify the WIM contents against the WIM's integrity table, if present. */
+/** Verify the WIM contents against the WIM's integrity table, if present. This
+ * causes the raw data of the WIM file, divided into 10 MB chunks, to be
+ * checksummed and checked against the SHA1 message digests specified in the
+ * integrity table. WIMLIB_ERR_INTEGRITY is returned if there are any
+ * mismatches. */
#define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001
-/** Do not issue an error if the WIM is part of a split WIM. */
+/** Do not issue an error if the WIM is part of a split WIM. */
#define WIMLIB_OPEN_FLAG_SPLIT_OK 0x00000002
+/** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it
+ * is not. A WIM is considered writable only if it is writable at the
+ * filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its
+ * header (note: wimlib currently never sets this flag), and is not part of a
+ * spanned set. It is not required to provide this flag to make changes to the
+ * WIM, but with this flag you get the error sooner rather than later. */
+#define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004
+
/******************************
* WIMLIB_UNMOUNT_FLAG_*
******************************/
/** Do a "lazy" unmount (detach filesystem immediately, even if busy) */
#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010
+/******************************
+ * WIMLIB_UPDATE_FLAG_*
+ ******************************/
+
+/** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and
+ * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */
+#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001
+
/******************************
* WIMLIB_WRITE_FLAG_*
******************************/
WIMLIB_ERR_VOLUME_LACKS_FEATURES,
WIMLIB_ERR_WRITE,
WIMLIB_ERR_XML,
+ WIMLIB_ERR_WIM_IS_READONLY,
};
* Pointer to the ::WIMStruct for the WIM file to which the image is to be
* added.
* @param name
- * Name to give the new image.
+ * Name to give the new image. If @c NULL or empty, the new image is given
+ * no name. If nonempty, it must specify a name that does not already
+ * exist in @a wim.
* @param new_idx_ret
* If non-<code>NULL</code>, the index of the newly added image is returned
* in this location.
*
* @return 0 on success; nonzero on failure. The possible error codes are:
*
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * @a name was @c NULL or an empty string.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- * @a wim is part of a split WIM.
* @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
* There is already an image in @a wim named @a name.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to add the new image.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * The WIM file is considered read-only because of any of the reasons
+ * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
+ * flag.
*/
extern int
wimlib_add_empty_image(WIMStruct *wim,
* A path to a directory or unmounted NTFS volume that will be captured as
* a WIM image.
* @param name
- * The name to give the image. It must be nonempty and must specify a name
- * that does not yet exist in @a wim.
+ * Name to give the new image. If @c NULL or empty, the new image is given
+ * no name. If nonempty, it must specify a name that does not already
+ * exist in @a wim.
* @param config
* Capture configuration that specifies files, directories, or path globs
* to exclude from being captured. If @c NULL, a dummy configuration where
* Failed to allocate needed memory.
* @retval ::WIMLIB_ERR_READ
* Could not read the metadata resource for @a image from the WIM.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- * @a wim is part of a split WIM. Deleting an image from a split WIM is
- * unsupported.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * The WIM file is considered read-only because of any of the reasons
+ * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
+ * flag.
*/
extern int
wimlib_delete_image(WIMStruct *wim, int image);
* complete split 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_SPLIT_UNSUPPORTED
- * @a dest_wim is part of a split WIM. Exporting an image to a split WIM
- * is unsupported.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * @a dest_wim is considered read-only because of any of the reasons
+ * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
+ * flag.
*/
extern int
wimlib_export_image(WIMStruct *src_wim, int src_image,
*
* @return 0 on success; nonzero on error. This function may return any value
* returned by wimlib_open_wim() and wimlib_write() except
- * ::WIMLIB_ERR_SPLIT_UNSUPPORTED, as well as the following error code:
+ * ::WIMLIB_ERR_WIM_IS_READONLY, as well as the following error code:
*
* @retval ::WIMLIB_ERR_SPLIT_INVALID
* The split WIMs do not form a valid WIM because they do not include all
* split 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_SPLIT_UNSUPPORTED
- * The WIM is a split WIM and a read-write mount was requested. We only
- * support mounting a split WIM read-only.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @a mount_flags, but @a
+ * wim is considered read-only because of any of the reasons mentioned in
+ * the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* Mounting is not supported, either because the platform is Windows, or
* because the platform is UNIX and wimlib was compiled with @c
* The path to the WIM file to open.
* @param open_flags
* Bitwise OR of flags ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY and/or
- * ::WIMLIB_OPEN_FLAG_SPLIT_OK.
- * <br/> <br/>
- * If ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is given, the integrity table of
- * the WIM, if it exists, is checked, and this function will fail with an
- * ::WIMLIB_ERR_INTEGRITY status if any of the computed SHA1 message
- * digests of the WIM do not exactly match the corresponding message
- * digests given in the integrity table.
- * <br/> <br/>
- * If ::WIMLIB_OPEN_FLAG_SPLIT_OK is given, no error will be issued if the
- * WIM is part of a split WIM; otherwise ::WIMLIB_ERR_SPLIT_UNSUPPORTED is
- * returned. (This flag may be removed in the future, in which case no
- * error will be issued when opening a split WIM.)
+ * ::WIMLIB_OPEN_FLAG_SPLIT_OK and/or ::WIMLIB_OPEN_FLAG_WRITE_ACCESS.
*
* @param progress_func
* If non-NULL, a function that will be called periodically with the
* @retval ::WIMLIB_ERR_UNKNOWN_VERSION
* A number other than 0x10d00 is written in the version field of the WIM
* header of @a wim_file. (Probably a pre-Vista WIM).
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
+ * considered read-only because of any of the reasons mentioned in the
+ * documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
* @retval ::WIMLIB_ERR_XML
* The XML data for @a wim_file is invalid.
*/
* @return 0 on success; nonzero on error. This function may return any value
* returned by wimlib_write() as well as the following error codes:
* @retval ::WIMLIB_ERR_ALREADY_LOCKED
- * The WIM was going to be modifien in-place (with no temporary file), but
+ * The WIM was going to be modified in-place (with no temporary file), but
* an exclusive advisory lock on the on-disk WIM file could not be acquired
* because another thread or process has mounted an image from the WIM
* read-write or is currently modifying the WIM in-place.
* @retval ::WIMLIB_ERR_RENAME
* The temporary file that the WIM was written to could not be renamed to
* the original filename of @a wim.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * The WIM file is considered read-only because of any of the reasons
+ * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
+ * flag.
*/
extern int
wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads,
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @a boot_idx does not specify an existing image in @a wim, and it was not
* 0.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- * @a wim is part of a split WIM. We do not support changing the boot
- * index of a split WIM.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * @a wim is considered read-only because of any of the reasons mentioned
+ * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_boot_idx(WIMStruct *wim, int boot_idx);
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @a description
* string.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * @a wim is considered read-only because of any of the reasons mentioned
+ * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_image_descripton(WIMStruct *wim, int image,
* @a image does not specify a single existing image in @a wim.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @a flags string.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * @a wim is considered read-only because of any of the reasons mentioned
+ * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int wimlib_set_image_flags(WIMStruct *wim, int image,
const wimlib_tchar *flags);
* @param image
* The number of the image for which to change the name.
* @param name
- * The new name to give the image. It must be a nonempty string.
+ * New name to give the new image. If @c NULL or empty, the new image is
+ * given no name. If nonempty, it must specify a name that does not
+ * already exist in @a wim.
*
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
* There is already an image named @a name in @a wim.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * @a name was @c NULL or the empty string.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @a image does not specify a single existing image in @a wim.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @a name string.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * @a wim is considered read-only because of any of the reasons mentioned
+ * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int wimlib_set_image_name(WIMStruct *wim, int image,
const wimlib_tchar *name);
* @param num_cmds
* Number of commands in @a cmds.
* @param update_flags
- * Reserved; must be 0.
+ * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0.
* @param progress_func
* If non-NULL, a function that will be called periodically with the
* progress of the current operation.
* or, the platform is Windows and either the ::WIMLIB_ADD_FLAG_UNIX_DATA
* or the ::WIMLIB_ADD_FLAG_DEREFERENCE flags were specified in the @a
* add_flags for an update command.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ * The WIM file is considered read-only because of any of the reasons
+ * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
+ * flag.
*/
extern int
wimlib_update_image(WIMStruct *wim,
git://wimlib.net / wimlib / blobdiff