X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=e880182b664ea3696f2c88f635fadcf71212bbca;hb=864db0e0929d60b33b8b0df35ccb68d43e7f8684;hp=5b164b6d6364577865cfcfdd47e9545e7c77d707;hpb=668c363a59c521f48eecbc4dd549c07a3e36179e;p=wimlib
diff --git a/include/wimlib.h b/include/wimlib.h
index 5b164b6d..e880182b 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -10,7 +10,7 @@
*/
/*
- * Copyright (C) 2012, 2013 Eric Biggers
+ * Copyright (C) 2012, 2013, 2014 Eric Biggers
*
* This file is part of wimlib, a library for working with WIM files.
*
@@ -33,7 +33,7 @@
*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.6.1, a C
+ * This is the documentation for the library interface of wimlib 1.6.2, 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
@@ -345,7 +345,7 @@
#define WIMLIB_MINOR_VERSION 6
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 2
#ifdef __cplusplus
extern "C" {
@@ -517,8 +517,10 @@ enum wimlib_progress_msg {
* will not be valid. */
WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
- /** Confirms that the metadata resource for each image has successfully
- * been writen to the WIM. @p info will not be valid. */
+ /** Confirms that per-image metadata has been successfully been written
+ * to the WIM file. @p info will not be valid. This message is paired
+ * with a preceding ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message.
+ */
WIMLIB_PROGRESS_MSG_WRITE_METADATA_END,
/** wimlib_overwrite() has successfully renamed the temporary file to
@@ -537,8 +539,8 @@ enum wimlib_progress_msg {
/** An integrity table is being calculated for the WIM being written.
* @p info will point to ::wimlib_progress_info.integrity. This message
- * is only received (and may be received many times) when a WIM is being
- * written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */
+ * is only received (and may be received many times) when a WIM file is
+ * being written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */
WIMLIB_PROGRESS_MSG_CALC_INTEGRITY,
/** Reserved. */
@@ -957,46 +959,6 @@ struct wimlib_capture_source {
long reserved;
};
-/** Structure that specifies a list of path patterns. */
-struct wimlib_pattern_list {
- /** Array of patterns. The patterns may be modified by library code,
- * but the @p pats pointer itself will not. See the man page for
- * wimlib-imagex capture for more information about allowed
- * patterns. */
- wimlib_tchar **pats;
-
- /** Number of patterns in the @p pats array. */
- size_t num_pats;
-
- /** Ignored; may be used by the calling code. */
- size_t num_allocated_pats;
-};
-
-/** A structure that contains lists of wildcards that match paths to treat
- * specially when capturing a WIM image. */
-struct wimlib_capture_config {
- /** Paths matching any pattern this list are excluded from being
- * captured, except if the same path appears in @p
- * exclusion_exception_pats. */
- struct wimlib_pattern_list exclusion_pats;
-
- /** Paths matching any pattern in this list are never excluded from
- * being captured. */
- struct wimlib_pattern_list exclusion_exception_pats;
-
- /** Reserved for future capture configuration options. */
- struct wimlib_pattern_list reserved1;
-
- /** Reserved for future capture configuration options. */
- struct wimlib_pattern_list reserved2;
-
- /** Library internal use only. */
- wimlib_tchar *_prefix;
-
- /** Library internal use only. */
- size_t _prefix_num_tchars;
-};
-
/** Set or unset the WIM header flag that marks it read-only
* (WIM_HDR_FLAG_READONLY in Microsoft's documentation), based on the
* ::wimlib_wim_info.is_marked_readonly member of the @p info parameter. This
@@ -1225,6 +1187,7 @@ struct wimlib_dir_entry {
#define WIMLIB_REPARSE_TAG_DFS 0x8000000A
#define WIMLIB_REPARSE_TAG_DFSR 0x80000012
#define WIMLIB_REPARSE_TAG_FILTER_MANAGER 0x8000000B
+#define WIMLIB_REPARSE_TAG_WOF 0x80000017
#define WIMLIB_REPARSE_TAG_SYMLINK 0xA000000C
/** If the file is a reparse point (FILE_ATTRIBUTE_DIRECTORY set in the
* attributes), this will give the reparse tag. This tells you whether
@@ -1359,19 +1322,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* such a file is encountered. */
#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
-/** Automatically select a capture configuration appropriate for capturing
- * filesystems containing Windows operating systems. When this flag is
- * specified, the corresponding @p config parameter or member must be @c NULL.
- *
- * Currently, selecting this capture configuration will cause the following
- * files and directories to be excluded from capture:
+/**
+ * Automatically select a capture configuration appropriate for capturing
+ * filesystems containing Windows operating systems. For example,
+ * "pagefile.sys" and "System Volume Information" will be excluded.
*
- * - "\$ntfs.log"
- * - "\hiberfil.sys"
- * - "\pagefile.sys"
- * - "\System Volume Information"
- * - "\RECYCLER"
- * - "\Windows\CSC"
+ * When this flag is specified, the corresponding @p config parameter or member
+ * must be @c NULL.
*
* Note that the default behavior--- that is, when this flag is not specified
* and @p config is @c NULL--- is to use no capture configuration, meaning that
@@ -1379,6 +1336,24 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*/
#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
+/**
+ * Capture image as WIMBoot compatible. In addition, use the capture
+ * configuration file $SOURCE/Windows/System32/WimBootCompress.ini if it
+ * exists, where $SOURCE is the directory being captured.
+ *
+ * Note: this will not by itself change the compression type. Before writing
+ * the WIM file, it's recommended to also do:
+ *
+ * \code
+ * wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS);
+ * wimlib_set_output_chunk_size(wim, 4096);
+ * \endcode
+ *
+ * since that makes access to the data faster (at the cost of a worse
+ * compression ratio compared to the 32768-byte LZX chunks usually used).
+ */
+#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
+
#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
@@ -1392,6 +1367,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \
WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE
#define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG
+#define WIMLIB_ADD_IMAGE_FLAG_WIMBOOT WIMLIB_ADD_FLAG_WIMBOOT
+
/** @} */
/** @ingroup G_modifying_wims
@@ -1476,8 +1453,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** This is the extraction equivalent to ::WIMLIB_ADD_FLAG_RPFIX. This forces
* reparse-point fixups on, so absolute symbolic links or junction points will
- * be fixed to be absolute relative to the actual extraction root. Reparse
- * point fixups are done by default if WIM_HDR_FLAG_RP_FIX is set in the WIM
+ * be fixed to be absolute relative to the actual extraction root. Reparse-
+ * point fixups are done by default for wimlib_extract_image() and
+ * wimlib_extract_image_from_pipe() if WIM_HDR_FLAG_RP_FIX is set in the WIM
* header. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_NORPFIX. */
#define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100
@@ -1547,10 +1525,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Do not
* preserve the directory structure of the archive when extracting --- that is,
- * place each extracted files or directory tree directly in the target
- * directory. */
+ * place each extracted file or directory tree directly in the target directory.
+ */
#define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000
+/** Windows only: Extract files as "pointers" back to the WIM archive. */
+#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
+
/** @} */
/** @ingroup G_mounting_wim_images
* @{ */
@@ -1625,6 +1606,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */
#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010
+/** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted
+ * image, causes the modified image to be committed as a new, unnamed image
+ * appended to the archive. The original image will be unmodified. */
+#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020
+
/** @} */
/** @ingroup G_modifying_wims
* @{ */
@@ -1811,11 +1797,9 @@ struct wimlib_add_command {
* WIM image. */
wimlib_tchar *wim_target_path;
- /** Configuration for excluded files. @c NULL means
- * exclude no files (use no configuration), unless
- * ::WIMLIB_ADD_FLAG_WINCONFIG is specified in @p
- * add_flags. */
- struct wimlib_capture_config *config;
+ /** Path to capture configuration file to use, or @c NULL for default.
+ */
+ wimlib_tchar *config_file;
/** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */
int add_flags;
@@ -1965,6 +1949,7 @@ enum wimlib_error_code {
WIMLIB_ERR_WRITE,
WIMLIB_ERR_XML,
WIMLIB_ERR_WIM_IS_ENCRYPTED,
+ WIMLIB_ERR_WIMBOOT,
};
@@ -2041,10 +2026,15 @@ wimlib_add_empty_image(WIMStruct *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 @p wim.
- * @param config
- * Capture configuration that specifies files, directories, or path globs
- * to exclude from being captured. If @c NULL, a dummy configuration where
- * no paths are treated specially is used.
+ * @param config_file
+ * Path to capture configuration file, or @c NULL. This file may specify,
+ * among other things, which files to exclude from capture. See the man
+ * page for wimlib-imagex capture (--config option) for
+ * details of the file format. If @c NULL, the default capture
+ * configuration shall be used. Ordinarily, the default capture
+ * configuration will result in no files being excluded from capture purely
+ * based on name; however, the ::WIMLIB_ADD_FLAG_WINCONFIG and
+ * ::WIMLIB_ADD_FLAG_WIMBOOT flags modify the default.
* @param add_flags
* Bitwise OR of flags prefixed with WIMLIB_ADD_FLAG.
* @param progress_func
@@ -2068,7 +2058,7 @@ extern int
wimlib_add_image(WIMStruct *wim,
const wimlib_tchar *source,
const wimlib_tchar *name,
- const struct wimlib_capture_config *config,
+ const wimlib_tchar *config_file,
int add_flags,
wimlib_progress_func_t progress_func);
@@ -2097,7 +2087,7 @@ wimlib_add_image_multisource(WIMStruct *wim,
const struct wimlib_capture_source *sources,
size_t num_sources,
const wimlib_tchar *name,
- const struct wimlib_capture_config *config,
+ const wimlib_tchar *config_file,
int add_flags,
wimlib_progress_func_t progress_func);
@@ -2269,7 +2259,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_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
- * usually more efficient.
+ * more efficient.
*
* Notes: wimlib_extract_files() does not support the
* ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS flag, and
@@ -2394,6 +2384,9 @@ wimlib_extract_files(WIMStruct *wim,
* names is not supported --- on Windows, this occurs if the target volume
* does not support short names, while on non-Windows, this occurs if
* ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags.
+ * @retval ::WIMLIB_ERR_WIMBOOT
+ * ::WIMLIB_EXTRACT_FLAG_WIMBOOT was specified in @p extract_flags, but
+ * there was a problem creating WIMBoot pointer files.
* @retval ::WIMLIB_ERR_WRITE
* Failed to write data to a file being extracted.
*/
@@ -2677,6 +2670,19 @@ wimlib_get_image_description(const WIMStruct *wim, int image);
extern const wimlib_tchar *
wimlib_get_image_name(const WIMStruct *wim, int image);
+/**
+ * @ingroup G_general
+ *
+ * Returns the version of wimlib as a 32-bit number whose top 12 bits contain
+ * the major version, the next 10 bits contain the minor version, and the low 10
+ * bits contain the patch version.
+ *
+ * In other words, the returned value is equal to ((WIMLIB_MAJOR_VERSION
+ * << 22) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION) for the
+ * corresponding header file.
+ */
+extern uint32_t
+wimlib_get_version(void);
/**
* @ingroup G_wim_information