/**
* @mainpage
*
- * @section sec_intro Introduction
- *
- * This is the documentation for the library interface of wimlib 1.7.0, a C
+ * This is the documentation for the library interface of wimlib 1.7.1, 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
- * program, please see the README file or manual pages.
+ * program, please see the manual pages and also the <a
+ * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/README">README
+ * file</a>.
*
- * @section sec_installing_and_compiling Installing and Compiling
+ * @section sec_installing Installing
*
- * wimlib uses the GNU autotools, so, on UNIX-like systems, it should be easy to
- * install with <code>configure && make && sudo make install</code>; however,
- * please see the README for more information about installing it.
+ * @subsection UNIX
*
- * To use wimlib in your program after installing it, include wimlib.h and link
- * your program with @c -lwim.
+ * Download the source code from <a
+ * href="http://sourceforge.net/projects/wimlib/files">http://sourceforge.net/projects/wimlib/files</a>.
+ * Install the library by running <c>configure && make && sudo make install</c>.
+ * See the README for information about configuration options. To use wimlib in
+ * your program after installing it, include wimlib.h and link your program with
+ * <c>-lwim</c>.
*
- * As of wimlib 1.5.0, wimlib.h is also compatible with C++.
+ * @subsection Windows
*
- * Note: before calling any other function declared in wimlib.h,
- * wimlib_global_init() can (and in some cases, must) be called. See its
- * documentation for more details.
+ * Download the Windows binary distribution with the appropriate architecture
+ * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from <a
+ * href="http://sourceforge.net/projects/wimlib/files">http://sourceforge.net/projects/wimlib/files</a>.
+ * Link your program with the libwim-15.dll file. Make sure to also download
+ * the source code so you can get wimlib.h, as it is not included in the binary
+ * distribution. If you need to access the DLL from other programming
+ * languages, note that the calling convention is "cdecl".
+ *
+ * @section sec_examples Examples
+ *
+ * Several examples are located in the <a
+ * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/examples">examples</a>
+ * directory of the source distribution.
+ *
+ * There is also the <a
+ * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/programs/imagex.c">
+ * source code of <b>wimlib-imagex</b></a>, which is complicated but uses most
+ * capabilities of wimlib.
*
* @section sec_basic_wim_handling_concepts Basic WIM handling concepts
*
* you can make multiple changes to a WIM and commit them all to the underlying
* file in only one overwrite operation, which is more efficient.
*
+ * Note: before calling any other function declared in wimlib.h,
+ * wimlib_global_init() can (and in some cases, must) be called. See its
+ * documentation for more details.
+ *
* @section sec_cleaning_up Cleaning up
*
* After you are done with any ::WIMStruct, you can call wimlib_free() to free
#define WIMLIB_MINOR_VERSION 7
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 1
#ifdef __cplusplus
extern "C" {
/** Starting to unmount a WIM image. @p info will point to
* ::wimlib_progress_info.unmount. */
WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25,
+
+ /** wimlib has used a file's data for the last time (including all data
+ * streams, if it has multiple). @p info will point to
+ * ::wimlib_progress_info.done_with_file. This message is only received
+ * if ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES was provided. */
+ WIMLIB_PROGRESS_MSG_DONE_WITH_FILE = 26,
};
/** Valid return values from user-provided progress functions
* potentially multiple streams per file (named data streams).
* A "stream" may be the default contents of a file, a named
* data stream, or a reparse data buffer. */
- uint64_t num_streams;
+ uint64_t total_streams;
- /** Reserved. */
- const wimlib_tchar *reserved_2;
+ /** Number of (not necessarily unique) streams that have been
+ * extracted so far. */
+ uint64_t completed_streams;
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
/** Flags passed to wimlib_unmount_image(). */
uint32_t unmount_flags;
} unmount;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE. */
+ struct wimlib_progress_info_done_with_file {
+ /* Path to the file whose data has been written to the WIM file,
+ * or is currently being asynchronously compressed in memory,
+ * and therefore is no longer needed by wimlib.
+ *
+ * WARNING: The file data will not actually be accessible in the
+ * WIM file until the WIM file has been completely written.
+ * Ordinarily you should <b>not</b> treat this message as a
+ * green light to go ahead and delete the specified file, since
+ * that would result in data loss if the WIM file cannot be
+ * successfully created for any reason.
+ *
+ * If a file has multiple names (hard links),
+ * ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE will only be received
+ * for one name. Also, this message will not be received for
+ * empty files or reparse points (or symbolic links), unless
+ * they have nonempty named data streams.
+ */
+ const wimlib_tchar *path_to_file;
+ } done_with_file;
};
/**
/** @addtogroup G_modifying_wims
* @{ */
-/** Directly capture an NTFS volume rather than a generic directory. This flag
- * cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or
- * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
+/** UNIX-like systems only: Directly capture an NTFS volume rather than a
+ * generic directory. This requires that wimlib was compiled with support for
+ * libntfs-3g.
+ *
+ * This flag cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or
+ * ::WIMLIB_ADD_FLAG_UNIX_DATA.
+ *
+ * Do not use this flag on Windows, where wimlib already supports all
+ * Windows-native filesystems, including NTFS, through the Windows APIs. */
#define WIMLIB_ADD_FLAG_NTFS 0x00000001
-/** Follow symlinks; archive and dump the files they point to. Currently only
+/** Follow symbolic links when scanning the directory tree. Currently only
* supported on UNIX-like systems. */
#define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002
* scanned. */
#define WIMLIB_ADD_FLAG_VERBOSE 0x00000004
-/** Mark the image being added as the bootable image of the WIM. Not valid for
- * wimlib_update_image(). */
+/** Mark the image being added as the bootable image of the WIM. This flag is
+ * valid only for wimlib_add_image() and wimlib_add_image_multisource().
+ *
+ * Note that you can also change the bootable image of a WIM using
+ * wimlib_set_wim_info().
+ *
+ * Note: ::WIMLIB_ADD_FLAG_BOOT does something different from, and independent
+ * from, ::WIMLIB_ADD_FLAG_WIMBOOT. */
#define WIMLIB_ADD_FLAG_BOOT 0x00000008
/** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID
- * (major and minor number) of each file. See the documentation for the
+ * (major and minor number) of each file. Also allows capturing special files
+ * such as device nodes and FIFOs. See the documentation for the
* <b>--unix-data</b> option to <b>wimlib-imagex capture</b> for more
* information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS capture
- * mode, or in Windows native builds. */
+ * mode, or in Windows native builds. */
#define WIMLIB_ADD_FLAG_NO_ACLS 0x00000020
/** Fail immediately if the full security descriptor of any file or directory
* cannot be accessed. Only has an effect in Windows 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_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_FLAG_VERBOSE. */
+ * ::WIMLIB_ADD_FLAG_VERBOSE. */
#define WIMLIB_ADD_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.
+/** Reparse-point fixups: Modify absolute symbolic links (and junctions, in the
+ * case of Windows) that point inside the directory being captured to instead be
+ * absolute relative to the directory 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. */
+ * Without this flag, the default is to do reparse-point fixups 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_FLAG_RPFIX 0x00000100
-/** Don't do reparse point fixups. The default behavior is described in the
- * documentation for ::WIMLIB_ADD_FLAG_RPFIX. */
+/** Don't do reparse point fixups. See ::WIMLIB_ADD_FLAG_RPFIX. */
#define WIMLIB_ADD_FLAG_NORPFIX 0x00000200
/** Do not automatically exclude unsupported files or directories from capture;
* 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. */
+ * UNIX-like systems when not also using ::WIMLIB_ADD_FLAG_UNIX_DATA. Instead,
+ * fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when 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. For example,
- * "pagefile.sys" and "System Volume Information" will be excluded.
+ * "/pagefile.sys" and "System Volume Information" will be excluded.
*
- * When this flag is specified, the corresponding @p config parameter or member
- * must be @c NULL.
+ * When this flag is specified, the corresponding @p config parameter (for
+ * wimlib_add_image()) or member (for wimlib_update_image()) must be @c NULL.
+ * Otherwise, ::WIMLIB_ERR_INVALID_PARAM will be returned.
*
- * 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
- * no files are excluded from capture.
+ * Note that the default behavior--- that is, when neither
+ * ::WIMLIB_ADD_FLAG_WINCONFIG nor ::WIMLIB_ADD_FLAG_WIMBOOT is specified and @p
+ * config is @c NULL--- is to use no capture configuration, meaning that no
+ * files are excluded from capture.
*/
#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
*
* 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).
+ *
+ * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and
+ * independent from, ::WIMLIB_ADD_FLAG_BOOT.
*/
#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
*/
#define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000
+/**
+ * Send ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM
+ * file. This is only needed in the unusual case that the library user needs to
+ * know exactly when wimlib has read each file for the last time.
+ */
+#define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000
+
/** @} */
/** @addtogroup G_general
* @{ */
wimlib_resolve_image(WIMStruct *wim,
const wimlib_tchar *image_name_or_num);
+/**
+ * Sets the file to which the library will print error and warning messages.
+ *
+ * This version of the function takes a C library <c>FILE *</c> opened for
+ * writing (or appending). Use wimlib_set_error_file_by_name() to specify the
+ * file by name instead.
+ *
+ * This also enables error messages, as if by a call to
+ * wimlib_set_print_errors(true).
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
+ * wimlib was compiled using the <c>--without-error-messages</c> option.
+ */
+extern int
+wimlib_set_error_file(FILE *fp);
+
+/**
+ * Sets the path to the file to which the library will print error and warning
+ * messages. The library will open this file for appending.
+ *
+ * This also enables error messages, as if by a call to
+ * wimlib_set_print_errors(true).
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_OPEN
+ * The file named by @p path could not be opened for appending.
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
+ * wimlib was compiled using the <c>--without-error-messages</c> option.
+ */
+extern int
+wimlib_set_error_file_by_name(const wimlib_tchar *path);
+
/**
* @ingroup G_modifying_wims
*
git://wimlib.net / wimlib / blobdiff