Add support for not extracting file attributes

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index 8bb5cfd6ba68a47e7e84ffaa14b13c497abef81b..c2c32a8c164712ed6001e788d280676726e48c41 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -33,7 +33,7 @@
  *
  * @section sec_intro Introduction
  *
  *
  * @section sec_intro Introduction
  *

- * This is the documentation for the library interface of wimlib 1.6.0, a C
+ * This is the documentation for the library interface of wimlib 1.6.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
  * 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


@@ -350,7 +350,7 @@
 #define WIMLIB_MINOR_VERSION 6
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
 #define WIMLIB_MINOR_VERSION 6
 
 /** 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" {
 
 #ifdef __cplusplus
 extern "C" {


@@ -1514,6 +1514,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * one of the provided globs did not match a file.  */
 #define WIMLIB_EXTRACT_FLAG_STRICT_GLOB                        0x00080000
 
  * one of the provided globs did not match a file.  */
 #define WIMLIB_EXTRACT_FLAG_STRICT_GLOB                        0x00080000
 

+/** Do not extract Windows file attributes such as readonly, hidden, etc.  */
+#define WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES              0x00100000
+

 /** @} */
 /** @ingroup G_mounting_wim_images
  * @{ */
 /** @} */
 /** @ingroup G_mounting_wim_images
  * @{ */


