X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=0347014810bbb86523ecda5d0e6aa334b50bbc3b;hb=39b2d3b483fa16d35630f3d83f252b5dc590295f;hp=a45ebac308c5d829db4eaaf90fda0e0c7b7d711a;hpb=bdf5880ca32d1ae20933caedb4a5e4809ede4678;p=wimlib
diff --git a/include/wimlib.h b/include/wimlib.h
index a45ebac3..03470148 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -11,11 +11,11 @@
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.10.0, a C
+ * This is the documentation for the library interface of wimlib 1.13.6, 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.
*
* @section sec_installing Installing
@@ -31,13 +31,16 @@
*
* Download the Windows binary distribution with the appropriate architecture
* (i686 or x86_64 --- also called "x86" and "amd64" respectively) from
- * https://wimlib.net. Link your program with the libwim-15.dll file. Make
- * sure to also download the source code so you can get wimlib.h, as it is not
- * included in the binary distribution. If you need to access the DLL from
- * other programming languages, note that the calling convention is "cdecl".
+ * https://wimlib.net. Link your program with libwim-15.dll. If needed by your
+ * programming language or development environment, the import library
+ * libwim.lib and C/C++ header wimlib.h can be found in the directory "devel" in
+ * the ZIP file.
*
- * Note that wimlib is developed using MinGW-w64, and there may be a little work
- * required if you plan to use the header and DLL with Visual Studio.
+ * If you need to access the DLL from non-C/C++ programming languages, note that
+ * the calling convention is "cdecl".
+ *
+ * If you want to build wimlib from source on Windows, see README.WINDOWS. This
+ * is only needed if you are making modifications to wimlib.
*
* @section sec_examples Examples
*
@@ -388,8 +391,14 @@
#include
#include
-#include
-#include
+#ifndef __cplusplus
+# if defined(_MSC_VER) && _MSC_VER < 1800 /* VS pre-2013? */
+ typedef unsigned char bool;
+# else
+# include
+# endif
+#endif
+#include
#include
/** @addtogroup G_general
@@ -399,25 +408,28 @@
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 10
+#define WIMLIB_MINOR_VERSION 13
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 6
#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 {
+ * To represent file timestamps, wimlib's API originally used the POSIX 'struct
+ * timespec'. This was a mistake because when building wimlib for 32-bit
+ * Windows with MinGW we ended up originally using 32-bit time_t which isn't
+ * year 2038-safe, and therefore we had to later add fields like
+ * 'creation_time_high' to hold the high 32 bits of each timestamp. Moreover,
+ * old Visual Studio versions did not define struct timespec, while newer ones
+ * define it but with 64-bit tv_sec. So to at least avoid a missing or
+ * incompatible 'struct timespec' definition, define the correct struct
+ * ourselves when this header is included on Windows.
+ */
+#ifdef _WIN32
+struct wimlib_timespec {
/* Seconds since start of UNIX epoch (January 1, 1970) */
#ifdef _WIN64
int64_t tv_sec;
@@ -426,9 +438,9 @@ typedef struct {
#endif
/* Nanoseconds (0-999999999) */
int32_t tv_nsec;
-} wimlib_timespec;
+};
#else
-# define wimlib_timespec struct timespec /* standard definition */
+# define wimlib_timespec timespec /* standard definition */
#endif
/**
@@ -637,7 +649,8 @@ enum wimlib_progress_msg {
* to ::wimlib_progress_info.write_streams. This message may be
* received many times while the WIM file is being written or appended
* to with wimlib_write(), wimlib_overwrite(), or wimlib_write_to_fd().
- */
+ * Since wimlib v1.13.4 it will also be received when a split WIM part
+ * is being written by wimlib_split(). */
WIMLIB_PROGRESS_MSG_WRITE_STREAMS = 12,
/** Per-image metadata is about to be written to the WIM file. @p info
@@ -813,7 +826,8 @@ union wimlib_progress_info {
/** The number of bytes of file data that have been written so
* far. This starts at 0 and ends at @p total_bytes. This
* number is the uncompressed size; the actual size may be lower
- * due to compression. */
+ * due to compression. See @p completed_compressed_bytes for
+ * the compressed size. */
uint64_t completed_bytes;
/** The number of distinct file data "blobs" that have been
@@ -836,6 +850,10 @@ union wimlib_progress_info {
/** This is currently broken and will always be 0. */
uint32_t completed_parts;
+
+ /** Since wimlib v1.13.4: Like @p completed_bytes, but counts
+ * the compressed size. */
+ uint64_t completed_compressed_bytes;
} write_streams;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
@@ -1381,20 +1399,23 @@ struct wimlib_wim_info {
* sha1_hash. This case can only occur with wimlib_iterate_dir_tree(), never
* wimlib_iterate_lookup_table().
*
- * 2. Otherwise we know the sha1_hash, the uncompressed_size, the
- * reference_count, and the is_metadata flag. In addition:
+ * 2. Otherwise we know the uncompressed_size, the reference_count, and the
+ * is_metadata flag. In addition:
*
* A. If the blob is located in a non-solid WIM resource, then we also know
- * the compressed_size and offset.
+ * the sha1_hash, compressed_size, and offset.
*
* B. If the blob is located in a solid WIM resource, then we also know the
- * offset, raw_resource_offset_in_wim, raw_resource_compressed_size, and
- * raw_resource_uncompressed_size. But the "offset" is actually the
- * offset in the uncompressed solid resource rather than the offset from
- * the beginning of the WIM file.
+ * sha1_hash, offset, raw_resource_offset_in_wim,
+ * raw_resource_compressed_size, and raw_resource_uncompressed_size. But
+ * the "offset" is actually the offset in the uncompressed solid resource
+ * rather than the offset from the beginning of the WIM file.
*
- * C. If the blob is *not* located in any type of WIM resource, then we don't
- * know any additional information.
+ * C. If the blob is *not* located in any type of WIM resource, for example
+ * if it's in a external file that was scanned by wimlib_add_image(), then
+ * we usually won't know any more information. The sha1_hash might be
+ * known, and prior to wimlib v1.13.6 it always was; however, in wimlib
+ * v1.13.6 and later, the sha1_hash might not be known in this case.
*
* Unknown or irrelevant fields are left zeroed.
*/
@@ -1414,7 +1435,8 @@ struct wimlib_resource_entry {
* of this blob within that solid resource when uncompressed. */
uint64_t offset;
- /** The SHA-1 message digest of the blob's uncompressed contents. */
+ /** If this blob is located in a WIM resource, then this is the SHA-1
+ * message digest of the blob's uncompressed contents. */
uint8_t sha1_hash[20];
/** If this blob is located in a WIM resource, then this is the part
@@ -1582,13 +1604,13 @@ struct wimlib_dir_entry {
uint64_t hard_link_group_id;
/** Time this file was created. */
- wimlib_timespec creation_time;
+ struct wimlib_timespec creation_time;
/** Time this file was last written to. */
- wimlib_timespec last_write_time;
+ struct wimlib_timespec last_write_time;
/** Time this file was last accessed. */
- wimlib_timespec last_access_time;
+ struct wimlib_timespec last_access_time;
/** The UNIX user ID of this file. This is a wimlib extension.
*
@@ -1617,7 +1639,21 @@ struct wimlib_dir_entry {
* object_id.object_id is not all zeroes. */
struct wimlib_object_id object_id;
- uint64_t reserved[6];
+ /** High 32 bits of the seconds portion of the creation timestamp,
+ * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */
+ int32_t creation_time_high;
+
+ /** High 32 bits of the seconds portion of the last write timestamp,
+ * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */
+ int32_t last_write_time_high;
+
+ /** High 32 bits of the seconds portion of the last access timestamp,
+ * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */
+ int32_t last_access_time_high;
+
+ int32_t reserved2;
+
+ uint64_t reserved[4];
/**
* Variable-length array of streams that make up this file.
@@ -1702,8 +1738,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID
* (major and minor number) of each file. In addition, capture special files
- * such as device nodes and FIFOs. See the documentation for the
- * --unix-data option to wimcapture for more information. */
+ * such as device nodes and FIFOs. Since wimlib v1.11.0, on Linux also capture
+ * extended attributes. See the documentation for the --unix-data option
+ * to wimcapture for more information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS-3G capture
@@ -1895,9 +1932,12 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* wimlib_extract_paths() when passed multiple paths. */
#define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001
-/** UNIX-like systems only: Extract special UNIX data captured with
- * ::WIMLIB_ADD_FLAG_UNIX_DATA. This flag cannot be combined with
- * ::WIMLIB_EXTRACT_FLAG_NTFS. */
+/** Since wimlib v1.13.4: Don't consider corrupted files to be an error. Just
+ * extract them in whatever form we can. */
+#define WIMLIB_EXTRACT_FLAG_RECOVER_DATA 0x00000002
+
+/** UNIX-like systems only: Extract UNIX-specific metadata captured with
+ * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020
/** Do not extract security descriptors. This flag cannot be combined with
@@ -2057,8 +2097,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* name, a colon, then the name of the data stream. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010
-/** Use UNIX metadata if available in the WIM image. See
- * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
+/** Support UNIX owners, groups, modes, and special files. */
#define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020
/** Allow other users to see the mounted filesystem. This passes the @c
@@ -2558,6 +2597,8 @@ enum wimlib_error_code {
WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87,
WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88,
WIMLIB_ERR_SNAPSHOT_FAILURE = 89,
+ WIMLIB_ERR_INVALID_XATTR = 90,
+ WIMLIB_ERR_SET_XATTR = 91,
};
@@ -2711,7 +2752,7 @@ wimlib_add_tree(WIMStruct *wim, int image,
* @param wim_ret
* On success, a pointer to the new ::WIMStruct is written to the memory
* location pointed to by this parameter. This ::WIMStruct must be freed
- * using using wimlib_free() when finished with it.
+ * using wimlib_free() when finished with it.
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
@@ -3028,6 +3069,9 @@ wimlib_extract_image_from_pipe_with_progress(int pipe_fd,
* are otherwise delimited by the newline character. However, quotes will be
* stripped if present.
*
+ * If @p path_list_file is @c NULL, then the pathlist file is read from standard
+ * input.
+ *
* The error codes are the same as those returned by wimlib_extract_paths(),
* except that wimlib_extract_pathlist() returns an appropriate error code if it
* cannot read the path list file (e.g. ::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT,
@@ -3246,6 +3290,16 @@ wimlib_get_image_property(const WIMStruct *wim, int image,
extern uint32_t
wimlib_get_version(void);
+/**
+ * @ingroup G_general
+ *
+ * Since wimlib v1.13.0: like wimlib_get_version(), but returns the full
+ * PACKAGE_VERSION string that was set at build time. (This allows a beta
+ * release to be distinguished from an official release.)
+ */
+extern const wimlib_tchar *
+wimlib_get_version_string(void);
+
/**
* @ingroup G_wim_information
*
@@ -3583,8 +3637,8 @@ wimlib_mount_image(WIMStruct *wim,
* @param wim_ret
* On success, a pointer to a new ::WIMStruct backed by the specified
* on-disk WIM file is written to the memory location pointed to by this
- * parameter. This ::WIMStruct must be freed using using wimlib_free()
- * when finished with it.
+ * parameter. This ::WIMStruct must be freed using wimlib_free() when
+ * finished with it.
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
@@ -3974,10 +4028,7 @@ wimlib_resolve_image(WIMStruct *wim,
* This also enables error messages, as if by a call to
* wimlib_set_print_errors(true).
*
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_UNSUPPORTED
- * wimlib was compiled using the --without-error-messages option.
+ * @return 0
*/
extern int
wimlib_set_error_file(FILE *fp);
@@ -3995,8 +4046,6 @@ wimlib_set_error_file(FILE *fp);
*
* @retval ::WIMLIB_ERR_OPEN
* The file named by @p path could not be opened for appending.
- * @retval ::WIMLIB_ERR_UNSUPPORTED
- * wimlib was compiled using the --without-error-messages option.
*/
extern int
wimlib_set_error_file_by_name(const wimlib_tchar *path);
@@ -4194,10 +4243,7 @@ wimlib_set_output_pack_compression_type(WIMStruct *wim,
* @c true if messages are to be printed; @c false if messages are not to
* be printed.
*
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_UNSUPPORTED
- * wimlib was compiled using the --without-error-messages option.
+ * @return 0
*/
extern int
wimlib_set_print_errors(bool show_messages);
@@ -4265,7 +4311,9 @@ wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info,
* If a progress function is registered with @p wim, then for each split WIM
* part that is written it will receive the messages
* ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and
- * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART.
+ * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART. Since wimlib v1.13.4 it will also
+ * receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages while writing each part;
+ * these messages will report the progress of the current part only.
*/
extern int
wimlib_split(WIMStruct *wim,