Heuristic sorting of streams for solid compression
[wimlib] / include / wimlib / wim.h
1 /*
2  * wim.h - WIMStruct definition and helper functions
3  */
4
5 #ifndef _WIMLIB_WIM_H
6 #define _WIMLIB_WIM_H
7
8 #include "wimlib.h"
9 #include "wimlib/file_io.h"
10 #include "wimlib/header.h"
11 #include "wimlib/list.h"
12
13 struct wim_image_metadata;
14 struct wim_info;
15 struct wim_lookup_table;
16
17 /*
18  * WIMStruct - represents a WIM, or a part of a non-standalone WIM
19  *
20  * Note 1: there are three ways in which a WIMStruct can be created:
21  *
22  *      1. open an on-disk WIM file
23  *      2. start to extract a pipable WIM from a file descriptor
24  *      3. create a new WIMStruct directly
25  *
26  * For (1) and (2), the WIMStruct has a backing file; for (3) it does not.  For
27  * (1), the backing file is a real "on-disk" file from the filesystem, whereas
28  * for (2) the backing file is a file descriptor which may be a pipe.
29  *
30  * Note 2: although this is the top-level data structure in wimlib, there do
31  * exist cases in which a WIMStruct is not standalone:
32  *      - streams have been referenced from another WIMStruct
33  *      - an image has been imported into this WIMStruct from another
34  *        (as this references the metadata rather than copies it)
35  *
36  * Note 3: It is unsafe for multiple threads to operate on the same WIMStruct at
37  * the same time.  This extends to references to other WIMStructs as noted
38  * above.  But besides this, it is safe to operate on *different* WIMStructs in
39  * different threads concurrently.
40  */
41 struct WIMStruct {
42
43         /* Information from the header of the WIM file.
44          *
45          * This is also maintained for a WIMStruct not backed by a file, but the
46          * 'reshdr' fields have no meaning.  */
47         struct wim_header hdr;
48
49         /* Array of image metadata, one for each image in the WIM (array length
50          * hdr.image_count).  Or, this will be NULL if this WIM does not contain
51          * metadata, which implies that this WIMStruct either represents part of
52          * a non-standalone WIM, or represents a standalone WIM that, oddly
53          * enough, actually contains 0 images.  */
54         struct wim_image_metadata **image_metadata;
55
56         /* Information from the XML data of the WIM file.  This information is
57          * also maintained for a WIMStruct not backed by a file.  */
58         struct wim_info *wim_info;
59
60         /* The lookup table for this WIMStruct.  If this WIMStruct has a backing
61          * file, then this table will index the streams contained in that file.
62          * In addition, this table may index streams that were added by updates
63          * or referenced from other WIMStructs.  */
64         struct wim_lookup_table *lookup_table;
65
66         /*
67          * The 1-based index of the currently selected image in this WIMStruct,
68          * or WIMLIB_NO_IMAGE if no image is currently selected.
69          *
70          * The metadata for the current image is image_metadata[current_image -
71          * 1].  Since we load image metadata lazily, only the metadata for the
72          * current image is guaranteed to actually be present in memory.
73          */
74         int current_image;
75
76         /* The absolute path to the on-disk file backing this WIMStruct, or NULL
77          * if this WIMStruct is not backed by an on-disk file.  */
78         tchar *filename;
79
80         /* If this WIMStruct has a backing file, then this is a file descriptor
81          * open to that file with read access.  Otherwise, this field is invalid
82          * (!filedes_valid(&in_fd)).  */
83         struct filedes in_fd;
84
85         /* If the library is currently writing this WIMStruct out to a file,
86          * then this is a file descriptor open to that file with write access.
87          * Otherwise, this field is invalid (!filedes_valid(&out_fd)).  */
88         struct filedes out_fd;
89
90         /*
91          * This is the cached decompressor for this WIM file, or NULL if no
92          * decompressor is cached yet.  Normally, all the compressed data in a
93          * WIM file has the same compression type and chunk size, so the same
94          * decompressor can be used for all data --- and that decompressor will
95          * be cached here.  However, if we do encounter any data with a
96          * different compression type or chunk size (this is possible in solid
97          * blocks), then this cached decompressor will be replaced with a new
98          * one.
99          */
100         struct wimlib_decompressor *decompressor;
101         u8 decompressor_ctype;
102         u32 decompressor_max_block_size;
103
104         /*
105          * 'subwims' is the list of dependent WIMStructs (linked by
106          * 'subwim_node') that have been opened by calls to
107          * wimlib_reference_resource_files().  These WIMStructs must be retained
108          * so that resources from them can be used.  They are internal to the
109          * library and are not visible to API users.
110          */
111         struct list_head subwims;
112         struct list_head subwim_node;
113
114         /* Temporary field; use sparingly  */
115         void *private;
116
117         /* 1 if any images have been deleted from this WIMStruct, otherwise 0 */
118         u8 image_deletion_occurred : 1;
119
120         /* 1 if the WIM file has been locked for appending, otherwise 0  */
121         u8 locked_for_append : 1;
122
123         /* If this WIM is backed by a file, then this is the compression type
124          * for non-solid resources in that file.  */
125         u8 compression_type;
126
127         /* Overridden compression type for wimlib_overwrite() or wimlib_write().
128          * Can be changed by wimlib_set_output_compression_type(); otherwise is
129          * the same as compression_type.  */
130         u8 out_compression_type;
131
132         /* Compression type for writing solid resources; can be set with
133          * wimlib_set_output_pack_compression_type().  */
134         u8 out_solid_compression_type;
135
136         /* If this WIM is backed by a file, then this is the compression chunk
137          * size for non-solid resources in that file.  */
138         u32 chunk_size;
139
140         /* Overridden chunk size for wimlib_overwrite() or wimlib_write().  Can
141          * be changed by wimlib_set_output_chunk_size(); otherwise is the same
142          * as chunk_size.  */
143         u32 out_chunk_size;
144
145         /* Chunk size for writing solid resources; can be set with
146          * wimlib_set_output_pack_chunk_size().  */
147         u32 out_solid_chunk_size;
148
149         /* Currently registered progress function for this WIMStruct, or NULL if
150          * no progress function is currently registered for this WIMStruct.  */
151         wimlib_progress_func_t progfunc;
152         void *progctx;
153 };
154
155 /*
156  * Return true if and only if the WIM contains image metadata (actual directory
157  * trees, not just a collection of streams and their checksums).
158  *
159  * See the description of the 'image_metadata' field.  Note that we return true
160  * when the image count is 0 because it could be a WIM with 0 images.  It's only
161  * when the WIM does not contain the metadata described by its image count that
162  * we return false.
163  */
164 static inline bool wim_has_metadata(const WIMStruct *wim)
165 {
166         return (wim->image_metadata != NULL || wim->hdr.image_count == 0);
167 }
168
169 /* Return true if and only if the WIM has an integrity table.
170  *
171  * If the WIM is not backed by a file, then this always returns false.  */
172 static inline bool wim_has_integrity_table(const WIMStruct *wim)
173 {
174         return (wim->hdr.integrity_table_reshdr.offset_in_wim != 0);
175 }
176
177 /* Return true if and only if the WIM is in pipable format.
178  *
179  * If the WIM is not backed by a file, then this always returns false.  */
180 static inline bool wim_is_pipable(const WIMStruct *wim)
181 {
182         return (wim->hdr.magic == PWM_MAGIC);
183 }
184
185 extern int
186 set_wim_hdr_cflags(int ctype, struct wim_header *hdr);
187
188 extern int
189 init_wim_header(struct wim_header *hdr, int ctype, u32 chunk_size);
190
191 extern int
192 read_wim_header(WIMStruct *wim, struct wim_header *hdr);
193
194 extern int
195 write_wim_header(const struct wim_header *hdr, struct filedes *out_fd);
196
197 extern int
198 write_wim_header_at_offset(const struct wim_header *hdr, struct filedes *out_fd,
199                            off_t offset);
200
201 extern int
202 write_wim_header_flags(u32 hdr_flags, struct filedes *out_fd);
203
204 extern int
205 select_wim_image(WIMStruct *wim, int image);
206
207 extern void
208 deselect_current_wim_image(WIMStruct *wim);
209
210 extern int
211 for_image(WIMStruct *wim, int image, int (*visitor)(WIMStruct *));
212
213 extern int
214 wim_checksum_unhashed_streams(WIMStruct *wim);
215
216 extern int
217 delete_wim_image(WIMStruct *wim, int image);
218
219 /* Internal open flags (pass to open_wim_as_WIMStruct(), not wimlib_open_wim())
220  */
221 #define WIMLIB_OPEN_FLAG_FROM_PIPE      0x80000000
222
223 extern int
224 open_wim_as_WIMStruct(const void *wim_filename_or_fd, int open_flags,
225                       WIMStruct **wim_ret,
226                       wimlib_progress_func_t progfunc, void *progctx);
227
228 extern int
229 can_modify_wim(WIMStruct *wim);
230
231 #endif /* _WIMLIB_WIM_H */