@@ -2071,9 +2074,8 @@ wimlib_add_image_multisource(WIMStruct *wim,
  * images.  No on-disk file is created until wimlib_write() is called.
  *
  * @param ctype
  * images.  No on-disk file is created until wimlib_write() is called.
  *
  * @param ctype

- *     The type of compression to be used in the new WIM file.  Must be
- *     ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX, or
- *     ::WIMLIB_COMPRESSION_TYPE_XPRESS.
+ *     The type of compression to be used in the new WIM file, as one of the
+ *     ::wimlib_compression_type constants.

  * @param wim_ret
  *     On success, a pointer to an opaque ::WIMStruct for the new WIM file is
  *     written to the memory location pointed to by this paramater.  The
  * @param wim_ret
  *     On success, a pointer to an opaque ::WIMStruct for the new WIM file is
  *     written to the memory location pointed to by this paramater.  The


@@ -2081,8 +2083,7 @@ wimlib_add_image_multisource(WIMStruct *wim,
  *     it.
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
  *     it.
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE

- *     @p ctype was not ::WIMLIB_COMPRESSION_TYPE_NONE,
- *     ::WIMLIB_COMPRESSION_TYPE_LZX, or ::WIMLIB_COMPRESSION_TYPE_XPRESS.
+ *     @p ctype was not a supported compression type.

  * @retval ::WIMLIB_ERR_NOMEM
  *     Failed to allocate needed memory.
  */
  * @retval ::WIMLIB_ERR_NOMEM
  *     Failed to allocate needed memory.
  */


@@ -2472,12 +2473,14 @@ wimlib_extract_image_from_pipe(int pipe_fd,
                               wimlib_progress_func_t progress_func);
 
 /**
                               wimlib_progress_func_t progress_func);
 
 /**

- * Similar to wimlib_extract_paths(), but the paths to extract from the WIM
- * image are specified in the UTF-8 text file named by @p path_list_file which
- * itself contains the list of paths to use, one per line.  Leading and trailing
- * whitespace, and otherwise empty lines and lines beginning with the ';'
- * character are ignored.  No quotes are needed as paths are otherwise delimited
- * by the newline character.
+ * @ingroup G_extracting_wims
+ *
+ * Since wimlib v1.6.0:  Similar to wimlib_extract_paths(), but the paths to
+ * extract from the WIM image are specified in the UTF-8 text file named by @p
+ * path_list_file which itself contains the list of paths to use, one per line.
+ * Leading and trailing whitespace, and otherwise empty lines and lines
+ * beginning with the ';' character are ignored.  No quotes are needed as paths
+ * are otherwise delimited by the newline character.

  */
 extern int
 wimlib_extract_pathlist(WIMStruct *wim, int image,
  */
 extern int
 wimlib_extract_pathlist(WIMStruct *wim, int image,


@@ -2487,8 +2490,10 @@ wimlib_extract_pathlist(WIMStruct *wim, int image,
                        wimlib_progress_func_t progress_func);
 
 /**
                        wimlib_progress_func_t progress_func);
 
 /**

- * Similar to wimlib_extract_files(), but the files or directories to extract
- * from the WIM image are specified as an array of paths.
+ * @ingroup G_extracting_wims
+ *
+ * Since wimlib v1.6.0:  Similar to wimlib_extract_files(), but the files or
+ * directories to extract from the WIM image are specified as an array of paths.

  *
  * Each path will be extracted to a corresponding subdirectory of the @p target
  * based on its location in the WIM image.  For example, if one of the paths to
  *
  * Each path will be extracted to a corresponding subdirectory of the @p target
  * based on its location in the WIM image.  For example, if one of the paths to


@@ -2568,12 +2573,11 @@ wimlib_free(WIMStruct *wim);
  * Converts a ::wimlib_compression_type value into a string.
  *
  * @param ctype
  * Converts a ::wimlib_compression_type value into a string.
  *
  * @param ctype

- *     ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX,
- *     ::WIMLIB_COMPRESSION_TYPE_XPRESS, or another value.
+ *     The ::wimlib_compression_type value to convert.

  *
  * @return
  *
  * @return

- *     A statically allocated string: "None", "LZX", "XPRESS", or "Invalid",
- *     respectively.
+ *     A statically allocated string naming the compression algorithm,
+ *     such as "None", "LZX", "XPRESS", or "Invalid".

  */
 extern const wimlib_tchar *
 wimlib_get_compression_type_string(int ctype);
  */
 extern const wimlib_tchar *
 wimlib_get_compression_type_string(int ctype);


@@ -3024,8 +3028,7 @@ wimlib_mount_image(WIMStruct *wim,
  * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
  *     Unexpected end-of-file while reading data from @p wim_file.
  * @retval ::WIMLIB_ERR_UNKNOWN_VERSION
  * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
  *     Unexpected end-of-file while reading data from @p wim_file.
  * @retval ::WIMLIB_ERR_UNKNOWN_VERSION

- *     A number other than 0x10d00 is written in the version field of the WIM
- *     header of @p wim_file.  (May be a pre-Vista WIM.)
+ *     The WIM version number was not recognized. (May be a pre-Vista WIM.)

  * @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
  * @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


@@ -3146,15 +3149,6 @@ wimlib_print_available_images(const WIMStruct *wim, int image);
 extern void
 wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated;
 
 extern void
 wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated;
 

-/**
- * @ingroup G_wim_information
- *
- * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the
- * information in a way that can be accessed programatically.
- */
-extern int
-wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated;
-

 /**
  * @ingroup G_nonstandalone_wims
  *
 /**
  * @ingroup G_nonstandalone_wims
  *


@@ -3383,23 +3377,21 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
  * Set the compression chunk size of a WIM to use in subsequent calls to
  * wimlib_write() or wimlib_overwrite().
  *
  * Set the compression chunk size of a WIM to use in subsequent calls to
  * wimlib_write() or wimlib_overwrite().
  *

- * A compression chunk size will result in a greater compression ratio, but the
- * speed of random access to the WIM will be reduced, and the effect of an
- * increased compression chunk size is limited by the size of each file being
- * compressed.
+ * For compatibility reasons, using this function is not generally recommended.
+ * See the documentation for the @c --chunk-size option of <b>wimlib-imagex
+ * capture</b> for more information.

  *
  *

- * <b>WARNING: Microsoft's software is seemingly incompatible with LZX chunk
- * sizes other than 32768.  Chunk sizes other than 32768 (for any format) are
- * also incompatible with wimlib v1.5.3 and earlier.</b>
+ * A larger compression chunk size will likely result in a better compression
+ * ratio, but the speed of random access to the WIM will be reduced.
+ * Furthermore, the effect of a larger compression chunk size is limited by the
+ * size of each stream ("file") being compressed.

  *
  * @param wim
  *     ::WIMStruct for a WIM.
  * @param chunk_size
  *     The chunk size (in bytes) to set.  The valid chunk sizes are dependent
  *
  * @param wim
  *     ::WIMStruct for a WIM.
  * @param chunk_size
  *     The chunk size (in bytes) to set.  The valid chunk sizes are dependent

- *     on the compression format.  The XPRESS and LZMS compression formats
- *     support chunk sizes that are powers of 2 with exponents between 15 and
- *     26 inclusively, whereas the LZX compression format supports chunk sizes
- *     that are powers of 2 with exponents between 15 and 21 inclusively.  As a
+ *     on the compression format; see the documentation for the @c --chunk-size
+ *     option of <b>wimlib-imagex capture</b> for more information.  As a

  *     special case, if @p chunk_size is specified as 0, the chunk size is set
  *     to the default for the currently selected output compression type.
  *
  *     special case, if @p chunk_size is specified as 0, the chunk size is set
  *     to the default for the currently selected output compression type.
  *


@@ -3447,7 +3439,12 @@ wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
  * @ingroup G_writing_and_overwriting_wims
  *
  * Similar to wimlib_set_output_compression_type(), but set the compression type
  * @ingroup G_writing_and_overwriting_wims
  *
  * Similar to wimlib_set_output_compression_type(), but set the compression type

- * for writing packed streams.
+ * for writing packed streams (solid blocks).
+ *
+ * Note: based on testing, WIMGAPI is seemingly only compatible with LZMS
+ * compression in packed streams.  Therefore the use of this function is not
+ * recommended.  Also, with large chunk sizes, LZMS gives the best compression
+ * ratio among the alternatives anyway.

  */
 extern int
 wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
  */
 extern int
 wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);


@@ -4341,10 +4338,19 @@ wimlib_xpress_decompress(const void *cdata, unsigned clen,
                         void *udata, unsigned ulen)
                _wimlib_deprecated;
 
                         void *udata, unsigned ulen)
                _wimlib_deprecated;
 

+

 /**
  * @}
  */
 
 /**
  * @}
  */
 

+/** @ingroup G_wim_information
+ *
+ * Deprecated and will return ::WIMLIB_ERR_UNSUPPORTED.  Use
+ * wimlib_iterate_dir_tree() instead.  */
+extern int
+wimlib_print_metadata(WIMStruct *wim, int image)
+               _wimlib_deprecated;
+

 
 #ifdef __cplusplus
 }
 
 #ifdef __cplusplus
 }