*/
/*
- * Copyright (C) 2012 Eric Biggers
+ * Copyright (C) 2012, 2013 Eric Biggers
*
* This file is part of wimlib, a library for working with WIM files.
*
*
* \section intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.2.6. If you
+ * This is the documentation for the library interface of wimlib 1.3.0. If you
* have installed wimlib and want to know how to use the @c imagex program,
- * please see the man pages instead.
+ * please see the man pages instead. Also: the actual project page where you
+ * can download the source code for the library is at <a
+ * href="https://sourceforge.net/projects/wimlib">https://sourceforge.net/projects/wimlib</a>.
*
* wimlib is a C library to read, write, and mount archive files in the Windows
* Imaging Format (WIM files). These files are normally created using the @c
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 2
+#define WIMLIB_MINOR_VERSION 3
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 6
+#define WIMLIB_PATCH_VERSION 0
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
/** True iff @a cur_path is being excluded from the image
* capture due to the capture configuration file. */
bool excluded;
+
+ /** Target path in the WIM. Only valid on messages
+ * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
+ * ::WIMLIB_PROGRESS_MSG_SCAN_END. */
+ const char *wim_target_path;
} scan;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
const union wimlib_progress_info *info);
+/** An array of these structures is passed to wimlib_add_image_multisource() to
+ * specify the sources from which to create a WIM image. */
+struct wimlib_capture_source {
+ /** Absolute or relative path to a file or directory on the external
+ * filesystem to be included in the WIM image. */
+ char *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. */
+ char *wim_target_path;
+
+ /** Reserved; set to 0. */
+ long reserved;
+};
+
/*****************************
* WIMLIB_ADD_IMAGE_FLAG_* *
* See the documentation for each wimlib function to see specifically what error
* codes can be returned by a given function, and what they mean.
*/
+/* Note: these are currently in alphabetic order, but new error codes should be
+ * added at the end to maintain a compatible ABI, except when it's being broken
+ * anyway. */
enum wimlib_error_code {
WIMLIB_ERR_SUCCESS = 0,
WIMLIB_ERR_ALREADY_LOCKED,
WIMLIB_ERR_UNSUPPORTED,
WIMLIB_ERR_WRITE,
WIMLIB_ERR_XML,
+ WIMLIB_ERR_INVALID_OVERLAY,
};
* NULL, a default string is used. Please see the manual page for
* <b>imagex capture</b> for more information.
* @param config_len
- * Length of the string @a config in bytes. Ignored if @a config is @c
- * NULL.
+ * Length of the string @a config in bytes, not including an optional
+ * null-terminator. Ignored if @a config is @c NULL.
* @param add_image_flags
* Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.
* @param progress_func
size_t config_len, int add_image_flags,
wimlib_progress_func_t progress_func);
+/** This function is equivalent to wimlib_add_image() except it allows for
+ * multiple sources to be combined into a single WIM image. This is done by
+ * specifying the @a sources and @a num_sources parameters instead of the @a
+ * source parameter of wimlib_add_image(). The rest of the parameters are the
+ * same as wimlib_add_image(). See the documentation for <b>imagex capture</b>
+ * for full details on how this mode works.
+ *
+ * Additional note: @a sources is not a @c const parameter and you cannot
+ * assume that its contents are valid after this function returns. You must
+ * save pointers to the strings in these structures if you need to free them
+ * later, and/or save copies if needed.
+ *
+ * In addition to the error codes that wimlib_add_image() can return,
+ * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY
+ * when trying to overlay a non-directory on a directory or when otherwise
+ * trying to overlay multiple conflicting files to the same location in the WIM
+ * image. It will also return ::WIMLIB_ERR_INVALID_PARAM if
+ * ::WIMLIB_ADD_IMAGE_FLAG_NTFS was specified in @a add_image_flags but there
+ * was not exactly one capture source with the target being the root directory.
+ * (In this respect, there is no advantage to using
+ * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting
+ * NTFS mode.) */
+extern int wimlib_add_image_multisource(WIMStruct *w,
+ struct wimlib_capture_source *sources,
+ size_t num_sources,
+ const char *name,
+ const char *config_str,
+ size_t config_len,
+ int add_image_flags,
+ wimlib_progress_func_t progress_func);
+
/**
* Creates a ::WIMStruct for a new WIM file.
*
* Note: wimlib_export_image() can provide similar functionality to
* wimlib_join(), since it is possible to export all images from a split WIM.
*/
-extern int wimlib_join(const char **swms, unsigned num_swms,
+extern int wimlib_join(const char * const *swms, unsigned num_swms,
const char *output_path, int swm_open_flags,
int wim_write_flags,
wimlib_progress_func_t progress_func);