wimlib: Automatically try to acquire needed privileges on Windows

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index 8c293c8a81d42dbbd867f0b5e6b3878959843737..af167428bde155541d3fcbfaba720afc85818756 100644 (file)
--- 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.
@@ -2061,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.
  */
@@ -2078,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);
@@ -2784,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.
@@ -3089,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:
  *