X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=d22eb5811ffab8584caa3d30db7291ad0f606319;hp=e4ae34411babc20c55826ae4b420ae980766fcfb;hb=ef01d3a49d4a0e83f0fb5bd6604a1b7ebeee71a1;hpb=f0654e95701359ba8318601a6abeb01f0bad52eb
diff --git a/include/wimlib.h b/include/wimlib.h
index e4ae3441..d22eb581 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -11,12 +11,12 @@
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.9.1, a C
+ * This is the documentation for the library interface of wimlib 1.10.0, 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 README file.
+ * href="https://wimlib.net/git/?p=wimlib;a=blob;f=README">README file.
*
* @section sec_installing Installing
*
@@ -45,7 +45,7 @@
* distribution. Also see @ref sec_basic_wim_handling_concepts below.
*
* There is also the
+ * href="https://wimlib.net/git/?p=wimlib;a=blob;f=programs/imagex.c">
* source code of wimlib-imagex, which is complicated but uses most
* capabilities of wimlib.
*
@@ -141,20 +141,21 @@
* messages and strings (as well as all documentation, for that matter) are only
* available in English.
*
- * @section sec_encodings Locales and character encodings
+ * @section sec_encodings Character encoding
*
* To support Windows as well as UNIX-like systems, wimlib's API typically takes
- * and returns strings of ::wimlib_tchar, which are in a platform-dependent
- * encoding.
+ * and returns strings of ::wimlib_tchar which have a platform-dependent type
+ * and encoding.
*
- * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t",
- * and the encoding is UTF-16LE.
+ * On Windows, each ::wimlib_tchar is a 2-byte wchar_t. The encoding
+ * is meant to be UTF-16LE. However, unpaired surrogates are permitted because
+ * neither Windows nor the NTFS filesystem forbids them in filenames.
*
- * On UNIX-like systems, each ::wimlib_tchar is 1 byte and is simply a "char",
- * and the encoding is the locale-dependent multibyte encoding. I recommend you
- * set your locale to a UTF-8 capable locale to avoid any issues. Also, by
- * default, wimlib on UNIX will assume the locale is UTF-8 capable unless you
- * call wimlib_global_init() after having set your desired locale.
+ * On UNIX-like systems, each ::wimlib_tchar is a 1 byte char. The
+ * encoding is meant to be UTF-8. However, for compatibility with Windows-style
+ * filenames that are not valid UTF-16LE, surrogate codepoints are permitted.
+ * Other multibyte encodings (e.g. ISO-8859-1) or garbage sequences of bytes are
+ * not permitted.
*
* @section sec_advanced Additional information and features
*
@@ -388,7 +389,7 @@
#include
#include
#include
-#include
+#include
#include
/** @addtogroup G_general
@@ -398,15 +399,38 @@
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 9
+#define WIMLIB_MINOR_VERSION 10
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 0
#ifdef __cplusplus
extern "C" {
#endif
+/*
+ * To represent file timestamps, wimlib's API uses the POSIX 'struct timespec'.
+ * This was probably a mistake because it doesn't play well with Visual Studio.
+ * In old VS versions it isn't present at all; in newer VS versions it is
+ * supposedly present, but I wouldn't trust it to be the same size as the one
+ * MinGW uses. The solution is to define a compatible structure ourselves when
+ * this header is included on Windows and the compiler is not MinGW.
+ */
+#if defined(_WIN32) && !defined(__GNUC__)
+typedef struct {
+ /* Seconds since start of UNIX epoch (January 1, 1970) */
+#ifdef _WIN64
+ int64_t tv_sec;
+#else
+ int32_t tv_sec;
+#endif
+ /* Nanoseconds (0-999999999) */
+ int32_t tv_nsec;
+} wimlib_timespec;
+#else
+# define wimlib_timespec struct timespec /* standard definition */
+#endif
+
/**
* Opaque structure that represents a WIM, possibly backed by an on-disk file.
* See @ref sec_basic_wim_handling_concepts for more information.
@@ -416,14 +440,14 @@ typedef struct WIMStruct WIMStruct;
#define WIMLIB_WIMSTRUCT_DECLARED
#endif
-#ifdef __WIN32__
+#ifdef _WIN32
typedef wchar_t wimlib_tchar;
#else
/** See @ref sec_encodings */
typedef char wimlib_tchar;
#endif
-#ifdef __WIN32__
+#ifdef _WIN32
/** Path separator for WIM paths passed back to progress callbacks.
* This is forward slash on UNIX and backslash on Windows. */
# define WIMLIB_WIM_PATH_SEPARATOR '\\'
@@ -1558,13 +1582,13 @@ struct wimlib_dir_entry {
uint64_t hard_link_group_id;
/** Time this file was created. */
- struct timespec creation_time;
+ wimlib_timespec creation_time;
/** Time this file was last written to. */
- struct timespec last_write_time;
+ wimlib_timespec last_write_time;
/** Time this file was last accessed. */
- struct timespec last_access_time;
+ wimlib_timespec last_access_time;
/** The UNIX user ID of this file. This is a wimlib extension.
*
@@ -2323,9 +2347,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** @addtogroup G_general
* @{ */
-/** Assume that strings are represented in UTF-8, even if this is not the
- * locale's character encoding. This flag is ignored on Windows, where wimlib
- * always uses UTF-16LE. */
+/** Deprecated; no longer has any effect. */
#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
/** Windows-only: do not attempt to acquire additional privileges (currently
@@ -2462,7 +2484,6 @@ enum wimlib_error_code {
WIMLIB_ERR_DECOMPRESSION = 2,
WIMLIB_ERR_FUSE = 6,
WIMLIB_ERR_GLOB_HAD_NO_MATCHES = 8,
- WIMLIB_ERR_ICONV_NOT_AVAILABLE = 9,
WIMLIB_ERR_IMAGE_COUNT = 10,
WIMLIB_ERR_IMAGE_NAME_COLLISION = 11,
WIMLIB_ERR_INSUFFICIENT_PRIVILEGES = 12,
@@ -2475,7 +2496,6 @@ enum wimlib_error_code {
WIMLIB_ERR_INVALID_INTEGRITY_TABLE = 19,
WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY = 20,
WIMLIB_ERR_INVALID_METADATA_RESOURCE = 21,
- WIMLIB_ERR_INVALID_MULTIBYTE_STRING = 22,
WIMLIB_ERR_INVALID_OVERLAY = 23,
WIMLIB_ERR_INVALID_PARAM = 24,
WIMLIB_ERR_INVALID_PART_NUMBER = 25,
@@ -3278,9 +3298,8 @@ wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret);
*
* Initialization function for wimlib. Call before using any other wimlib
* function (except possibly wimlib_set_print_errors()). If not done manually,
- * this function will be called automatically with @p init_flags set to
- * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. This function does nothing if called again
- * after it has already successfully run.
+ * this function will be called automatically with a flags argument of 0. This
+ * function does nothing if called again after it has already successfully run.
*
* @param init_flags
* Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG.
@@ -4334,8 +4353,9 @@ wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags);
* @ingroup G_mounting_wim_images
*
* Same as wimlib_unmount_image(), but allows specifying a progress function.
- * If changes are committed from a read-write mount, the progress function will
- * receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages.
+ * The progress function will receive a ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN
+ * message. In addition, if changes are committed from a read-write mount, the
+ * progress function will receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages.
*/
extern int
wimlib_unmount_image_with_progress(const wimlib_tchar *dir,