X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=1de5d045801bb5eeb09300a748c1a8d9e932cc6b;hp=1b476be24763990d6112f2b479561feb7b89dc76;hb=7bde3fc590afbdef8f71cd7f8ccbd24172bffc63;hpb=17dd0feabb235443ca310bfafbd95adfa54924cb

diff --git a/src/wimlib.h b/src/wimlib.h
index 1b476be2..1de5d045 100644
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -31,7 +31,7 @@
  *
  * \section intro Introduction
  *
- * This is the documentation for the library interface of wimlib 1.2.1.  If you
+ * This is the documentation for the library interface of wimlib 1.2.5.  If you
  * have installed wimlib and want to know how to use the @c imagex program,
  * please see the man pages instead.
  *
@@ -217,7 +217,7 @@
 
 #define WIMLIB_MAJOR_VERSION 1
 #define WIMLIB_MINOR_VERSION 2
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 5
 
 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
@@ -745,14 +745,19 @@ enum wimlib_error_code {
 /**
  * Adds an image to a WIM file from an on-disk directory tree or NTFS volume.
  *
- * The directory tree is read immediately for the purpose of constructing a
- * directory entry tree in-memory.  Also, all files are read to calculate their
- * SHA1 message digests.  However, because the directory tree may contain a very
- * large amount of data, the files themselves are not read into memory
- * permanently, and instead references to their paths saved.  The files are then
- * read on-demand if wimlib_write() or wimlib_overwrite() is called.
+ * The directory tree of NTFS volume is read immediately for the purpose of
+ * constructing a directory entry tree in-memory.  Also, all files are read to
+ * calculate their SHA1 message digests.  However, because the directory tree
+ * may contain a very large amount of data, the files themselves are not read
+ * into memory permanently, and instead references to their paths saved.  The
+ * files are then read on-demand if wimlib_write() or wimlib_overwrite() is
+ * called.
  *
- * Please note that @b no changes are committed to the underlying WIM file (if
+ * See the manual page for the @c imagex program for more information about the
+ * "normal" capture mode versus the NTFS capture mode (entered by providing the
+ * flag ::WIMLIB_ADD_IMAGE_FLAG_NTFS).
+ *
+ * Note that @b no changes are committed to the underlying WIM file (if
  * any) until wimlib_write() or wimlib_overwrite() is called.
  *
  * @param wim
@@ -770,17 +775,8 @@ enum wimlib_error_code {
  * @param config_len
  * 	Length of the string @a config in bytes.  Ignored if @a config is @c
  * 	NULL.
- *
  * @param add_image_flags
- * 	Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_BOOT is specified, the image in @a wim that is
- * 	marked as bootable is changed to the one being added.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_VERBOSE is specified, the name of each file is
- * 	printed as it is scanned or captured.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE is specified, the files or
- * 	directories pointed to by symbolic links are archived rather than the
- * 	symbolic links themselves.
- *
+ * 	Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.
  * @param progress_func
  * 	If non-NULL, a function that will be called periodically with the
  * 	progress of the current operation.
@@ -1286,6 +1282,34 @@ extern int wimlib_get_num_images(const WIMStruct *wim);
  */
 extern int wimlib_get_part_number(const WIMStruct *wim, int *total_parts_ret);
 
+/**
+ * Since wimlib 1.2.6:  Initialization function for wimlib.  This is not
+ * re-entrant.  If you are calling wimlib functions concurrently in different
+ * threads, then you must call this function serially first.  Otherwise, calling
+ * this function is not required.
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_NOMEM
+ * 	Could not allocate memory.
+ * @retval ::WIMLIB_ERR_ICONV_NOT_AVAILABLE
+ * 	wimlib was configured --without-libntfs-3g at compilation time, and at
+ * 	runtime the iconv() set of functions did not seem to be available,
+ * 	perhaps due to missing files in the C library installation.
+ *
+ * If this function is not called or returns nonzero, then it will not be safe
+ * to use wimlib in multiple threads.  Furthermore, a nonzero return value here
+ * indicates that further calls into wimlib will probably fail when they try to
+ * repeat the same initializations.
+ */
+extern int wimlib_global_init();
+
+/**
+ * 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.
+ */
+extern void wimlib_global_cleanup();
+
 /**
  * Returns true if the WIM has an integrity table.
  *
@@ -1845,7 +1869,7 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const char *flags);
  * @param image
  * 	The number of the image for which to change the name.
  * @param name
- * 	The new name to give the image.  It must not a nonempty string.
+ * 	The new name to give the image.  It must be a nonempty string.
  *
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
@@ -1938,7 +1962,7 @@ extern int wimlib_set_print_errors(bool show_messages);
  * @return 0 on success; nonzero on error.  This function may return any value
  * returned by wimlib_write() as well as the following error codes:
  *
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED:
+ * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
  * 	@a wim is not part 1 of a stand-alone WIM.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
  * 	@a swm_name was @c NULL, or @a part_size was 0.