1 #ifndef _WIMLIB_RESOURCE_H
2 #define _WIMLIB_RESOURCE_H
4 #include "wimlib/callback.h"
5 #include "wimlib/file_io.h"
6 #include "wimlib/list.h"
7 #include "wimlib/sha1.h"
8 #include "wimlib/types.h"
10 struct wim_lookup_table_entry;
11 struct wim_image_metadata;
13 /* Specification of a resource in a WIM file.
15 * If a `struct wim_lookup_table_entry' lte has
16 * (lte->resource_location == RESOURCE_IN_WIM), then lte->wim_res_spec points to
17 * an instance of this structure.
19 * Normally, there is a one-to-one correspondence between WIM lookup table
20 * entries ("streams", each of which may be the contents of a file, for example)
21 * and WIM resources. However, WIM resources with the
22 * WIM_RESHDR_FLAG_PACKED_STREAMS flag set may actually contain multiple streams
23 * compressed together. */
24 struct wim_resource_spec {
25 /* The WIM containing this resource. @wim->in_fd is expected to be a
26 * file descriptor to the underlying WIM file, opened for reading. */
29 /* The offset, in bytes, from the start of WIM file at which this
33 /* The size of this resource in the WIM file. For compressed resources
34 * this is the compressed size, including overhead such as the chunk
38 /* The number of bytes of uncompressed data this resource decompresses
40 u64 uncompressed_size;
42 /* The list of streams this resource contains. */
43 struct list_head stream_list;
45 /* Flags for this resource (WIM_RESHDR_FLAG_*). */
48 /* [wimlib extension] This flag will be set if the WIM is pipable. In
49 * such cases, the resource will be in a slightly different format if it
57 /* On-disk version of a WIM resource header. */
58 struct wim_reshdr_disk {
59 /* Size of the resource as it appears in the WIM file (possibly
63 /* Zero or more of the WIM_RESHDR_FLAG_* flags. These indicate, for
64 * example, whether the resource is compressed or not. */
67 /* Offset of the resource from the start of the WIM file, in bytes. */
70 /* Uncompressed size of the resource, in bytes. */
71 le64 uncompressed_size;
74 /* In-memory version of a WIM resource header (`struct wim_reshdr_disk'). */
79 u64 uncompressed_size;
82 /* Flags for the `flags' field of WIM resource headers (`struct wim_reshdr').
85 /* Unknown meaning; may be intended to indicate spaces in the WIM that are free
86 * to overwrite. Currently ignored by wimlib. */
87 #define WIM_RESHDR_FLAG_FREE 0x01
89 /* The resource is a metadata resource for a WIM image, or is the lookup table
90 * or XML data for the WIM. */
91 #define WIM_RESHDR_FLAG_METADATA 0x02
93 /* The resource is compressed using the WIM's default compression type and uses
94 * the regular chunk table format. */
95 #define WIM_RESHDR_FLAG_COMPRESSED 0x04
97 /* Unknown meaning; may be intended to indicate a partial stream. Currently
98 * ignored by wimlib. */
99 #define WIM_RESHDR_FLAG_SPANNED 0x08
101 /* The resource is packed in a special format that may contain multiple
102 * underlying streams, or this resource entry represents a stream packed into
103 * one such resource. When resources have this flag set, the WIM version number
104 * should be WIM_VERSION_PACKED_STREAMS. */
105 #define WIM_RESHDR_FLAG_PACKED_STREAMS 0x10
107 /* Magic number in the 'uncompressed_size' field of the resource header that
108 * identifies the main entry for a pack. */
109 #define WIM_PACK_MAGIC_NUMBER 0x100000000ULL
111 /* Returns true if the specified WIM resource is compressed, using either the
112 * original chunk table layout or the alternate layout for resources that may
113 * contain multiple packed streams. */
115 resource_is_compressed(const struct wim_resource_spec *rspec)
117 return (rspec->flags & (WIM_RESHDR_FLAG_COMPRESSED |
118 WIM_RESHDR_FLAG_PACKED_STREAMS));
122 copy_reshdr(struct wim_reshdr *dest, const struct wim_reshdr *src)
124 memcpy(dest, src, sizeof(struct wim_reshdr));
128 zero_reshdr(struct wim_reshdr *reshdr)
130 memset(reshdr, 0, sizeof(struct wim_reshdr));
134 wim_res_hdr_to_spec(const struct wim_reshdr *reshdr, WIMStruct *wim,
135 struct wim_resource_spec *rspec);
138 wim_res_spec_to_hdr(const struct wim_resource_spec *rspec,
139 struct wim_reshdr *reshdr);
142 get_wim_reshdr(const struct wim_reshdr_disk *disk_reshdr,
143 struct wim_reshdr *reshdr);
146 put_wim_reshdr(const struct wim_reshdr *reshdr,
147 struct wim_reshdr_disk *disk_reshdr);
149 /* Alternate chunk table format for resources with
150 * WIM_RESHDR_FLAG_PACKED_STREAMS set. */
151 struct alt_chunk_table_header_disk {
152 /* Uncompressed size of the resource in bytes. */
155 /* Number of bytes each compressed chunk decompresses into, except
156 * possibly the last which decompresses into the remainder. This
157 * overrides the chunk size specified by the WIM header. */
160 /* Compression format used for compressed chunks:
166 * This overrides the compression type specified by the WIM header. */
167 le32 compression_format;
169 /* This header is directly followed by a table of compressed sizes of
170 * the chunks (4 bytes per entry). */
173 /* Functions to read streams */
176 read_partial_wim_stream_into_buf(const struct wim_lookup_table_entry *lte,
177 size_t size, u64 offset, void *buf);
180 read_full_stream_into_buf(const struct wim_lookup_table_entry *lte, void *buf);
183 read_full_stream_into_alloc_buf(const struct wim_lookup_table_entry *lte,
187 wim_reshdr_to_data(const struct wim_reshdr *reshdr,
188 WIMStruct *wim, void **buf_ret);
191 skip_wim_stream(struct wim_lookup_table_entry *lte);
194 * Type of callback function for beginning to read a stream.
197 * Stream that is about to be read.
200 * Set to true if the stream is just one of several being read from a
201 * single pack and therefore would be extra expensive to read
205 * User-provided context.
207 * Must return 0 on success, a positive error code on failure, or the special
208 * value BEGIN_STREAM_STATUS_SKIP_STREAM to indicate that the stream should not
209 * be read, and read_stream_list() should continue on to the next stream
210 * (without calling @consume_chunk or @end_stream).
212 typedef int (*read_stream_list_begin_stream_t)(struct wim_lookup_table_entry *lte,
216 #define BEGIN_STREAM_STATUS_SKIP_STREAM -1
219 * Type of callback function for finishing reading a stream.
222 * Stream that has been fully read, or stream that started being read but
223 * could not be fully read due to a read error.
226 * 0 if reading the stream was successful; otherwise a nonzero error code
227 * that specifies the return status.
230 * User-provided context.
232 typedef int (*read_stream_list_end_stream_t)(struct wim_lookup_table_entry *lte,
237 /* Callback functions and contexts for read_stream_list(). */
238 struct read_stream_list_callbacks {
240 /* Called when a stream is about to be read. */
241 read_stream_list_begin_stream_t begin_stream;
243 /* Called when a chunk of data has been read. */
244 consume_data_callback_t consume_chunk;
246 /* Called when a stream has been fully read. A successful call to
247 * @begin_stream will always be matched by a call to @end_stream. */
248 read_stream_list_end_stream_t end_stream;
250 /* Parameter passed to @begin_stream. */
251 void *begin_stream_ctx;
253 /* Parameter passed to @consume_chunk. */
254 void *consume_chunk_ctx;
256 /* Parameter passed to @end_stream. */
257 void *end_stream_ctx;
260 /* Flags for read_stream_list() */
261 #define VERIFY_STREAM_HASHES 0x1
262 #define COMPUTE_MISSING_STREAM_HASHES 0x2
263 #define STREAM_LIST_ALREADY_SORTED 0x4
266 read_stream_list(struct list_head *stream_list,
267 size_t list_head_offset,
268 const struct read_stream_list_callbacks *cbs,
271 /* Functions to extract streams. */
274 extract_stream(struct wim_lookup_table_entry *lte,
276 consume_data_callback_t extract_chunk,
277 void *extract_chunk_arg);
280 extract_stream_to_fd(struct wim_lookup_table_entry *lte,
281 struct filedes *fd, u64 size);
284 extract_full_stream_to_fd(struct wim_lookup_table_entry *lte,
288 extract_chunk_to_fd(const void *chunk, size_t size, void *_fd_p);
290 /* Miscellaneous stream functions. */
293 sha1_stream(struct wim_lookup_table_entry *lte);
295 /* Functions to read/write metadata resources. */
298 read_metadata_resource(WIMStruct *wim,
299 struct wim_image_metadata *image_metadata);
302 write_metadata_resource(WIMStruct *wim, int image, int write_resource_flags);
304 /* Definitions specific to pipable WIM resources. */
306 /* Arbitrary number to begin each stream in the pipable WIM, used for sanity
308 #define PWM_STREAM_MAGIC 0x2b9b9ba2443db9d8ULL
310 /* Header that precedes each resource in a pipable WIM. */
311 struct pwm_stream_hdr {
313 le64 uncompressed_size; /* +8 */
314 u8 hash[SHA1_HASH_SIZE]; /* +16 */
315 le32 flags; /* +36 */
319 /* Extra flag for the @flags field in `struct pipable_wim_stream_hdr': Indicates
320 * that the SHA1 message digest of the stream has not been calculated.
321 * Currently only used for the XML data. */
322 #define PWM_RESHDR_FLAG_UNHASHED 0x100
324 /* Header that precedes each chunk of a compressed resource in a pipable WIM.
326 struct pwm_chunk_hdr {
327 le32 compressed_size;
330 #endif /* _WIMLIB_RESOURCE_H */