* \section encodings Locales and character encodings
*
* To support Windows as well as UNIX, wimlib's API typically takes and returns
- * strings of "tchars", which are in a platform-dependent encoding.
+ * strings of ::wimlib_tchar, which are in a platform-dependent encoding.
*
- * On Windows, each "tchar" is 2 bytes and is the same as a "wchar_t", and the
- * encoding is UTF-16LE.
+ * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t",
+ * and the encoding is UTF-16LE.
*
- * On UNIX, each "tchar" is 1 byte and is simply a "char", and the encoding is
- * the locale-dependent multibyte encoding. I recommend you set your locale to a
- * UTF-8 capable locale to avoid any issues. Also, by default, wimlib on UNIX
- * will assume the locale is UTF-8 capable unless you call wimlib_global_init()
- * after having set your desired locale.
+ * On UNIX, each ::wimlib_tchar is 1 byte and is simply a "char", and the
+* encoding is the locale-dependent multibyte encoding. I recommend you set your
+* locale to a UTF-8 capable locale to avoid any issues. Also, by default,
+ * wimlib on UNIX will assume the locale is UTF-8 capable unless you call
+* wimlib_global_init() after having set your desired locale.
*
* \section Limitations
*
* without mounting it, other than by adding, removing, or extracting an
* entire image. The FUSE mount feature should be used for this purpose.
* - Currently, Microsoft's @a image.exe can create slightly smaller WIM files
- * than wimlib when using maximum (LZX) compression because it knows how to
- * split up LZX compressed blocks, which is not yet implemented in wimlib.
+ * than wimlib (~2% or 3% smaller) when using maximum (LZX) compression.
* - 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".
* - The old WIM format from Vista pre-releases is not supported.
#ifdef __WIN32__
typedef wchar_t wimlib_tchar;
#else
+/** See \ref encodings */
typedef char wimlib_tchar;
#endif
* ::WIMLIB_COMPRESSION_TYPE_XPRESS, or
* ::WIMLIB_COMPRESSION_TYPE_LZX. */
int compression_type;
+
+ /** Library internal use only. */
+ uint64_t _private;
} write_streams;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
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 @a pats pointer itself will not. See the man page for
+ * <b>wimlib-imagex capture</b> for more information about allowed
+ * patterns. */
+ wimlib_tchar **pats;
+
+ /** Number of patterns in the @a 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 @a
+ * 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;
+};
+
/*****************************
* WIMLIB_ADD_IMAGE_FLAG_* *
* mode, or in Win32 native builds. */
#define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS 0x00000020
+/** Fail immediately if the full security descriptor of any file or directory
+ * cannot be accessed. Only has an effect in Win32 native builds. The default
+ * behavior without this flag is to first try omitting the SACL from the
+ * security descriptor, then to try omitting the security descriptor entirely.
+ * */
+#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS 0x00000040
+
+/** Call the progress function with the message
+ * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from
+ * capture. This is a subset of the messages provided by
+ * ::WIMLIB_ADD_IMAGE_FLAG_VERBOSE. */
+#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE 0x00000080
+
/******************************
* WIMLIB_EXPORT_FLAG_* *
******************************/
/** Do not extract security descriptors. Only has an effect in NTFS apply mode,
* or in Win32 native builds. */
-#define WIMLIB_EXTRACT_FLAG_NOACLS 0x00000040
+#define WIMLIB_EXTRACT_FLAG_NO_ACLS 0x00000040
+
+/** Fail immediately if the full security descriptor of any file or directory
+ * cannot be set exactly as specified in the WIM file. The default behavior
+ * without this flag is to fall back to setting the security descriptor with the
+ * SACL omitted, then only the default inherited security descriptor, if we do
+ * not have permission to set the desired one. */
+#define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080
/******************************
* WIMLIB_MOUNT_FLAG_* *
WIMLIB_ERR_INVALID_IMAGE,
WIMLIB_ERR_INVALID_INTEGRITY_TABLE,
WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY,
+ WIMLIB_ERR_INVALID_MULTIBYTE_STRING,
+ WIMLIB_ERR_INVALID_OVERLAY,
WIMLIB_ERR_INVALID_PARAM,
WIMLIB_ERR_INVALID_PART_NUMBER,
WIMLIB_ERR_INVALID_RESOURCE_HASH,
WIMLIB_ERR_INVALID_RESOURCE_SIZE,
WIMLIB_ERR_INVALID_SECURITY_DATA,
WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
- WIMLIB_ERR_INVALID_UTF8_STRING,
WIMLIB_ERR_INVALID_UTF16_STRING,
+ WIMLIB_ERR_INVALID_UTF8_STRING,
WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE,
WIMLIB_ERR_LINK,
WIMLIB_ERR_MKDIR,
WIMLIB_ERR_NTFS_3G,
WIMLIB_ERR_OPEN,
WIMLIB_ERR_OPENDIR,
- WIMLIB_ERR_READLINK,
WIMLIB_ERR_READ,
+ WIMLIB_ERR_READLINK,
WIMLIB_ERR_RENAME,
WIMLIB_ERR_REOPEN,
WIMLIB_ERR_RESOURCE_ORDER,
WIMLIB_ERR_SPLIT_UNSUPPORTED,
WIMLIB_ERR_STAT,
WIMLIB_ERR_TIMEOUT,
+ WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE,
WIMLIB_ERR_UNKNOWN_VERSION,
WIMLIB_ERR_UNSUPPORTED,
WIMLIB_ERR_WRITE,
WIMLIB_ERR_XML,
- WIMLIB_ERR_INVALID_OVERLAY,
- WIMLIB_ERR_INVALID_MULTIBYTE_STRING,
- WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE,
};
* @param name
* The name to give the image. This must be non-@c NULL.
* @param config
- * Pointer to the contents of an image capture configuration file. If @c
- * NULL, a default string is used. Please see the manual page for
- * <b>wimlib-imagex capture</b> for more information.
- * @param config_len
- * Length of the string @a config in bytes, not including an optional
- * null-terminator. Ignored if @a config is @c NULL.
+ * 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 add_image_flags
* Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.
* @param progress_func
wimlib_add_image(WIMStruct *wim,
const wimlib_tchar *source,
const wimlib_tchar *name,
- const wimlib_tchar *config,
- size_t config_len,
+ struct wimlib_capture_config *config,
int add_image_flags,
wimlib_progress_func_t progress_func);
struct wimlib_capture_source *sources,
size_t num_sources,
const wimlib_tchar *name,
- const wimlib_tchar *config_str,
- size_t config_len,
+ struct wimlib_capture_config *config,
int add_image_flags,
wimlib_progress_func_t progress_func);
int wim_write_flags,
wimlib_progress_func_t progress_func);
+/**
+ * Compress a chunk of a WIM resource using LZX compression.
+ *
+ * This function is exported for convenience only and need not be used.
+ *
+ * @param chunk
+ * Uncompressed data of the chunk.
+ * @param chunk_size
+ * Size of the uncompressed chunk, in bytes.
+ * @param out
+ * Pointer to output buffer of size at least (@a chunk_size - 1) bytes.
+ *
+ * @return
+ * The size of the compressed data written to @a out in bytes, or 0 if the
+ * data could not be compressed to (@a chunk_size - 1) bytes or fewer.
+ *
+ * As a special requirement, the compression code is optimized for the WIM
+ * format and therefore requires (@a chunk_size <= 32768).
+ */
+extern unsigned
+wimlib_lzx_compress(const void *chunk, unsigned chunk_size, void *out);
+
+/**
+ * Decompresses a block of LZX-compressed data as used in the WIM file format.
+ *
+ * Note that this will NOT work unmodified for LZX as used in the cabinet
+ * format, which is not the same as in the WIM format!
+ *
+ * This function is exported for convenience only and need not be used.
+ *
+ * @param compressed_data
+ * Pointer to the compressed data.
+ *
+ * @param compressed_len
+ * Length of the compressed data, in bytes.
+ *
+ * @param uncompressed_data
+ * Pointer to the buffer into which to write the uncompressed data.
+ *
+ * @param uncompressed_len
+ * Length of the uncompressed data. It must be 32768 bytes or less.
+ *
+ * @return
+ * 0 on success; non-zero on failure.
+ */
+extern int
+wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len,
+ void *uncompressed_data, unsigned uncompressed_len);
+
+
/**
* Mounts an image in a WIM file on a directory read-only or read-write.
*
unsigned num_threads,
wimlib_progress_func_t progress_func);
+/**
+ * This function is equivalent to wimlib_lzx_compress(), but instead compresses
+ * the data using "XPRESS" compression.
+ */
+extern unsigned
+wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out);
+
+/**
+ * This function is equivalent to wimlib_lzx_decompress(), but instead assumes
+ * the data is compressed using "XPRESS" compression.
+ */
+extern int
+wimlib_xpress_decompress(const void *compressed_data, unsigned compressed_len,
+ void *uncompressed_data, unsigned uncompressed_len);
+
#endif /* _WIMLIB_H */
git://wimlib.net / wimlib / blobdiff