xml.c: support numerically indexed elements in wimlib_{get,set}_image_property()

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index f68cb2b89639376ccc0ae8040277b4664f5d04e9..10f9bb7eb36dee1ebed7284849d715c7d3666c9b 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -3,7 +3,7 @@
  * @brief External header for wimlib.
  *
  * This file contains comments for generating documentation with Doxygen.  The
- * built HTML documentation can be viewed at http://wimlib.net/apidoc.  Make
+ * built HTML documentation can be viewed at https://wimlib.net/apidoc.  Make
  * sure to see the <a href="modules.html">Modules page</a> to make more sense of
  * the declarations in this header.
  */
@@ -11,19 +11,19 @@
 /**
  * @mainpage
  *
- * This is the documentation for the library interface of wimlib 1.8.2, a C
+ * This is the documentation for the library interface of wimlib 1.8.3, 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 manual pages and also the <a
- * href="http://wimlib.net/gitlist/wimlib/blob/master/README">README
+ * href="https://wimlib.net/gitlist/wimlib/blob/master/README">README
  * file</a>.
  *
  * @section sec_installing Installing
  *
  * @subsection UNIX
  *
- * Download the source code from http://wimlib.net.  Install the library by
+ * Download the source code from https://wimlib.net.  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>.
@@ -32,8 +32,8 @@
  *
  * Download the Windows binary distribution with the appropriate architecture
  * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from
- * http://wimlib.net.  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
+ * https://wimlib.net.  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".
  *
@@ -43,8 +43,8 @@
  * distribution.
  *
  * There is also the <a
- * href="http://wimlib.net/gitlist/wimlib/blob/master/programs/imagex.c"> source
- * code of <b>wimlib-imagex</b></a>, which is complicated but uses most
+ * href="https://wimlib.net/gitlist/wimlib/blob/master/programs/imagex.c">
+ * source code of <b>wimlib-imagex</b></a>, which is complicated but uses most
  * capabilities of wimlib.
  *
  * @section backwards_compatibility Backwards Compatibility
@@ -380,7 +380,7 @@
 #define WIMLIB_MINOR_VERSION 8
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 3
 
 #ifdef __cplusplus
 extern "C" {
@@ -1721,6 +1721,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  *
  * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and
  * independent from, ::WIMLIB_ADD_FLAG_BOOT.
+ *
+ * Since wimlib v1.8.3, ::WIMLIB_ADD_FLAG_WIMBOOT also causes offline WIM-backed
+ * files to be added as the "real" files rather than as their reparse points,
+ * provided that their data is already present in the WIM.  This feature can be
+ * useful when updating a backing WIM file in an "offline" state.
  */
 #define WIMLIB_ADD_FLAG_WIMBOOT                        0x00001000
 
@@ -3181,7 +3186,11 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
  *     "TOTALBYTES".  The name can contain forward slashes to indicate a nested
  *     XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD
  *     element nested within the VERSION element nested within the WINDOWS
- *     element.  The <tt>[</tt> character is reserved for future use.
+ *     element.  Since wimlib v1.8.4, a bracketed number can be used to
+ *     indicate one of several identically-named elements; for example,
+ *     "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element
+ *     nested within the "WINDOWS/LANGUAGES" element.  Note that element names
+ *     are case sensitive.
  *
  * @return
  *     The property's value as a ::wimlib_tchar string, or @c NULL if there is
@@ -4038,6 +4047,13 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
  * @param property_name
  *     The name of the image property in the same format documented for
  *     wimlib_get_image_property().
+ *     <br/>
+ *     Note: if creating a new element using a bracketed index such as
+ *     "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified
+ *     is one greater than the number of existing elements with that same name,
+ *     excluding the index.  That means that if you are adding a list of new
+ *     elements, they must be added sequentially from the first index (1) to
+ *     the last index (n).
  * @param property_value
  *     If not NULL and not empty, the property is set to this value.
  *     Otherwise, the property is removed from the XML document.
@@ -4047,7 +4063,8 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  *     @p image does not exist in @p wim.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
- *     @p property_name has an unsupported format.
+ *     @p property_name has an unsupported format, or @p property_name included
+ *     a bracketed index that was too high.
  */
 extern int
 wimlib_set_image_property(WIMStruct *wim, int image,