Add avl_tree_for_each_in_{post,}order() macros and examples

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index 5b164b6d6364577865cfcfdd47e9545e7c77d707..fd55ebf8c23f0b70c8b641dc9923a3599fa7c52b 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -10,7 +10,7 @@
  */
 
 /*
- * Copyright (C) 2012, 2013 Eric Biggers
+ * Copyright (C) 2012, 2013, 2014 Eric Biggers
  *
  * This file is part of wimlib, a library for working with WIM files.
  *
@@ -33,7 +33,7 @@
  *
  * @section sec_intro Introduction
  *
- * This is the documentation for the library interface of wimlib 1.6.1, a C
+ * This is the documentation for the library interface of wimlib 1.6.2, 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
@@ -345,7 +345,7 @@
 #define WIMLIB_MINOR_VERSION 6
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 2
 
 #ifdef __cplusplus
 extern "C" {
@@ -517,8 +517,10 @@ enum wimlib_progress_msg {
         * will not be valid. */
        WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
 
-       /** Confirms that the metadata resource for each image has successfully
-        * been writen to the WIM.  @p info will not be valid.  */
+       /** Confirms that per-image metadata has been successfully been written
+        * to the WIM file.  @p info will not be valid.  This message is paired
+        * with a preceding ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message.
+        */
        WIMLIB_PROGRESS_MSG_WRITE_METADATA_END,
 
        /** wimlib_overwrite() has successfully renamed the temporary file to
@@ -537,8 +539,8 @@ enum wimlib_progress_msg {
 
        /** An integrity table is being calculated for the WIM being written.
         * @p info will point to ::wimlib_progress_info.integrity.  This message
-        * is only received (and may be received many times) when a WIM is being
-        * written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY.  */
+        * is only received (and may be received many times) when a WIM file is
+        * being written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY.  */
        WIMLIB_PROGRESS_MSG_CALC_INTEGRITY,
 
        /** Reserved.  */
@@ -1476,8 +1478,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 
 /** This is the extraction equivalent to ::WIMLIB_ADD_FLAG_RPFIX.  This forces
  * reparse-point fixups on, so absolute symbolic links or junction points will
- * be fixed to be absolute relative to the actual extraction root.  Reparse
- * point fixups are done by default if WIM_HDR_FLAG_RP_FIX is set in the WIM
+ * be fixed to be absolute relative to the actual extraction root.  Reparse-
+ * point fixups are done by default for wimlib_extract_image() and
+ * wimlib_extract_image_from_pipe() if WIM_HDR_FLAG_RP_FIX is set in the WIM
  * header.  This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_NORPFIX.  */
 #define WIMLIB_EXTRACT_FLAG_RPFIX                      0x00000100
 
@@ -1547,8 +1550,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 
 /** For wimlib_extract_paths() and wimlib_extract_pathlist() only:  Do not
  * preserve the directory structure of the archive when extracting --- that is,
- * place each extracted files or directory tree directly in the target
- * directory.  */
+ * place each extracted file or directory tree directly in the target directory.
+ */
 #define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE  0x00200000
 
 /** @} */
@@ -1625,6 +1628,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 /** Do a "lazy" unmount (detach filesystem immediately, even if busy).  */
 #define WIMLIB_UNMOUNT_FLAG_LAZY                       0x00000010
 
+/** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted
+ * image, causes the modified image to be committed as a new, unnamed image
+ * appended to the archive.  The original image will be unmodified.  */
+#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE                  0x00000020
+
 /** @} */
 /** @ingroup G_modifying_wims
  * @{ */
@@ -2269,7 +2277,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
  *
  * As of wimlib v1.6.1, this function is deprecated in favor of
  * wimlib_extract_paths() because wimlib_extract_paths() is easier to use and
- * usually more efficient.
+ * more efficient.
  *
  * Notes: wimlib_extract_files() does not support the
  * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS flag, and
@@ -2677,6 +2685,19 @@ wimlib_get_image_description(const WIMStruct *wim, int image);
 extern const wimlib_tchar *
 wimlib_get_image_name(const WIMStruct *wim, int image);
 
+/**
+ * @ingroup G_general
+ *
+ * Returns the version of wimlib as a 32-bit number whose top 12 bits contain
+ * the major version, the next 10 bits contain the minor version, and the low 10
+ * bits contain the patch version.
+ *
+ * In other words, the returned value is equal to <code>((WIMLIB_MAJOR_VERSION
+ * << 22) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</code> for the
+ * corresponding header file.
+ */
+extern uint32_t
+wimlib_get_version(void);
 
 /**
  * @ingroup G_wim_information