wimlib/header.h: Improve comments
authorEric Biggers <ebiggers3@gmail.com>
Tue, 14 Jan 2014 19:59:24 +0000 (13:59 -0600)
committerEric Biggers <ebiggers3@gmail.com>
Tue, 14 Jan 2014 19:59:24 +0000 (13:59 -0600)
include/wimlib/header.h

index 2841b827ca1bfb9eb2620750a8f99ca9ea594afa..34e910cbb15fe1b338ce132bd053f6dadf70eebc 100644 (file)
@@ -8,16 +8,18 @@
 /* Length of "Globally Unique ID" field in WIM header.  */
 #define WIM_GID_LEN    16
 
-/* Length of the WIM header on disk.  */
+/* Length of the WIM header on disk.  wimlib currently requires that the header
+ * be exactly this size.  */
 #define WIM_HEADER_DISK_SIZE 208
 
 /* Default WIM version number.  Streams are always compressed independently.  */
 #define WIM_VERSION_DEFAULT 0x10d00
 
 /* Version number used for WIMs that allow multiple streams packed into one
- * resource (WIM_RESHDR_FLAG_PACKED_STREAMS).  New as of Windows 8 WIMGAPI; used
- * for the Windows 8 web downloader, but yet not yet properly documented by
- * Microsoft.  This WIM format also allows a new compression format (LZMS).  */
+ * resource ("solid blocks", marked by WIM_RESHDR_FLAG_PACKED_STREAMS) and also
+ * a new compression format (LZMS).  This version is new as of Windows 8
+ * WIMGAPI.  Although it is used by Windows 8 web downloader, it is not yet
+ * properly documented by Microsoft.  */
 #define WIM_VERSION_PACKED_STREAMS 0xe00
 
 /* Note: there is another WIM version from Vista pre-releases, but it is not
                 ((u64)'\0' << 48) |            \
                 ((u64)'\0' << 54))
 
-/* On-disk format of the WIM header. */
+/* On-disk format of the WIM header.  */
 struct wim_header_disk {
 
-       /* +0x00: Magic characters "MSWIM\0\0\0".  */
+       /* +0x00: Magic characters WIM_MAGIC or PWM_MAGIC.  */
        le64 magic;
 
        /* +0x08: Size of the WIM header, in bytes; WIM_HEADER_DISK_SIZE
@@ -64,22 +66,25 @@ struct wim_header_disk {
        u32 wim_flags;
 
        /* +0x14: Uncompressed chunk size for compressed resources in the WIM
-        * other than packed resources, or 0 if the WIM is uncompressed.  */
+        * other than packed resources, or 0 if the WIM is uncompressed.
+        * (However wimlib will currently accept any value here if the WIM is
+        * uncompressed.)  */
        u32 chunk_size;
 
        /* +0x18: Globally unique identifier for the WIM file.  Basically a
-        * bunch of random bytes. */
+        * bunch of random bytes.  */
        u8 guid[WIM_GID_LEN];
 
        /* +0x28: Number of this WIM part in the split WIM file, indexed from 1,
-        * or 1 if the WIM is not split. */
+        * or 1 if the WIM is not split.  */
        u16 part_number;
 
        /* +0x2a: Total number of parts of the split WIM file, or 1 if the WIM
-        * is not split. */
+        * is not split.  */
        u16 total_parts;
 
-       /* +0x2c: Number of images in the WIM.  */
+       /* +0x2c: Number of images in the WIM.  WIMGAPI requires that this be at
+        * least 1.  wimlib allows 0.  */
        u32 image_count;
 
        /* +0x30: Location and size of the WIM's lookup table.  */
@@ -129,57 +134,60 @@ struct wim_header {
        struct wim_reshdr integrity_table_reshdr;
 };
 
-/* Flags for the `flags' field of the struct wim_header: */
+/* WIM header flags ('wim_flags' field of 'struct wim_header_disk'):  */
 
-/* Reserved for future use */
+/* Reserved flag.  */
 #define WIM_HDR_FLAG_RESERVED           0x00000001
 
-/* Files and metadata in the WIM are compressed. */
+/* The WIM may contain compressed resources --- specifically, resources with
+ * WIM_RESHDR_FLAG_COMPRESSED set in their headers.  Exactly one of the more
+ * specific WIM_HDR_FLAG_COMPRESSION_* flags must be set to specify the
+ * compression format used.  */
 #define WIM_HDR_FLAG_COMPRESSION        0x00000002
 
-/* WIM is read-only, so modifications should not be allowed even if the WIM is
- * writable at the filesystem level. */
+/* The WIM is read-only, so modifications should not be allowed even if the WIM
+ * is writable at the filesystem level.  */
 #define WIM_HDR_FLAG_READONLY           0x00000004
 
-/* Resource data specified by images in this WIM may be contained in a different
- * WIM.  Or in other words, this WIM is part of a split WIM.  */
+/* The WIM is part of a split WIM.  */
 #define WIM_HDR_FLAG_SPANNED            0x00000008
 
-/* The WIM contains resources only; no filesystem metadata.  wimlib ignores this
- * flag, as it looks for resources in all the WIMs anyway. */
+/* All streams included in the WIM's lookup table are non-metadata (do not have
+ * WIM_RESHDR_FLAG_METADATA set).  wimlib ignores this flag and clears it on new
+ * WIM files it writes.  */
 #define WIM_HDR_FLAG_RESOURCE_ONLY      0x00000010
 
-/* The WIM contains metadata only.  wimlib ignores this flag.  Note that all the
- * metadata resources for a split WIM should be in the first part. */
+/* All streams included in the WIM's lookup table are metadata (have
+ * WIM_RESHDR_FLAG_METADATA set).  wimlib ignores this flag and clears it on
+ * new WIM files it writes.  */
 #define WIM_HDR_FLAG_METADATA_ONLY      0x00000020
 
 /* The WIM is currently being written or appended to.  */
 #define WIM_HDR_FLAG_WRITE_IN_PROGRESS  0x00000040
 
-/* Reparse point fixup flag.  See docs for --rpfix and --norpfix in imagex, or
- * WIMLIB_ADD_FLAG_{RPFIX,NORPFIX} in wimlib.h.  Note that
- * WIM_HDR_FLAG_RP_FIX is a header flag and just sets the default behavior for
- * the WIM; it can still be overridder on a per-image basis.  But there is no
- * flag to set the default behavior for a specific image. */
+/* Reparse point fixup flag.  See docs for the --rpfix and --norpfix options to
+ * 'wimlib-imagex capture', or the WIMLIB_ADD_FLAG_{RPFIX,NORPFIX} flags in
+ * wimlib.h.  Note that WIM_HDR_FLAG_RP_FIX is a header flag and just sets the
+ * default behavior for the WIM; it can still be programatically overridden on a
+ * per-image basis.  But there is no flag in the file format to set the default
+ * behavior for a specific image.  */
 #define WIM_HDR_FLAG_RP_FIX             0x00000080
 
-/* Unused, reserved flag for another compression type */
+/* Unused, reserved flag for another compression type */
 #define WIM_HDR_FLAG_COMPRESS_RESERVED  0x00010000
 
-/* Resources within the WIM are compressed using "XPRESS" compression, which is
- * a LZ77-based compression algorithm.  */
+/* Resources in the WIM with WIM_RESHDR_FLAG_COMPRESSED set in their headers are
+ * compressed with XPRESS compression.  */
 #define WIM_HDR_FLAG_COMPRESS_XPRESS    0x00020000
 
-/* Resources within the WIM are compressed using "LZX" compression.  This is also
- * a LZ77-based algorithm. */
+/* Resources in the WIM with WIM_RESHDR_FLAG_COMPRESSED set in their headers are
+ * compressed with LZX compression.  */
 #define WIM_HDR_FLAG_COMPRESS_LZX       0x00040000
 
-/* Starting in Windows 8, WIMGAPI can create WIMs using LZMS compression, and
- * this flag is set on such WIMs.  However, an additional undocumented flag
- * needs to be provided to WIMCreateFile() to create such WIMs, and the version
- * number in the header of the resulting WIMs is different (3584).  None of this
- * is actually documented, and wimlib does not yet support this compression
- * format.  */
+/* Resources in the WIM with WIM_RESHDR_FLAG_COMPRESSED set in their headers are
+ * compressed with LZMS compression.  Note: this flag is only valid if the WIM
+ * version is WIM_VERSION_PACKED_STREAMS.  Also, this flag is only supported in
+ * wimlib v1.6.0 and later and WIMGAPI Windows 8 and later.  */
 #define WIM_HDR_FLAG_COMPRESS_LZMS      0x00080000
 
 #endif /* _WIMLIB_HEADER_H */