X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=af167428bde155541d3fcbfaba720afc85818756;hb=ac2f455531e39641bedca08ab510a8c1d09ba125;hp=faececa310df642f92c3514ba32937dd235f9235;hpb=61db93f82eca3fe9f7676355c709c58cc425a6ad;p=wimlib

diff --git a/include/wimlib.h b/include/wimlib.h
index faececa3..af167428 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -1207,9 +1207,18 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  ******************************/
 
 /** Assume that strings are represented in UTF-8, even if this is not the
- * locale's character encoding. */
+ * locale's character encoding.  Not used on Windows.  */
 #define WIMLIB_INIT_FLAG_ASSUME_UTF8			0x00000001
 
+/** Windows-only: do not attempt to acquire additional privileges (currently
+ * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and
+ * SeTakeOwnershipPrivilege) when initializing the library.  This is intended
+ * for the case where the calling program manages these privileges itself.
+ * Note: no error is issued if privileges cannot be acquired, although related
+ * errors may be reported later, depending on if the operations performed
+ * actually require additional privileges or not.  */
+#define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES	0x00000002
+
 /** Specification of an update to perform on a WIM image. */
 struct wimlib_update_command {
 
@@ -1872,7 +1881,8 @@ wimlib_extract_image(WIMStruct *wim, int image,
 		     wimlib_progress_func_t progress_func);
 
 /**
- * Extract one or more images from a pipe on which a pipable WIM is being sent.
+ * Since wimlib v1.5.0:  Extract one or more images from a pipe on which a
+ * pipable WIM is being sent.
  *
  * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information
  * about pipable WIMs.
@@ -1890,7 +1900,9 @@ wimlib_extract_image(WIMStruct *wim, int image,
  *	String that specifies the 1-based index or name of the image to extract.
  *	It is translated to an image index using the same rules that
  *	wimlib_resolve_image() uses.  However, unlike wimlib_extract_image(),
- *	only a single image (not all images) can be specified.
+ *	only a single image (not all images) can be specified.  Alternatively,
+ *	specify @p NULL here to use the first image in the WIM if it contains
+ *	exactly one image but otherwise return @p WIMLIB_ERR_INVALID_IMAGE.
  * @param target
  *	Same as the corresponding parameter to wimlib_extract_image().
  * @param extract_flags
@@ -2059,14 +2071,13 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info);
 
 /**
  * Initialization function for wimlib.  Call before using any other wimlib
- * function.
+ * function except wimlib_set_print_errors().  (However, currently this is not
+ * strictly necessary and it will be called automatically if not done manually,
+ * but you should not rely on this behavior.)
  *
  * @param init_flags
- * 	On UNIX, specify ::WIMLIB_INIT_FLAG_ASSUME_UTF8 if wimlib should assume
- * 	that all input data, including filenames, are in UTF-8 rather than the
- * 	locale-dependent character encoding which may or may not be UTF-8, and
- * 	that UTF-8 data can be directly printed to the console.  On Windows, use
- * 	0 for this parameter.
+ *	Bitwise OR of ::WIMLIB_INIT_FLAG_ASSUME_UTF8 and/or
+ *	::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES.
  *
  * @return 0; other error codes may be returned in future releases.
  */
@@ -2076,7 +2087,7 @@ wimlib_global_init(int init_flags);
 /**
  * Since wimlib 1.2.6:  Cleanup function for wimlib.  This is not re-entrant.
  * You are not required to call this function, but it will release any global
- * memory allocated by the library.
+ * resources allocated by the library.
  */
 extern void
 wimlib_global_cleanup(void);
@@ -2782,6 +2793,8 @@ wimlib_set_memory_allocator(void *(*malloc_func)(size_t),
  *
  * By default, error messages are not printed.
  *
+ * This can be called before wimlib_global_init().
+ *
  * @param show_messages
  * 	@c true if error messages are to be printed; @c false if error messages
  * 	are not to be printed.
@@ -3087,12 +3100,15 @@ wimlib_write(WIMStruct *wim,
 	     wimlib_progress_func_t progress_func);
 
 /**
- * Same as wimlib_write(), but write the WIM directly to a file descriptor,
- * which need not be seekable if the write is done in a special pipable WIM
- * format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p write_flags.  This can,
- * for example, allow capturing a WIM image and streaming it over the network.
- * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information
- * about pipable WIMs.
+ * Since wimlib v1.5.0:  Same as wimlib_write(), but write the WIM directly to a
+ * file descriptor, which need not be seekable if the write is done in a special
+ * pipable WIM format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p
+ * write_flags.  This can, for example, allow capturing a WIM image and
+ * streaming it over the network.  See the documentation for
+ * ::WIMLIB_WRITE_FLAG_PIPABLE for more information about pipable WIMs.
+ *
+ * The file descriptor @p fd will not be closed when the write is complete; the
+ * calling code is responsible for this.
  *
  * Return values are mostly the same as wimlib_write(), but also:
  *