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
56 /* Compression type of this resource. */
57 u32 compression_type : 22;
59 /* Compression chunk size of this resource. Irrelevant if the resource
64 /* On-disk version of a WIM resource header. */
65 struct wim_reshdr_disk {
66 /* Size of the resource as it appears in the WIM file (possibly
70 /* Zero or more of the WIM_RESHDR_FLAG_* flags. These indicate, for
71 * example, whether the resource is compressed or not. */
74 /* Offset of the resource from the start of the WIM file, in bytes. */
77 /* Uncompressed size of the resource, in bytes. */
78 le64 uncompressed_size;
81 /* In-memory version of a WIM resource header (`struct wim_reshdr_disk'). */
86 u64 uncompressed_size;
89 /* Flags for the `flags' field of WIM resource headers (`struct wim_reshdr').
92 /* Unknown meaning; may be intended to indicate spaces in the WIM that are free
93 * to overwrite. Currently ignored by wimlib. */
94 #define WIM_RESHDR_FLAG_FREE 0x01
96 /* The resource is a metadata resource for a WIM image, or is the lookup table
97 * or XML data for the WIM. */
98 #define WIM_RESHDR_FLAG_METADATA 0x02
100 /* The resource is compressed using the WIM's default compression type and uses
101 * the regular chunk table format. */
102 #define WIM_RESHDR_FLAG_COMPRESSED 0x04
104 /* Unknown meaning; may be intended to indicate a partial stream. Currently
105 * ignored by wimlib. */
106 #define WIM_RESHDR_FLAG_SPANNED 0x08
108 /* The resource is packed in a special format that may contain multiple
109 * underlying streams, or this resource entry represents a stream packed into
110 * one such resource. When resources have this flag set, the WIM version number
111 * should be WIM_VERSION_PACKED_STREAMS. */
112 #define WIM_RESHDR_FLAG_PACKED_STREAMS 0x10
114 /* Magic number in the 'uncompressed_size' field of the resource header that
115 * identifies the main entry for a pack. */
116 #define WIM_PACK_MAGIC_NUMBER 0x100000000ULL
118 /* Returns true if the specified WIM resource is compressed, using either the
119 * original chunk table layout or the alternate layout for resources that may
120 * contain multiple packed streams. */
122 resource_is_compressed(const struct wim_resource_spec *rspec)
124 return (rspec->flags & (WIM_RESHDR_FLAG_COMPRESSED |
125 WIM_RESHDR_FLAG_PACKED_STREAMS));
129 copy_reshdr(struct wim_reshdr *dest, const struct wim_reshdr *src)
131 memcpy(dest, src, sizeof(struct wim_reshdr));
135 zero_reshdr(struct wim_reshdr *reshdr)
137 memset(reshdr, 0, sizeof(struct wim_reshdr));
141 wim_res_hdr_to_spec(const struct wim_reshdr *reshdr, WIMStruct *wim,
142 struct wim_resource_spec *rspec);
145 wim_res_spec_to_hdr(const struct wim_resource_spec *rspec,
146 struct wim_reshdr *reshdr);
149 get_wim_reshdr(const struct wim_reshdr_disk *disk_reshdr,
150 struct wim_reshdr *reshdr);
153 put_wim_reshdr(const struct wim_reshdr *reshdr,
154 struct wim_reshdr_disk *disk_reshdr);
156 /* Alternate chunk table format for resources with
157 * WIM_RESHDR_FLAG_PACKED_STREAMS set. */
158 struct alt_chunk_table_header_disk {
159 /* Uncompressed size of the resource in bytes. */
162 /* Number of bytes each compressed chunk decompresses into, except
163 * possibly the last which decompresses into the remainder. This
164 * overrides the chunk size specified by the WIM header. */
167 /* Compression format used for compressed chunks:
173 * This overrides the compression type specified by the WIM header. */
174 le32 compression_format;
176 /* This header is directly followed by a table of compressed sizes of
177 * the chunks (4 bytes per entry). */
180 static inline unsigned int
181 get_chunk_entry_size(u64 res_size, bool is_alt)
183 if (res_size <= UINT32_MAX || is_alt)
189 /* Functions to read streams */
192 read_partial_wim_stream_into_buf(const struct wim_lookup_table_entry *lte,
193 size_t size, u64 offset, void *buf);
196 read_full_stream_into_buf(const struct wim_lookup_table_entry *lte, void *buf);
199 read_full_stream_into_alloc_buf(const struct wim_lookup_table_entry *lte,
203 wim_reshdr_to_data(const struct wim_reshdr *reshdr,
204 WIMStruct *wim, void **buf_ret);
207 wim_reshdr_to_hash(const struct wim_reshdr *reshdr, WIMStruct *wim,
208 u8 hash[SHA1_HASH_SIZE]);
211 skip_wim_stream(struct wim_lookup_table_entry *lte);
214 * Type of callback function for beginning to read a stream.
217 * Stream that is about to be read.
220 * Bitwise OR of BEGIN_STREAM_FLAG_PARTIAL_RESOURCE and/or
221 * BEGIN_STREAM_FLAG_WHOLE_STREAM.
224 * User-provided context.
226 * Must return 0 on success, a positive error code on failure, or the special
227 * value BEGIN_STREAM_STATUS_SKIP_STREAM to indicate that the stream should not
228 * be read, and read_stream_list() should continue on to the next stream
229 * (without calling @consume_chunk or @end_stream).
231 typedef int (*read_stream_list_begin_stream_t)(struct wim_lookup_table_entry *lte,
235 /* Set to true if the stream is just one of several being read from a single
236 * pack and therefore would be extra expensive to read independently. */
237 #define BEGIN_STREAM_FLAG_PARTIAL_RESOURCE 0x00000001
239 /* This is purely advisory and indicates that the entire stream data will be
240 * provided in one call to consume_chunk(). */
241 #define BEGIN_STREAM_FLAG_WHOLE_STREAM 0x00000002
243 #define BEGIN_STREAM_STATUS_SKIP_STREAM -1
246 * Type of callback function for finishing reading a stream.
249 * Stream that has been fully read, or stream that started being read but
250 * could not be fully read due to a read error.
253 * 0 if reading the stream was successful; otherwise a nonzero error code
254 * that specifies the return status.
257 * User-provided context.
259 typedef int (*read_stream_list_end_stream_t)(struct wim_lookup_table_entry *lte,
264 /* Callback functions and contexts for read_stream_list(). */
265 struct read_stream_list_callbacks {
267 /* Called when a stream is about to be read. */
268 read_stream_list_begin_stream_t begin_stream;
270 /* Called when a chunk of data has been read. */
271 consume_data_callback_t consume_chunk;
273 /* Called when a stream has been fully read. A successful call to
274 * @begin_stream will always be matched by a call to @end_stream. */
275 read_stream_list_end_stream_t end_stream;
277 /* Parameter passed to @begin_stream. */
278 void *begin_stream_ctx;
280 /* Parameter passed to @consume_chunk. */
281 void *consume_chunk_ctx;
283 /* Parameter passed to @end_stream. */
284 void *end_stream_ctx;
287 /* Flags for read_stream_list() */
288 #define VERIFY_STREAM_HASHES 0x1
289 #define COMPUTE_MISSING_STREAM_HASHES 0x2
290 #define STREAM_LIST_ALREADY_SORTED 0x4
293 read_stream_list(struct list_head *stream_list,
294 size_t list_head_offset,
295 const struct read_stream_list_callbacks *cbs,
298 /* Functions to extract streams. */
301 extract_stream(struct wim_lookup_table_entry *lte,
303 consume_data_callback_t extract_chunk,
304 void *extract_chunk_arg);
307 extract_stream_to_fd(struct wim_lookup_table_entry *lte,
308 struct filedes *fd, u64 size);
311 extract_full_stream_to_fd(struct wim_lookup_table_entry *lte,
315 extract_chunk_to_fd(const void *chunk, size_t size, void *_fd_p);
317 /* Miscellaneous stream functions. */
320 sha1_stream(struct wim_lookup_table_entry *lte);
322 /* Functions to read/write metadata resources. */
325 read_metadata_resource(WIMStruct *wim,
326 struct wim_image_metadata *image_metadata);
329 write_metadata_resource(WIMStruct *wim, int image, int write_resource_flags);
331 /* Definitions specific to pipable WIM resources. */
333 /* Arbitrary number to begin each stream in the pipable WIM, used for sanity
335 #define PWM_STREAM_MAGIC 0x2b9b9ba2443db9d8ULL
337 /* Header that precedes each resource in a pipable WIM. */
338 struct pwm_stream_hdr {
340 le64 uncompressed_size; /* +8 */
341 u8 hash[SHA1_HASH_SIZE]; /* +16 */
342 le32 flags; /* +36 */
346 /* Extra flag for the @flags field in `struct pipable_wim_stream_hdr': Indicates
347 * that the SHA1 message digest of the stream has not been calculated.
348 * Currently only used for the XML data. */
349 #define PWM_RESHDR_FLAG_UNHASHED 0x100
351 /* Header that precedes each chunk of a compressed resource in a pipable WIM.
353 struct pwm_chunk_hdr {
354 le32 compressed_size;
357 #endif /* _WIMLIB_RESOURCE_H */