*
* \section intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.3.2. If you
+ * This is the documentation for the library interface of wimlib 1.3.3. If you
* have installed wimlib and want to know how to use the @b wimlib-imagex
* program, please see the man pages instead. Also: the actual project page
* where you can download the source code for the library is at <a
#define WIMLIB_MINOR_VERSION 3
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 3
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
* ::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_* *
* ::WIMLIB_ADD_IMAGE_FLAG_VERBOSE. */
#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE 0x00000080
+/** Reparse-point fixups: Modify absolute symbolic links (or junction points,
+ * in the case of Windows) that point inside the directory being captured to
+ * instead be absolute relative to the directory being captured, rather than the
+ * current root; also exclude absolute symbolic links that point outside the
+ * directory tree being captured.
+ *
+ * Without this flag, the default is to do this if WIM_HDR_FLAG_RP_FIX is set in
+ * the WIM header or if this is the first image being added.
+ * WIM_HDR_FLAG_RP_FIX is set if the first image in a WIM is captured with
+ * reparse point fixups enabled and currently cannot be unset. */
+#define WIMLIB_ADD_IMAGE_FLAG_RPFIX 0x00000100
+
+/* Don't do reparse point fixups. The default behavior is described in the
+ * documentation for ::WIMLIB_ADD_IMAGE_FLAG_RPFIX. */
+#define WIMLIB_ADD_IMAGE_FLAG_NORPFIX 0x00000200
+
/******************************
* WIMLIB_EXPORT_FLAG_* *
******************************/
* not have permission to set the desired one. */
#define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080
+/* Extract equivalent to ::WIMLIB_ADD_IMAGE_FLAG_RPFIX; force reparse-point
+ * fixups on, so absolute symbolic links or junction points will be fixed to be
+ * absolute relative to the actual extraction root. Done by default if
+ * WIM_HDR_FLAG_RP_FIX is set in the WIM header. */
+#define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100
+
+/** Force reparse-point fixups on extraction off, regardless of the state of the
+ * WIM_HDR_FLAG_RP_FIX flag in the WIM header. */
+#define WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200
+
/******************************
* WIMLIB_MOUNT_FLAG_* *
******************************/
* deleting an image in this way. */
#define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000010
+/** Assume that strings are represented in UTF-8, even if this is not the
+ * locale's character encoding. */
+#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
+
#if 0
/****************************************************************
WIMLIB_ERR_ICONV_NOT_AVAILABLE,
WIMLIB_ERR_IMAGE_COUNT,
WIMLIB_ERR_IMAGE_NAME_COLLISION,
+ WIMLIB_ERR_INSUFFICIENT_PRIVILEGES_TO_EXTRACT,
WIMLIB_ERR_INTEGRITY,
WIMLIB_ERR_INVALID_CAPTURE_CONFIG,
WIMLIB_ERR_INVALID_CHUNK_SIZE,
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_REPARSE_DATA,
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_REPARSE_POINT_FIXUP_FAILED,
WIMLIB_ERR_RESOURCE_ORDER,
WIMLIB_ERR_SPECIAL_FILE,
WIMLIB_ERR_SPLIT_INVALID,
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_VOLUME_LACKS_FEATURES,
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);
* threads, then you must call this function serially first.
*
* Since wimlib 1.3.0, you must call this function if the character encoding of
- * the current locale is not UTF-8.
+ * the current locale is not UTF-8 and you do not want wimlib to assume a UTF-8
+ * encoding.
*
* Since wimlib 1.3.2, you must call this function if using the Windows-native
* build of the library so that certain functions can be dynamically loaded from
* system DLLs.
*
- * This function currently always returns 0, but it may return other error codes
- * in future releases.
+ * Since wimlib 1.3.3, this function takes the @a init_flags parameter.
+ *
+ * @param init_flags
+ * ::WIMLIB_INIT_FLAG_ASSUME_UTF8 if wimlib should assume that all input
+ * data, including filenames, are in UTF-8, and that UTF-8 data can be
+ * directly printed to the console.
+ *
+ * @return 0; other error codes may be returned in future releases.
*/
extern int
-wimlib_global_init();
+wimlib_global_init(int init_flags);
/**
* Since wimlib 1.2.6: Cleanup function for wimlib. This is not re-entrant.
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