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 /* wimlib internal flags used when writing resources. */
174 #define WIMLIB_WRITE_RESOURCE_FLAG_RECOMPRESS 0x00000001
175 #define WIMLIB_WRITE_RESOURCE_FLAG_PIPABLE 0x00000002
176 #define WIMLIB_WRITE_RESOURCE_FLAG_PACK_STREAMS 0x00000004
178 /* Functions to read streams */
181 read_partial_wim_stream_into_buf(const struct wim_lookup_table_entry *lte,
182 size_t size, u64 offset, void *buf);
185 read_full_stream_into_buf(const struct wim_lookup_table_entry *lte, void *buf);
188 read_full_stream_into_alloc_buf(const struct wim_lookup_table_entry *lte,
192 wim_reshdr_to_data(const struct wim_reshdr *reshdr,
193 WIMStruct *wim, void **buf_ret);
196 skip_wim_stream(struct wim_lookup_table_entry *lte);
199 * Type of callback function for beginning to read a stream.
202 * Stream that is about to be read.
205 * Set to true if the stream is just one of several being read from a
206 * single pack and therefore would be extra expensive to read
210 * User-provided context.
212 * Must return 0 on success, a positive error code on failure, or the special
213 * value BEGIN_STREAM_STATUS_SKIP_STREAM to indicate that the stream should not
214 * be read, and read_stream_list() should continue on to the next stream
215 * (without calling @consume_chunk or @end_stream).
217 typedef int (*read_stream_list_begin_stream_t)(struct wim_lookup_table_entry *lte,
221 #define BEGIN_STREAM_STATUS_SKIP_STREAM -1
224 * Type of callback function for finishing reading a stream.
227 * Stream that has been fully read, or stream that started being read but
228 * could not be fully read due to a read error.
231 * 0 if reading the stream was successful; otherwise a nonzero error code
232 * that specifies the return status.
235 * User-provided context.
237 typedef int (*read_stream_list_end_stream_t)(struct wim_lookup_table_entry *lte,
242 /* Callback functions and contexts for read_stream_list(). */
243 struct read_stream_list_callbacks {
245 /* Called when a stream is about to be read. */
246 read_stream_list_begin_stream_t begin_stream;
248 /* Called when a chunk of data has been read. */
249 consume_data_callback_t consume_chunk;
251 /* Called when a stream has been fully read. A successful call to
252 * @begin_stream will always be matched by a call to @end_stream. */
253 read_stream_list_end_stream_t end_stream;
255 /* Parameter passed to @begin_stream. */
256 void *begin_stream_ctx;
258 /* Parameter passed to @consume_chunk. */
259 void *consume_chunk_ctx;
261 /* Parameter passed to @end_stream. */
262 void *end_stream_ctx;
265 /* Flags for read_stream_list() */
266 #define VERIFY_STREAM_HASHES 0x1
267 #define COMPUTE_MISSING_STREAM_HASHES 0x2
268 #define STREAM_LIST_ALREADY_SORTED 0x4
271 read_stream_list(struct list_head *stream_list,
272 size_t list_head_offset,
273 const struct read_stream_list_callbacks *cbs,
276 /* Functions to extract streams. */
279 extract_stream(struct wim_lookup_table_entry *lte,
281 consume_data_callback_t extract_chunk,
282 void *extract_chunk_arg);
285 extract_stream_to_fd(struct wim_lookup_table_entry *lte,
286 struct filedes *fd, u64 size);
289 extract_chunk_to_fd(const void *chunk, size_t size, void *_fd_p);
291 /* Miscellaneous stream functions. */
294 sha1_stream(struct wim_lookup_table_entry *lte);
296 /* Functions to read/write metadata resources. */
299 read_metadata_resource(WIMStruct *wim,
300 struct wim_image_metadata *image_metadata);
303 write_metadata_resource(WIMStruct *wim, int image, int write_resource_flags);
305 /* Definitions specific to pipable WIM resources. */
307 /* Arbitrary number to begin each stream in the pipable WIM, used for sanity
309 #define PWM_STREAM_MAGIC 0x2b9b9ba2443db9d8ULL
311 /* Header that precedes each resource in a pipable WIM. */
312 struct pwm_stream_hdr {
314 le64 uncompressed_size; /* +8 */
315 u8 hash[SHA1_HASH_SIZE]; /* +16 */
316 le32 flags; /* +36 */
320 /* Extra flag for the @flags field in `struct pipable_wim_stream_hdr': Indicates
321 * that the SHA1 message digest of the stream has not been calculated.
322 * Currently only used for the XML data. */
323 #define PWM_RESHDR_FLAG_UNHASHED 0x100
325 /* Header that precedes each chunk of a compressed resource in a pipable WIM.
327 struct pwm_chunk_hdr {
328 le32 compressed_size;
331 #endif /* _WIMLIB_RESOURCE_H */