4 * Definitions for the Windows Overlay File System Filter (WOF) ioctls, as well
5 * some definitions for associated undocumented data structures. See
6 * http://msdn.microsoft.com/en-us/library/windows/hardware/ff540367(v=vs.85).aspx
7 * for more information about the documented ioctls.
9 * The author dedicates this file to the public domain.
10 * You can do whatever you want with this file.
16 #include "wimlib/compiler.h"
17 #include "wimlib/types.h"
20 * The Windows Overlay FileSystem Filter (WOF, a.k.a. wof.sys) is a filesystem
21 * filter driver, available in Windows 8.1 and later, which allows files to be
22 * "externally backed", meaning that their data is stored in another location,
23 * possibly in compressed form.
25 * WOF implements a plug-in mechanism by which a specific "provider" is
26 * responsible for actually externally backing a given file. The currently
27 * known providers are:
29 * - The WIM provider: allows a file to be externally backed by a
30 * compressed resource in a WIM archive
31 * - The file provider: allows a file to be "externally backed" by a named
32 * data stream stored with the file itself, where that named data stream
33 * has the format of a compressed WIM resource
35 * For both of these providers, externally backed files are effectively
36 * read-only. If you try to write to such a file, Windows automatically
37 * decompresses it and turns it into a regular, non-externally-backed file.
39 * WOF provides various ioctls that control its operation. For example,
40 * FSCTL_SET_EXTERNAL_BACKING sets up a file as externally backed.
42 * WOF external backings are implemented using reparse points. One consequence
43 * of this is that WOF external backings can only be set on files that do not
44 * already have a reparse point set. Another consequence of this is that it is
45 * possible to create a WOF external backing by manually creating the reparse
46 * point, although this requires dealing with undocumented data structures and
47 * it only works when the WOF driver is not currently attached to the volume.
49 * Note that only the unnamed data stream portion of a file can be externally
50 * backed. Other NTFS streams and metadata are not externally backed.
54 /* Current version of the WOF driver/protocol */
55 #define WOF_CURRENT_VERSION 1
57 /* Specifies the WIM backing provider */
58 #define WOF_PROVIDER_WIM 1
60 /* Specifies the "file" backing provider (a.k.a. System Compression) */
61 #define WOF_PROVIDER_FILE 2
63 /* The current version of the WIM backing provider */
64 #define WIM_PROVIDER_CURRENT_VERSION 1
66 /* The current version of the file backing provider */
67 #define FILE_PROVIDER_CURRENT_VERSION 1
69 /* Identifies a backing provider for a specific overlay service version. */
70 struct wof_external_info {
72 /* Version of the overlay service supported by the backing provider.
73 * Set to WOF_CURRENT_VERSION. */
76 /* Identifier for the backing provider. Example value:
77 * WOF_PROVIDER_WIM. */
83 * Format of the WIM provider reparse data. This is the data which follows the
84 * portion of the reparse point common to WOF. (The common portion consists of
85 * a reparse point header where the reparse tag is 0x80000017, then a 'struct
86 * wof_external_info' which specifies the provider.)
88 * Note that Microsoft does not document any of the reparse point formats for
89 * WOF, although they document the structures which must be passed into the
90 * ioctls, which are often similar.
92 struct wim_provider_rpdata {
93 /* Set to 2. Uncertain meaning. */
96 /* 0 when WIM provider active, otherwise
97 * WIM_PROVIDER_EXTERNAL_FLAG_NOT_ACTIVE or
98 * WIM_PROVIDER_EXTERNAL_FLAG_SUSPENDED. */
101 /* Integer ID that identifies the WIM. */
104 /* SHA-1 message digest of the file's unnamed data stream. */
105 u8 unnamed_data_stream_hash[20];
107 /* SHA-1 message digest of the WIM's blob table as stored on disk. */
108 u8 blob_table_hash[20];
110 /* Uncompressed size of the file's unnamed data stream, in bytes. */
111 le64 unnamed_data_stream_size;
113 /* Size of the file's unnamed data stream as stored in the WIM file.
114 * If this is the same as unnamed_data_stream_size, then the stream is
115 * uncompressed. If this is the *not* the same as
116 * unnamed_data_stream_size, then the stream is compressed. */
117 le64 unnamed_data_stream_size_in_wim;
119 /* Byte offset of the file's unnamed data stream in the WIM. */
120 le64 unnamed_data_stream_offset_in_wim;
123 /* WIM-specific information about a WIM data source */
124 struct WimOverlay_dat_entry_1 {
126 /* Identifier for the WIM data source, (normally allocated by
127 * FSCTL_ADD_OVERLAY). Every 'WimOverlay_dat_entry_1' should have a
128 * different value for this. */
131 /* Byte offset, from the beginning of the file, of the corresponding
132 * 'struct WimOverlay_dat_entry_2' for this WIM data source. */
135 /* Size, in bytes, of the corresponding 'struct WimOverlay_dat_entry_2
136 * for this WIM data source, including wim_file_name and its null
140 /* Type of the WIM file: WIM_BOOT_OS_WIM or WIM_BOOT_NOT_OS_WIM. */
143 /* Index of the image in the WIM to use??? (This doesn't really make
144 * sense, since WIM files combine file data "blobs" for all images into
145 * a single table. Set to 1 if unsure...) */
148 /* GUID of the WIM file (copied from the WIM header, offset +0x18). */
153 * Format of file: "\System Volume Information\WimOverlay.dat"
155 * Not documented by Microsoft.
157 * The file consists of a 'struct WimOverlay_dat_header' followed by one or more
158 * 'struct WimOverlay_dat_entry_1', followed by the same number of 'struct
159 * WimOverlay_dat_entry_2'. Note that 'struct WimOverlay_dat_entry_1' is of
160 * fixed length, whereas 'struct WimOverlay_dat_entry_2' is of variable length.
162 struct WimOverlay_dat_header {
163 /* Set to WIMOVERLAY_DAT_MAGIC */
165 #define WIMOVERLAY_DAT_MAGIC 0x66436F57
167 /* Set to 1 (WIM_PROVIDER_CURRENT_VERSION) */
168 le32 wim_provider_version;
170 /* Set to 0x00000028 */
173 /* Set to number of WIMs registered;
174 * also the number of 'struct WimOverlay_dat_entry_1' that follow. */
177 /* Set to number of WIMs registered;
178 * also the number of 'struct WimOverlay_dat_entry_2' that follow. */
184 struct WimOverlay_dat_entry_1 entry_1s[];
187 /* Location information about a WIM data source */
188 struct WimOverlay_dat_entry_2 {
195 /* Size, in bytes, of this 'struct WimOverlay_dat_entry_2', including
196 * wim_file_name and its null terminator. */
209 /* Size of this inner structure, in bytes. */
210 le32 inner_struct_size;
227 /*************************
228 * Partition information
229 ************************/
231 /* Partition identifier */
233 /* (For MBR-formatted disks) */
235 /* Offset, in bytes, of the MBR partition, from
236 * the beginning of the disk. */
237 le64 part_start_offset;
243 /* (For GPT-formatted disks) */
245 /* Unique GUID of the GPT partition */
246 u8 part_unique_guid[16];
253 /***********************
255 **********************/
257 /* 1 for MBR, 0 for GPT */
258 le32 partition_table_type;
259 #define WIMOVERLAY_PARTITION_TYPE_MBR 1
260 #define WIMOVERLAY_PARTITION_TYPE_GPT 0
262 /* Disk identifier */
264 /* (For MBR-formatted disks) */
266 /* 4-byte ID of the MBR disk */
273 /* (For GPT-formatted disks) */
275 /* GUID of the GPT disk */
280 /* Set to 0. (This is the right size for some sort of optional
282 le32 unknown_0x58[4];
284 /**************************
285 * Location in filesystem
286 *************************/
288 /* Null-terminated path to WIM file. Begins with \ but does
289 * *not* include drive letter! */
290 utf16lechar wim_file_name[];
295 wof_check_structs(void)
297 STATIC_ASSERT(sizeof(struct WimOverlay_dat_header) == 24);
298 STATIC_ASSERT(sizeof(struct WimOverlay_dat_entry_1) == 40);
299 STATIC_ASSERT(sizeof(struct WimOverlay_dat_entry_2) == 104);
302 /*****************************************************************************
304 * --- FSCTL_SET_EXTERNAL_BACKING ---
306 * Sets the backing source of a file.
308 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
309 * Access: 0 (FILE_ANY_ACCESS)
311 * Method: 0 (METHOD_BUFFERED)
313 * Input buffer: 'struct wof_external_info' followed by provider-specific data
314 * ('struct wim_provider_external_info' in the case of WIM).
316 * Output buffer: None
318 #define FSCTL_SET_EXTERNAL_BACKING 0x9030C
320 struct wim_provider_external_info {
322 /* Set to WIM_PROVIDER_CURRENT_VERSION. */
325 /* 0 when WIM provider active, otherwise
326 * WIM_PROVIDER_EXTERNAL_FLAG_NOT_ACTIVE or
327 * WIM_PROVIDER_EXTERNAL_FLAG_SUSPENDED. */
330 /* Integer ID that identifies the WIM. Get this with the
331 * FSCTL_ADD_OVERLAY ioctl. */
334 /* SHA-1 message digest of the file's unnamed data stream. */
335 u8 unnamed_data_stream_hash[20];
338 struct file_provider_external_info {
340 /* Set to FILE_PROVIDER_CURRENT_VERSION. */
343 u32 compression_format;
344 #define FILE_PROVIDER_COMPRESSION_FORMAT_XPRESS4K 0
345 #define FILE_PROVIDER_COMPRESSION_FORMAT_LZX 1
346 #define FILE_PROVIDER_COMPRESSION_FORMAT_XPRESS8K 2
347 #define FILE_PROVIDER_COMPRESSION_FORMAT_XPRESS16K 3
350 /*****************************************************************************
352 * --- FSCTL_GET_EXTERNAL_BACKING ---
354 * Get external backing information for the specified file.
356 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
357 * Access: 0 (FILE_ANY_ACCESS)
359 * Method: 0 (METHOD_BUFFERED)
362 * Output buffer: 'struct wof_external_info' followed by provider-specific data
363 * ('struct wim_provider_external_info' in the case of WIM).
365 #define FSCTL_GET_EXTERNAL_BACKING 0x90310
367 /*****************************************************************************
369 * --- FSCTL_DELETE_EXTERNAL_BACKING ---
371 * Copy a file from its backing source to its volume, then disassociate it from
372 * its backing provider.
374 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
375 * Access: 0 (FILE_ANY_ACCESS)
377 * Method: 0 (METHOD_BUFFERED)
380 * Output buffer: None
382 #define FSCTL_DELETE_EXTERNAL_BACKING 0x90314
384 /*****************************************************************************
386 * --- FSCTL_ENUM_EXTERNAL_BACKING ---
388 * Enumerate externally backed files on a volume.
390 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
391 * Access: 0 (FILE_ANY_ACCESS)
393 * Method: 0 (METHOD_BUFFERED)
396 * Output buffer: A 16-byte buffer that receives the 128-bit file ID for the
397 * next externally backed file.
399 * The handle used may be either the volume handle or the handle for any file or
400 * directory on the volume.
402 * When all externally backed files on the volume have been enumerated, the
403 * function fails with ERROR_NO_MORE_FILES.
405 #define FSCTL_ENUM_EXTERNAL_BACKING 0x90318
407 /*****************************************************************************
409 * --- FSCTL_ENUM_OVERLAY ---
411 * Enumerates the volume's overlay sources from the specified provider.
413 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
414 * Access: 0 (FILE_ANY_ACCESS)
416 * Method: 3 (METHOD_NEITHER)
418 * Input buffer: 'struct wof_external_info' to specify the provider for which
419 * to enumerate the overlay sources.
421 * Output buffer: Provider-specific data. For the WIM provider, an array of
422 * 'struct wim_provider_overlay_entry'.
424 * This ioctl must be performed on the volume handle, such as \\.\C:
426 #define FSCTL_ENUM_OVERLAY 0x9031F
428 struct wim_provider_overlay_entry {
429 /* Byte offset of the next entry from the beginning of this structure,
430 * or 0 if there are no more entries. */
431 u32 next_entry_offset;
435 /* Identifier for the WIM file. */
438 /* GUID of the WIM file. */
441 /* Byte offset of the WIM's file name from the beginning of this
443 u32 wim_file_name_offset;
445 /* Type of WIM file: WIM_BOOT_OS_WIM or WIM_BOOT_NOT_OS_WIM. */
448 /* Index of the image in the WIM to use??? (This doesn't really make
449 * sense, since WIM files combine file data "blobs" for all images into
450 * a single table. Set to 1 if unsure...) */
453 /* 0 when WIM provider active, otherwise
454 * WIM_PROVIDER_EXTERNAL_FLAG_NOT_ACTIVE or
455 * WIM_PROVIDER_EXTERNAL_FLAG_SUSPENDED. */
458 /* Full path to the WIM in the NT device namespace, e.g.
459 * "\Device\HardDiskVolume2\test.wim". Seems to be null-terminated,
460 * although you probably shouldn't assume so. */
461 wchar_t wim_file_name[];
465 /*****************************************************************************
467 * --- FSCTL_ADD_OVERLAY ---
469 * Adds a new external backing source to a volume.
471 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
472 * Access: 2 (FILE_WRITE_ACCESS)
474 * Method: 0 (METHOD_BUFFERED)
476 * Input buffer: 'struct wof_external_info' followed by provider-specific data
477 * ('struct wim_provider_add_overlay_input' in the case of WIM).
479 * Output buffer: Buffer large enough to receive any information resulting from
480 * the add operation. For the WIM provider, this must be an 8 byte buffer that
481 * receives the 64-bit WIM file ID.
483 * This ioctl must be performed on the volume handle, such as \\.\C:
485 #define FSCTL_ADD_OVERLAY 0x98330
487 struct wim_provider_add_overlay_input {
489 /* Type of WIM file. */
491 #define WIM_BOOT_OS_WIM 0
492 #define WIM_BOOT_NOT_OS_WIM 1
494 /* Index of the image in the WIM to use??? (This doesn't really make
495 * sense, since WIM files combine file data "blobs" for all images into
496 * a single table. Set to 1 if unsure...) */
499 /* Byte offset of wim_file_name in this buffer, not including the
500 * preceding 'struct wof_external_info' (should be 16). */
501 u32 wim_file_name_offset;
503 /* Number of bytes in wim_file_name. */
504 u32 wim_file_name_length;
506 /* Full path to the WIM, e.g. "\??\C:\test-wimboot.wim".
507 * Does NOT need to be null terminated (MS docs claim otherwise). */
508 wchar_t wim_file_name[];
511 /*****************************************************************************
513 * --- FSCTL_REMOVE_OVERLAY ---
515 * Removes an external backing source from a volume.
517 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
518 * Access: 2 (FILE_WRITE_ACCESS)
520 * Method: 0 (METHOD_BUFFERED)
522 * Input buffer: 'struct wof_external_info' followed by provider-specific data
523 * ('struct wim_provider_remove_overlay_input' in the case of WIM).
525 * Output buffer: None
527 * This ioctl must be performed on the volume handle, such as \\.\C:
529 #define FSCTL_REMOVE_OVERLAY 0x98334
531 struct wim_provider_remove_overlay_input {
532 /* Integer ID that identifies the WIM. */
537 /*****************************************************************************
539 * --- FSCTL_UPDATE_OVERLAY ---
541 * Updates an overlay source for a volume.
543 * DeviceType: 9 (FILE_DEVICE_FILE_SYSTEM)
544 * Access: 2 (FILE_WRITE_ACCESS)
546 * Method: 0 (METHOD_BUFFERED)
548 * Input buffer: 'struct wof_external_info' followed by provider-specific data
549 * ('struct wim_provider_update_overlay_input' in the case of WIM).
551 * Output buffer: None
553 * This ioctl must be performed on the volume handle, such as \\.\C:
555 #define FSCTL_UPDATE_OVERLAY 0x98338
557 struct wim_provider_update_overlay_input {
558 /* Integer ID that identifies the WIM data source. */
561 /* Byte offset of wim_file_name in this buffer, not including the
562 * preceding 'struct wof_external_info' (should be 16). */
563 u32 wim_file_name_offset;
565 /* Number of bytes in wim_file_name. */
566 u32 wim_file_name_length;
568 /* Full path to the WIM, e.g. "\??\C:\test-wimboot.wim".
569 * Does NOT need to be null terminated (MS docs claim otherwise).
570 * This WIM must be renamed from the original WIM, or at least be an
571 * identical copy of it! (Maybe the WIM's GUID field is checked.) */
572 wchar_t wim_file_name[];