X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=9c043c1ba5d31e2d112c4ba8997ec481508bc832;hp=398a8fb6e7cd758055bb9fb8eb8cf1b62b4c8a5b;hb=4c532e2a9f1a40e1c1a6ed44a50025cfbfab6e4f;hpb=d828350d6065d39d761df687085be478acc88371

diff --git a/include/wimlib.h b/include/wimlib.h
index 398a8fb6..9c043c1b 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -31,28 +31,45 @@
 /**
  * @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
  *
@@ -88,6 +105,10 @@
  * 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
@@ -362,7 +383,7 @@
 #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" {
@@ -599,6 +620,12 @@ enum wimlib_progress_msg {
 	/** 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
@@ -868,10 +895,11 @@ union wimlib_progress_info {
 		 * 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.  */
@@ -1003,6 +1031,28 @@ union wimlib_progress_info {
 		/** 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;
 };
 
 /**
@@ -1915,6 +1965,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #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
  * @{ */