* @brief External header for wimlib.
*
* This file contains comments for generating documentation with Doxygen. The
- * built HTML documentation can be viewed at http://wimlib.sourceforge.net.
- * Make sure to see the <a href="modules.html">Modules page</a> to make more
- * sense of the declarations in this header.
+ * built HTML documentation can be viewed at http://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.
*/
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.8.1, a C
+ * This is the documentation for the library interface of wimlib 1.8.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
* program, please see the manual pages and also the <a
- * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/README">README
+ * href="http://wimlib.net/gitlist/wimlib/blob/master/README">README
* file</a>.
*
* @section sec_installing Installing
*
* @subsection UNIX
*
- * 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>.
+ * Download the source code from http://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>.
*
* @subsection Windows
*
* 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".
+ * (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
+ * 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.
+ * Several examples are located in the "examples" 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
+ * 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
* capabilities of wimlib.
*
* @section backwards_compatibility Backwards Compatibility
*
* wimlib_update_image() can add, delete, and rename files in a WIM image.
*
- * wimlib_set_image_name(), wimlib_set_image_descripton(), and
- * wimlib_set_image_flags() can change other image metadata.
+ * wimlib_set_image_name(), wimlib_set_image_descripton(),
+ * wimlib_set_image_flags(), and wimlib_set_image_property() can change other
+ * image metadata.
*
* wimlib_set_wim_info() can change information about the WIM file itself, such
* as the boot index.
#define WIMLIB_MINOR_VERSION 8
/** 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" {
*/
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
-/** EXPERIMENTAL and only works on Windows 10 and later: compress the extracted
- * files using the System Compression feature (when possible). System
- * Compression is only supported by Windows 10 or later. Several different
- * compression formats may be used with System Compression; this particular flag
- * selects the XPRESS compression format with 4096 byte chunks. <b>This flag is
- * currently experimental and may be changed or removed in future releases of
- * wimlib.</b> */
+/**
+ * Since wimlib v1.8.2 and Windows-only: compress the extracted files using
+ * System Compression, when possible. This only works on either Windows 10 or
+ * later, or on an older Windows to which Microsoft's wofadk.sys driver has been
+ * added. Several different compression formats may be used with System
+ * Compression; this particular flag selects the XPRESS compression format with
+ * 4096 byte chunks.
+ */
#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000
/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
- * 8192 byte chunks. <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b> */
+ * 8192 byte chunks. */
#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000
/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
- * 16384 byte chunks. <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b> */
+ * 16384 byte chunks. */
#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000
/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with
- * 32768 byte chunks. <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b> */
+ * 32768 byte chunks. */
#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000
/** @} */
WIMLIB_ERR_INVALID_UTF8_STRING = 31,
WIMLIB_ERR_IS_DIRECTORY = 32,
WIMLIB_ERR_IS_SPLIT_WIM = 33,
- WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE = 34,
WIMLIB_ERR_LINK = 35,
WIMLIB_ERR_METADATA_NOT_FOUND = 36,
WIMLIB_ERR_MKDIR = 37,
WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81,
WIMLIB_ERR_FVE_LOCKED_VOLUME = 82,
WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83,
+ WIMLIB_ERR_WIM_IS_INCOMPLETE = 84,
};
extern const wimlib_tchar *
wimlib_get_image_name(const WIMStruct *wim, int image);
+/**
+ * @ingroup G_wim_information
+ *
+ * Since wimlib v1.8.3: get a per-image property from the WIM's XML document.
+ * This is an alternative to wimlib_get_image_name() and
+ * wimlib_get_image_description() which allows getting any simple string
+ * property.
+ *
+ * @param wim
+ * Pointer to the ::WIMStruct for the WIM.
+ * @param image
+ * The 1-based index of the image for which to get the property.
+ * @param property_name
+ * The name of the image property, for example "NAME", "DESCRIPTION", or
+ * "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.
+ *
+ * @return
+ * The property's value as a ::wimlib_tchar string, or @c NULL if there is
+ * no such property. The string may not remain valid after later library
+ * calls, so the caller should duplicate it if needed.
+ */
+extern const wimlib_tchar *
+wimlib_get_image_property(const WIMStruct *wim, int image,
+ const wimlib_tchar *property_name);
+
/**
* @ingroup G_general
*
* @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED
* The WIM cannot be opened because it contains encrypted segments. (It
* may be a Windows 8 "ESD" file.)
+ * @retval ::WIMLIB_ERR_WIM_IS_INCOMPLETE
+ * The WIM file is not complete (e.g. the program which wrote it was
+ * terminated before it finished)
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
* considered read-only because of any of the reasons mentioned in the
/**
* @ingroup G_writing_and_overwriting_wims
*
- * Commit a ::WIMStruct to disk, overwriting its backing file or appending to it
- * as needed.
+ * Commit a ::WIMStruct to disk, updating its backing file.
*
- * There are two alternative ways in which changes may be committed:
+ * There are several alternative ways in which changes may be committed:
*
* 1. Full rebuild: write the updated WIM to a temporary file, then rename the
* temporary file to the original.
* 2. Appending: append updates to the new original WIM file, then overwrite
* its header such that those changes become visible to new readers.
*
- * Append mode is often much faster, but it wastes some amount of space due to
- * leaving "holes" in the WIM file. Because of the greater efficiency,
- * wimlib_overwrite() normally defaults to append mode. However,
- * ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild.
- * In addition, if wimlib_delete_image() has been used on the ::WIMStruct, then
- * the default mode switches to rebuild mode, and
+ * Append mode is often much faster than a full rebuild, but it wastes some
+ * amount of space due to leaving "holes" in the WIM file. Because of the
+ * greater efficiency, wimlib_overwrite() normally defaults to append mode.
+ * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full
+ * rebuild. In addition, if wimlib_delete_image() has been used on the
+ * ::WIMStruct, then the default mode switches to rebuild mode, and
* ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append
* mode.
*
extern int
wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
+/**
+ * @ingroup G_modifying_wims
+ *
+ * Since wimlib v1.8.3: add, modify, or remove a per-image property from the
+ * WIM's XML document. This is an alternative to wimlib_set_image_name(),
+ * wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows
+ * manipulating any simple string property.
+ *
+ * @param wim
+ * Pointer to the ::WIMStruct for the WIM.
+ * @param image
+ * The 1-based index of the image for which to set the property.
+ * @param property_name
+ * The name of the image property in the same format documented for
+ * wimlib_get_image_property().
+ * @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.
+ *
+ * @return 0 on success; a ::wimlib_error_code value on failure.
+ *
+ * @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.
+ */
+extern int
+wimlib_set_image_property(WIMStruct *wim, int image,
+ const wimlib_tchar *property_name,
+ const wimlib_tchar *property_value);
+
/**
* @ingroup G_general
*
git://wimlib.net / wimlib / blobdiff