/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.13.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 (WIM) format. This documentation is intended for developers
* only. If you have installed wimlib and want to know how to use the @b
#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" {
* 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
/** 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
/** 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,
* 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.
*/
* 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
* wimlib_extract_paths() when passed multiple paths. */
#define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001
+/** 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
* @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.
*
* @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.
*
* 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 <c>--without-error-messages</c> option.
+ * @return 0
*/
extern int
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 <c>--without-error-messages</c> option.
*/
extern int
wimlib_set_error_file_by_name(const wimlib_tchar *path);
* @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 <c>--without-error-messages</c> option.
+ * @return 0
*/
extern int
wimlib_set_print_errors(bool show_messages);
* 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,