#ifndef _WIMLIB_APPLY_H
#define _WIMLIB_APPLY_H
+#include "wimlib/compiler.h"
#include "wimlib/file_io.h"
-#include "wimlib/types.h"
#include "wimlib/list.h"
+#include "wimlib/progress.h"
+#include "wimlib/types.h"
#include "wimlib.h"
-struct wim_lookup_table_entry;
-struct wimlib_unix_data;
-struct wim_dentry;
-struct apply_ctx;
-
-/* Path to extracted file, or "cookie" identifying the file (e.g. inode number).
- * */
-typedef union {
- const tchar *path;
- u64 cookie;
-} file_spec_t;
-
-/*
- * struct apply_operations - Callback functions for a specific extraction
- * mode/backend. These are lower-level functions that are called by the generic
- * code in extract.c.
- *
- * Unless otherwise specified, the callbacks in this structure are expected to
- * return 0 on success or a WIMLIB_ERR_* value on failure as well as set errno.
- * When possible, error messages should NOT be printed as they are handled by
- * the generic code.
- *
- * Many callbacks are optional, but to extract the most data from the WIM
- * format, as many as possible should be provided, and the corresponding
- * features should be marked as supported in start_extract().
- */
-struct apply_operations {
-
- /* OPTIONAL: Name of this extraction mode. */
- const tchar *name;
-
- /* REQUIRED: Fill in ctx->supported_features with nonzero values for
- * features supported by the extraction mode and volume. This callback
- * can also be used to do any setup needed to access the volume. */
- int (*start_extract)
- (const tchar *path, struct apply_ctx *ctx);
-
- /* OPTIONAL: If root_directory_is_special is set: provide this
- * callback to determine whether the path corresponds to the root of the
- * target volume (%true) or not (%false). */
- bool (*target_is_root)
- (const tchar *target);
-
- /* REQUIRED: Create a file. */
- int (*create_file)
- (const tchar *path, struct apply_ctx *ctx, u64 *cookie_ret);
-
- /* REQUIRED: Create a directory. */
- int (*create_directory)
- (const tchar *path, struct apply_ctx *ctx, u64 *cookie_ret);
-
- /* OPTIONAL: Create a hard link. In start_extract(), set
- * ctx->supported_features.hard_links if supported. */
- int (*create_hardlink)
- (const tchar *oldpath, const tchar *newpath,
- struct apply_ctx *ctx);
-
- /* OPTIONAL: Create a symbolic link. In start_extract(), set
- * ctx->supported_features.symlink_reparse_points if supported. */
- int (*create_symlink)
- (const tchar *oldpath, const tchar *newpath,
- struct apply_ctx *ctx);
-
- /* REQUIRED: Extract unnamed data stream. */
- int (*extract_unnamed_stream)
- (file_spec_t file, struct wim_lookup_table_entry *lte,
- struct apply_ctx *ctx, struct wim_dentry *dentry);
-
- /* OPTIONAL: Extracted named data stream. In start_extract(), set
- * ctx->supported_features.alternate_data_streams if supported. */
- int (*extract_named_stream)
- (file_spec_t file, const utf16lechar *stream_name,
- size_t stream_name_nchars, struct wim_lookup_table_entry *lte,
- struct apply_ctx *ctx);
-
- /* OPTIONAL: Extracted encrypted stream. In start_extract(), set
- * ctx->supported_features.encrypted_files if supported. */
- int (*extract_encrypted_stream)
- (const tchar *path, struct wim_lookup_table_entry *lte,
- struct apply_ctx *ctx);
-
- /* OPTIONAL: Set file attributes. Calling code calls this if non-NULL.
- */
- int (*set_file_attributes)
- (const tchar *path, u32 attributes, struct apply_ctx *ctx,
- unsigned pass);
-
- /* OPTIONAL: Set reparse data. In start_extract(), set
- * ctx->supported_features.reparse_data if supported. */
- int (*set_reparse_data)
- (const tchar *path, const u8 *rpbuf, u16 rpbuflen,
- struct apply_ctx *ctx);
-
- /* OPTIONAL: Set short (DOS) filename. In start_extract(), set
- * ctx->supported_features.short_name if supported. */
- int (*set_short_name)
- (const tchar *path, const utf16lechar *short_name,
- size_t short_name_nchars, struct apply_ctx *ctx);
-
- /* OPTIONAL: Set Windows NT security descriptor. In start_extract(),
- * set ctx->supported_features.security_descriptors if supported. */
- int (*set_security_descriptor)
- (const tchar *path, const u8 *desc, size_t desc_size,
- struct apply_ctx *ctx);
-
- /* OPTIONAL: Set wimlib-specific UNIX data. In start_extract(), set
- * ctx->supported_features.unix_data if supported. */
- int (*set_unix_data)
- (const tchar *path, const struct wimlib_unix_data *data,
- struct apply_ctx *ctx);
-
- /* OPTIONAL: Set timestamps. Calling code calls this if non-NULL. */
- int (*set_timestamps)
- (const tchar *path, u64 creation_time, u64 last_write_time,
- u64 last_access_time, struct apply_ctx *ctx);
-
- /* OPTIONAL: Called after the extraction operation has succeeded. */
- int (*finish_extract)
- (struct apply_ctx *ctx);
-
- /* OPTIONAL: Called after the extraction operation has failed. */
- int (*abort_extract)
- (struct apply_ctx *ctx);
-
- /* REQUIRED: Path separator character to use when building paths. */
- tchar path_separator;
-
- /* REQUIRED: Maximum path length, in tchars, including the
- * null-terminator. */
- unsigned path_max;
-
- /* OPTIONAL: String to prefix every path with. */
- const tchar *path_prefix;
-
- /* OPTIONAL: Length of path_prefix in tchars. */
- unsigned path_prefix_nchars;
-
- /* OPTIONAL: Set to 1 if paths must be prefixed by the name of the
- * extraction target (i.e. if it's interpreted as a directory). */
- unsigned requires_target_in_paths : 1;
-
- /* OPTIONAL: Like above, but operations require real (absolute) path.
- * */
- unsigned requires_realtarget_in_paths : 1;
-
- /* OPTIONAL: Set to 1 if realpath() can be used to get the real
- * (absolute) path of a file on the target volume before it's been
- * created. */
- unsigned realpath_works_on_nonexisting_files : 1;
-
- /* OPTIONAL: Set to 1 if this extraction mode supports case sensitive
- * filenames. */
- unsigned supports_case_sensitive_filenames : 1;
-
- /* OPTIONAL: Set to 1 if the root directory of the volume (see
- * target_is_root() callback) should not be explicitly extracted. */
- unsigned root_directory_is_special : 1;
-
- /* OPTIONAL: Set to 1 if extraction cookie, or inode number, is stored
- * in create_file() and create_directory() callbacks. This cookie will
- * then be passed to callbacks taking a 'file_spec_t', rather than the
- * path. */
- unsigned uses_cookies : 1;
-
- /* OPTIONAL: Set to 1 if set_file_attributes() needs to be called a
- * second time towards the end of the extraction. */
- unsigned requires_final_set_attributes_pass : 1;
-
- /* OPTIONAL: Set to 1 if extract_encrypted_stream() must be used to
- * create encrypted files. */
- unsigned extract_encrypted_stream_creates_file : 1;
-
- /* OPTIONAL: Set to 1 if a link to a file with corresponding short name
- * must be created before all links to the same file without
- * corresponding short names. */
- unsigned requires_short_name_reordering : 1;
-};
-
+/* These can be treated as counts (for required_features) or booleans (for
+ * supported_features). */
struct wim_features {
unsigned long archive_files;
unsigned long hidden_files;
unsigned long security_descriptors;
unsigned long short_names;
unsigned long unix_data;
+ unsigned long timestamps;
+ unsigned long case_sensitive_filenames;
};
-/* Context for an apply (extract) operation. */
+struct wim_lookup_table_entry;
+struct read_stream_list_callbacks;
+struct apply_operations;
+struct wim_dentry;
+
struct apply_ctx {
+ /* The WIMStruct from which files are being extracted from the currently
+ * selected image. */
WIMStruct *wim;
- int extract_flags;
+
+ /* The target of the extraction, usually the path to a directory. */
const tchar *target;
+
+ /* Length of @target in tchars. */
size_t target_nchars;
- wimlib_progress_func_t progress_func;
+
+ /* Extraction flags (WIMLIB_EXTRACT_FLAG_*) */
+ int extract_flags;
+
+ /* User-provided progress function, or NULL if not specified. */
+ wimlib_progress_func_t progfunc;
+ void *progctx;
+
+ /* Progress data buffer, with progress.extract initialized. */
union wimlib_progress_info progress;
- const struct apply_operations *ops;
- struct list_head stream_list;
+
+ /* Features required to extract the files (with counts) */
+ struct wim_features required_features;
+
+ /* Features supported by the extraction mode (with booleans) */
struct wim_features supported_features;
- bool root_dentry_is_special;
- u32 supported_attributes_mask;
- struct wim_dentry *target_dentry;
- tchar *realtarget;
- size_t realtarget_nchars;
+ /* The members below should not be used outside of extract.c */
+ const struct apply_operations *apply_ops;
+ u64 next_progress;
unsigned long invalid_sequence;
- unsigned long partial_security_descriptors;
- unsigned long no_security_descriptors;
+ unsigned long num_streams_remaining;
+ struct list_head stream_list;
+ const struct read_stream_list_callbacks *saved_cbs;
+ struct wim_lookup_table_entry *cur_stream;
+ u64 cur_stream_offset;
struct filedes tmpfile_fd;
tchar *tmpfile_name;
- u64 num_streams_remaining;
- uint64_t next_progress;
- intptr_t private[10];
+ unsigned int count_until_file_progress;
+};
+
+/* Maximum number of UNIX file descriptors, NTFS attributes, or Windows file
+ * handles that can be opened simultaneously to extract a single-instance
+ * stream to multiple destinations. */
+#define MAX_OPEN_STREAMS 512
+
+static inline int
+extract_progress(struct apply_ctx *ctx, enum wimlib_progress_msg msg)
+{
+ return call_progress(ctx->progfunc, msg, &ctx->progress, ctx->progctx);
+}
+
+extern int
+do_file_extract_progress(struct apply_ctx *ctx, enum wimlib_progress_msg msg);
+
+static inline int
+maybe_do_file_progress(struct apply_ctx *ctx, enum wimlib_progress_msg msg)
+{
+ if (unlikely(!--ctx->count_until_file_progress))
+ return do_file_extract_progress(ctx, msg);
+ return 0;
+}
+
+/* Call this to reset the counter for report_file_created() and
+ * report_file_metadata_applied(). */
+static inline void
+reset_file_progress(struct apply_ctx *ctx)
+{
+ ctx->count_until_file_progress = 1;
+}
+
+/* Report that a file was created, prior to stream extraction. */
+static inline int
+report_file_created(struct apply_ctx *ctx)
+{
+ return maybe_do_file_progress(ctx, WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE);
+}
+
+/* Report that file metadata was applied, after stream extraction. */
+static inline int
+report_file_metadata_applied(struct apply_ctx *ctx)
+{
+ return maybe_do_file_progress(ctx, WIMLIB_PROGRESS_MSG_EXTRACT_METADATA);
+}
+
+/* Returns any of the aliases of an inode that are being extracted. */
+#define inode_first_extraction_dentry(inode) \
+ list_first_entry(&(inode)->i_extraction_aliases, \
+ struct wim_dentry, d_extraction_alias_node)
+
+extern int
+extract_stream_list(struct apply_ctx *ctx,
+ const struct read_stream_list_callbacks *cbs);
+
+/*
+ * Represents an extraction backend.
+ */
+struct apply_operations {
+
+ /* Name of the extraction backend. */
+ const char *name;
+
+ /*
+ * Query the features supported by the extraction backend.
+ *
+ * @target
+ * The target string that was provided by the user. (Often a
+ * directory, but extraction backends are free to interpret this
+ * differently.)
+ *
+ * @supported_features
+ * A structure, each of whose members represents a feature that may
+ * be supported by the extraction backend. For each feature that
+ * the extraction backend supports, this routine must set the
+ * corresponding member to a nonzero value.
+ *
+ * Return 0 if successful; otherwise a positive wimlib error code.
+ */
+ int (*get_supported_features)(const tchar *target,
+ struct wim_features *supported_features);
+
+ /*
+ * Main extraction routine.
+ *
+ * The extraction backend is provided a list of dentries that have been
+ * prepared for extraction. It is free to extract them in any way that
+ * it chooses. Ideally, it should choose a method that maximizes
+ * performance.
+ *
+ * The target string will be provided in ctx->common.target. This might
+ * be a directory, although extraction backends are free to interpret it
+ * as they wish. TODO: in some cases, the common extraction code also
+ * interprets the target string. This should be completely isolated to
+ * extraction backends.
+ *
+ * The extraction flags will be provided in ctx->common.extract_flags.
+ * Extraction backends should examine them and implement the behaviors
+ * for as many flags as possible. Some flags are already handled by the
+ * common extraction code. TODO: this needs to be better formalized.
+ *
+ * @dentry_list, the list of dentries, will be ordered such that the
+ * ancestor of any dentry always precedes any descendents. Unless
+ * @single_tree_only is set, it's possible that the dentries consist of
+ * multiple disconnected trees.
+ *
+ * 'd_extraction_name' and 'd_extraction_name_nchars' of each dentry
+ * will be set to indicate the actual name with which the dentry should
+ * be extracted. This may or may not be the same as 'file_name'.
+ * TODO: really, the extraction backends should be responsible for
+ * generating 'd_extraction_name'.
+ *
+ * Each dentry will refer to a valid inode in 'd_inode'.
+ * 'd_inode->i_extraction_aliases' will contain a list of just the
+ * dentries of that inode being extracted. This will be a (possibly
+ * nonproper) subset of the 'd_inode->i_dentry' list.
+ *
+ * The streams required to be extracted will already be prepared in
+ * 'apply_ctx'. The extraction backend should call
+ * extract_stream_list() to extract them.
+ *
+ * The will_extract_dentry() utility function, given an arbitrary dentry
+ * in the WIM image (which may not be in the extraction list), can be
+ * used to determine if that dentry is in the extraction list.
+ *
+ * Return 0 if successful; otherwise a positive wimlib error code.
+ */
+ int (*extract)(struct list_head *dentry_list, struct apply_ctx *ctx);
+
+ /*
+ * Query whether the unnamed data stream of the specified file will be
+ * extracted as "externally backed". If so, the extraction backend is
+ * assumed to handle this separately, and the common extraction code
+ * will not register a usage of that stream.
+ *
+ * This routine is optional.
+ *
+ * Return:
+ * < 0 if the file will *not* be externally backed.
+ * = 0 if the file will be externally backed.
+ * > 0 (wimlib error code) if another error occurred.
+ */
+ int (*will_externally_back)(struct wim_dentry *dentry, struct apply_ctx *ctx);
+
+ /*
+ * Size of the backend-specific extraction context. It must contain
+ * 'struct apply_ctx' as its first member.
+ */
+ size_t context_size;
+
+ /*
+ * Set this if the extraction backend only supports extracting dentries
+ * that form a single tree, not multiple trees.
+ */
+ bool single_tree_only;
};
#ifdef __WIN32__
git://wimlib.net / wimlib / blobdiff