*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.6.2, a C
+ * This is the documentation for the library interface of wimlib 1.6.3, 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
* created from one of these on-disk files initially only partially represents
* the full WIM and needs to, in effect, be logically combined with other
* ::WIMStruct's before performing certain operations, such as extracting files
- * with wimlib_extract_image() or wimlib_extract_files(). This is done by
+ * with wimlib_extract_image() or wimlib_extract_paths(). This is done by
* calling wimlib_reference_resource_files() or wimlib_reference_resources().
*
* wimlib_write() can create delta WIMs as well as standalone WIMs, but a
#define WIMLIB_MINOR_VERSION 6
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 3
#ifdef __cplusplus
extern "C" {
# define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
#endif
+/** Use this to specify the root directory of the WIM image. */
+#define WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING
+
+/** Use this to test if the specified path refers to the root directory of the
+ * WIM image. */
+#define WIMLIB_IS_WIM_ROOT_PATH(path) \
+ ((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \
+ (path)[1] == 0)
+
#ifdef __GNUC__
# define _wimlib_deprecated __attribute__((deprecated))
#else
/** The WIM does not include any compressed resources. */
WIMLIB_COMPRESSION_TYPE_NONE = 0,
- /** Compressed resources in the WIM use LZX compression. */
- WIMLIB_COMPRESSION_TYPE_LZX = 1,
-
/** Compressed resources in the WIM use XPRESS compression. */
- WIMLIB_COMPRESSION_TYPE_XPRESS = 2,
+ WIMLIB_COMPRESSION_TYPE_XPRESS = 1,
+
+ /** Compressed resources in the WIM use LZX compression. */
+ WIMLIB_COMPRESSION_TYPE_LZX = 2,
/** Compressed resources in the WIM use LZMS compression. Note: LZMS
* compression is only compatible with wimlib v1.6.0 and later and with
/** One or more file or directory trees within a WIM image is about to
* be extracted. @p info will point to ::wimlib_progress_info.extract.
- * This message is received once per extraction command for
- * wimlib_extract_files(), but only once for wimlib_extract_paths() and
- * wimlib_extract_pathlist(). (In the latter cases, wimlib combines all
- * paths into a single extraction operation for optimization purposes.)
- */
+ * This message is received only once per wimlib_extract_paths() and
+ * wimlib_extract_pathlist(), since wimlib combines all paths into a
+ * single extraction operation for optimization purposes. */
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
/** The directory structure and other preliminary metadata is about to
* ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */
WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND,
+ /** A file in the WIM image is being replaced as a result of a
+ * ::wimlib_add_command without ::WIMLIB_ADD_FLAG_NO_REPLACE specified.
+ * @p info will point to ::wimlib_progress_info.replace. This is only
+ * received when ::WIMLIB_ADD_FLAG_VERBOSE is also specified in the add
+ * command. */
+ WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM,
+
+ /** A WIM image is being applied with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and
+ * a file is being extracted normally (not as a WIMBoot "pointer file")
+ * due to it matching a pattern in the [PrepopulateList] section of the
+ * configuration file \Windows\System32\WimBootCompress.ini in the WIM
+ * image. @info will point to ::wimlib_progress_info.wimboot_exclude.
+ */
+ WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE,
};
/** A pointer to this union is passed to the user-supplied
int32_t compression_type;
/** Number of split WIM parts from which streams are being
- * written (may be 0 if irrelevant). */
+ * written (may be 0 if irrelevant). */
uint32_t total_parts;
- /** Number of split WIM parts from which streams have been
- * written (may be 0 if irrelevant). */
+ /** This is currently broken and will always be 0. */
uint32_t completed_parts;
} write_streams;
union {
/** Target path in the WIM image. Only valid on
* messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
- * ::WIMLIB_PROGRESS_MSG_SCAN_END. If capturing a full
- * image, this will be the empty string; otherwise it
- * will name the place in the WIM image at which the
- * directory tree is being added. */
+ * ::WIMLIB_PROGRESS_MSG_SCAN_END. */
const wimlib_tchar *wim_target_path;
/** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
* being extracted. This is because wimlib, by default, extracts the
* individual data streams in whichever order it determines to be the
* most efficient.
- *
- * An additional caveat: wimlib_extract_files() will perform a separate
- * logical extraction operation, with separate byte counts, for each
- * extraction command (file or directory tree). On the other hand,
- * wimlib_extract_paths() and wimlib_extract_pathlist() combine all the
- * paths to extract into a single logical extraction operation.
*/
struct wimlib_progress_info_extract {
/** Number of the image from which files are being extracted
* data stream, or a reparse data buffer. */
uint64_t num_streams;
- /** When extracting files using wimlib_extract_files(), this
- * will be the path within the WIM image to the file or
- * directory tree currently being extracted. Otherwise, this
- * will be the empty string. */
- const wimlib_tchar *extract_root_wim_source_path;
+ /** Reserved. */
+ const wimlib_tchar *reserved_2;
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
* finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */
const wimlib_tchar *part_name;
} split;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM */
+ struct wimlib_progress_info_replace {
+ /** Path to the file in the WIM image that is being replaced */
+ const wimlib_tchar *path_in_wim;
+ } replace;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE */
+ struct wimlib_progress_info_wimboot_exclude {
+ /** Path to the file in the WIM image */
+ const wimlib_tchar *path_in_wim;
+
+ /** Path to which the file is being extracted */
+ const wimlib_tchar *extraction_path;
+ } wimboot_exclude;
};
/** A user-supplied function that will be called periodically during certain WIM
* filesystem to be included in the WIM image. */
wimlib_tchar *fs_source_path;
- /** Destination path in the WIM image. Leading and trailing slashes are
- * ignored. The empty string or @c NULL means the root directory of the
- * WIM image. */
+ /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to
+ * specify the root directory of the WIM image. */
wimlib_tchar *wim_target_path;
/** Reserved; set to 0. */
* ::WIMLIB_ADD_FLAG_UNIX_DATA. */
#define WIMLIB_ADD_FLAG_NTFS 0x00000001
-/** Follow symlinks; archive and dump the files they point to. Cannot be used
- * with ::WIMLIB_ADD_FLAG_NTFS. */
+/** Follow symlinks; archive and dump the files they point to. Currently only
+ * supported on UNIX-like systems. */
#define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002
/** Call the progress function with the message
* alternate data stream to each regular file, symbolic link, and directory to
* contain this information. Please note that this flag is for convenience
* only; Microsoft's implementation will not understand this special
- * information. This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */
+ * information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS capture
#define WIMLIB_ADD_FLAG_NORPFIX 0x00000200
/** Do not automatically exclude unsupported files or directories from capture;
- * e.g. encrypted directories in NTFS-3g capture mode, or device files and FIFOs
- * on UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
+ * e.g. encrypted files in NTFS-3g capture mode, or device files and FIFOs on
+ * UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
* such a file is encountered. */
#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
/**
- * Capture image as WIMBoot compatible. In addition, use the capture
- * configuration file <c>$SOURCE/Windows/System32/WimBootCompress.ini</c> if it
- * exists, where <c>$SOURCE</c> is the directory being captured.
+ * Capture image as WIMBoot compatible. In addition, if no capture
+ * configuration file is explicitly specified use the capture configuration file
+ * <c>$SOURCE/Windows/System32/WimBootCompress.ini</c> if it exists, where
+ * <c>$SOURCE</c> is the directory being captured; or, if a capture
+ * configuration file is explicitly specified, use it and also place it at
+ * /Windows/System32/WimBootCompress.ini in the WIM image.
*
* Note: this will not by itself change the compression type. Before writing
* the WIM file, it's recommended to also do:
*/
#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
+/**
+ * If the add command involves adding a non-directory file to a location at
+ * which there already exists a nondirectory file in the WIM image, issue
+ * ::WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file. This only has an
+ * effect when updating an existing image with wimlib_update_image().
+ * This was the default behavior in wimlib v1.6.2 and earlier.
+ */
+#define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000
+
#define WIMLIB_ADD_IMAGE_FLAG_NTFS WIMLIB_ADD_FLAG_NTFS
#define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE WIMLIB_ADD_FLAG_DEREFERENCE
#define WIMLIB_ADD_IMAGE_FLAG_VERBOSE WIMLIB_ADD_FLAG_VERBOSE
*/
#define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000
-/** Windows only: Extract files as "pointers" back to the WIM archive. */
+/** Windows only: Extract files as "pointers" back to the WIM archive. See the
+ * documentation for the <b>--wimboot</b> option of <b>wimlib-imagex apply</b>
+ * for more information. */
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
/** @} */
/** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */
struct wimlib_add_command {
- /** Filesystem path to the file or directory tree to
- * add. */
+ /** Filesystem path to the file or directory tree to add. */
wimlib_tchar *fs_source_path;
- /** Path, specified from the root of the WIM image, at
- * which to add the file or directory tree within the
- * WIM image. */
+
+ /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to
+ * specify the root directory of the WIM image. */
wimlib_tchar *wim_target_path;
/** Path to capture configuration file to use, or @c NULL for default.
/** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */
struct wimlib_delete_command {
- /** Path, specified from the root of the WIM image, for
- * the file or directory tree within the WIM image to be
- * deleted. */
+
+ /** Path, specified from the root of the WIM image, for the file or
+ * directory tree within the WIM image to be deleted. */
wimlib_tchar *wim_path;
- /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */
+
+ /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */
int delete_flags;
};
/** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */
struct wimlib_rename_command {
- /** Path, specified from the root of the WIM image, for
- * the source file or directory tree within the WIM
- * image. */
+
+ /** Path, specified from the root of the WIM image, for the source file
+ * or directory tree within the WIM image. */
wimlib_tchar *wim_source_path;
- /** Path, specified from the root of the WIM image, for
- * the destination file or directory tree within the WIM
- * image. */
+
+ /** Path, specified from the root of the WIM image, for the destination
+ * file or directory tree within the WIM image. */
wimlib_tchar *wim_target_path;
- /** Reserved; set to 0. */
+
+ /** Reserved; set to 0. */
int rename_flags;
};
};
};
-/** @} */
-/** @ingroup G_extracting_wims
- * @{ */
-
-/** DEPRECATED: Specification of extracting a file or directory tree from a WIM
- * image. This is only used for calls to wimlib_extract_files(), which has been
- * deprecated in favor of the easier-to-use wimlib_extract_paths(). */
-struct wimlib_extract_command {
- /** Path to file or directory tree within the WIM image to extract. It
- * must be provided as an absolute path from the root of the WIM image.
- * The path separators may be either forward slashes or backslashes. */
- wimlib_tchar *wim_source_path;
-
- /** Filesystem path to extract the file or directory tree to. */
- wimlib_tchar *fs_dest_path;
-
- /** Bitwise OR of zero or more of the WIMLIB_EXTRACT_FLAG_* flags. */
- int extract_flags;
-};
-
-
/** @} */
/** @ingroup G_general
* @{ */
int export_flags,
wimlib_progress_func_t progress_func);
-/**
- * @ingroup G_extracting_wims
- *
- * Extract zero or more files or directory trees from a WIM image.
- *
- * As of wimlib v1.6.1, this function is deprecated in favor of
- * wimlib_extract_paths() because wimlib_extract_paths() is easier to use and
- * more efficient.
- *
- * Notes: wimlib_extract_files() does not support the
- * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS flag, and
- * ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE is always implied. The same
- * hardlink/symlink extraction mode must be set on all extraction commands. An
- * independent extraction operation (like a separate call to
- * wimlib_extract_paths()) is done for each extraction command. Otherwise, the
- * documentation for wimlib_extract_paths() applies.
- */
-extern int
-wimlib_extract_files(WIMStruct *wim,
- int image,
- const struct wimlib_extract_command *cmds,
- size_t num_cmds,
- int default_extract_flags,
- wimlib_progress_func_t progress_func) _wimlib_deprecated;
/**
* @ingroup G_extracting_wims
*
* Similar to wimlib_set_output_compression_type(), but set the compression type
* for writing packed streams (solid blocks).
- *
- * Note: based on testing, WIMGAPI is seemingly only compatible with LZMS
- * compression in packed streams. Therefore the use of this function is not
- * recommended. Also, with large chunk sizes, LZMS gives the best compression
- * ratio among the alternatives anyway.
*/
extern int
wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
* If non-NULL, a function that will be called periodically with the
* progress of the current operation.
*
- * @return 0 on success; nonzero on error. On failure, some but not all of the
- * update commands may have been executed. No individual update command will
- * have been partially executed. Possible error codes include:
+ * @return 0 on success; nonzero on error. On failure, all update commands will
+ * be rolled back, and no visible changes shall have been made to @p wim.
+ * Possible error codes include:
*
* @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
* The capture configuration structure specified for an add command was
wimlib_free_decompressor(struct wimlib_decompressor *decompressor);
-struct wimlib_lzx_params_old;
-struct wimlib_lzx_context_old;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_lzx_set_default_params(const struct wimlib_lzx_params_old *params)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_lzx_alloc_context(const struct wimlib_lzx_params_old *params,
- struct wimlib_lzx_context_old **ctx_pp)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern void
-wimlib_lzx_free_context(struct wimlib_lzx_context_old *ctx)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern unsigned
-wimlib_lzx_compress2(const void *udata, unsigned ulen, void *cdata,
- struct wimlib_lzx_context_old *ctx)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern unsigned
-wimlib_lzx_compress(const void *udata, unsigned ulen, void *cdata)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern unsigned
-wimlib_xpress_compress(const void *udata, unsigned ulen, void *cdata)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_lzx_decompress(const void *cdata, unsigned clen,
- void *udata, unsigned ulen)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_xpress_decompress(const void *cdata, unsigned clen,
- void *udata, unsigned ulen)
- _wimlib_deprecated;
-
-
/**
* @}
*/
-/** @ingroup G_wim_information
- *
- * Deprecated and will return ::WIMLIB_ERR_UNSUPPORTED. Use
- * wimlib_iterate_dir_tree() instead. */
-extern int
-wimlib_print_metadata(WIMStruct *wim, int image)
- _wimlib_deprecated;
-
#ifdef __cplusplus
}
git://wimlib.net / wimlib / blobdiff