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 * Set to true if the stream is just one of several being read from a
221 * single pack and therefore would be extra expensive to read
225 * User-provided context.
227 * Must return 0 on success, a positive error code on failure, or the special
228 * value BEGIN_STREAM_STATUS_SKIP_STREAM to indicate that the stream should not
229 * be read, and read_stream_list() should continue on to the next stream
230 * (without calling @consume_chunk or @end_stream).
232 typedef int (*read_stream_list_begin_stream_t)(struct wim_lookup_table_entry *lte,
236 #define BEGIN_STREAM_STATUS_SKIP_STREAM -1
239 * Type of callback function for finishing reading a stream.
242 * Stream that has been fully read, or stream that started being read but
243 * could not be fully read due to a read error.
246 * 0 if reading the stream was successful; otherwise a nonzero error code
247 * that specifies the return status.
250 * User-provided context.
252 typedef int (*read_stream_list_end_stream_t)(struct wim_lookup_table_entry *lte,
257 /* Callback functions and contexts for read_stream_list(). */
258 struct read_stream_list_callbacks {
260 /* Called when a stream is about to be read. */
261 read_stream_list_begin_stream_t begin_stream;
263 /* Called when a chunk of data has been read. */
264 consume_data_callback_t consume_chunk;
266 /* Called when a stream has been fully read. A successful call to
267 * @begin_stream will always be matched by a call to @end_stream. */
268 read_stream_list_end_stream_t end_stream;
270 /* Parameter passed to @begin_stream. */
271 void *begin_stream_ctx;
273 /* Parameter passed to @consume_chunk. */
274 void *consume_chunk_ctx;
276 /* Parameter passed to @end_stream. */
277 void *end_stream_ctx;
280 /* Flags for read_stream_list() */
281 #define VERIFY_STREAM_HASHES 0x1
282 #define COMPUTE_MISSING_STREAM_HASHES 0x2
283 #define STREAM_LIST_ALREADY_SORTED 0x4
286 read_stream_list(struct list_head *stream_list,
287 size_t list_head_offset,
288 const struct read_stream_list_callbacks *cbs,
291 /* Functions to extract streams. */
294 extract_stream(struct wim_lookup_table_entry *lte,
296 consume_data_callback_t extract_chunk,
297 void *extract_chunk_arg);
300 extract_stream_to_fd(struct wim_lookup_table_entry *lte,
301 struct filedes *fd, u64 size);
304 extract_full_stream_to_fd(struct wim_lookup_table_entry *lte,
308 extract_chunk_to_fd(const void *chunk, size_t size, void *_fd_p);
310 /* Miscellaneous stream functions. */
313 sha1_stream(struct wim_lookup_table_entry *lte);
315 /* Functions to read/write metadata resources. */
318 read_metadata_resource(WIMStruct *wim,
319 struct wim_image_metadata *image_metadata);
322 write_metadata_resource(WIMStruct *wim, int image, int write_resource_flags);
324 /* Definitions specific to pipable WIM resources. */
326 /* Arbitrary number to begin each stream in the pipable WIM, used for sanity
328 #define PWM_STREAM_MAGIC 0x2b9b9ba2443db9d8ULL
330 /* Header that precedes each resource in a pipable WIM. */
331 struct pwm_stream_hdr {
333 le64 uncompressed_size; /* +8 */
334 u8 hash[SHA1_HASH_SIZE]; /* +16 */
335 le32 flags; /* +36 */
339 /* Extra flag for the @flags field in `struct pipable_wim_stream_hdr': Indicates
340 * that the SHA1 message digest of the stream has not been calculated.
341 * Currently only used for the XML data. */
342 #define PWM_RESHDR_FLAG_UNHASHED 0x100
344 /* Header that precedes each chunk of a compressed resource in a pipable WIM.
346 struct pwm_chunk_hdr {
347 le32 compressed_size;
350 #endif /* _WIMLIB_RESOURCE_H */