mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 19:24:40 +00:00
64 lines
4.3 KiB
Plaintext
64 lines
4.3 KiB
Plaintext
== Master Header Structure
|
|
|
|
The AaruHeaderV2 is the fundamental header present at the beginning of every AaruFormat file.
|
|
It defines the image's versioning, metadata, layout offset, feature compatibility, and structural alignment.
|
|
All subsequent parsing and interpretation of the file depends on the contents of this header.
|
|
|
|
=== Structure Definition
|
|
|
|
[source,c]
|
|
#define HEADER_APP_NAME_LEN 64
|
|
#define GUID_SIZE 16
|
|
/**Header, at start of file */
|
|
typedef struct AaruHeaderV2
|
|
{
|
|
uint64_t identifier; ///< File magic (AARU_MAGIC).
|
|
uint8_t application[AARU_HEADER_APP_NAME_LEN]; ///< UTF-8 creator application name (fixed 64 bytes).
|
|
uint8_t imageMajorVersion; ///< Container format major version.
|
|
uint8_t imageMinorVersion; ///< Container format minor version.
|
|
uint8_t applicationMajorVersion; ///< Creator application major version.
|
|
uint8_t applicationMinorVersion; ///< Creator application minor / patch version.
|
|
uint32_t mediaType; ///< Media type enumeration (value from \ref MediaType).
|
|
uint64_t indexOffset; ///< Absolute byte offset to primary index block (MUST be > 0; 0 => corrupt/unreadable).
|
|
int64_t creationTime; ///< Creation FILETIME (100 ns since 1601-01-01 UTC).
|
|
int64_t lastWrittenTime; ///< Last modification FILETIME (100 ns since 1601-01-01 UTC).
|
|
uint8_t guid[GUID_SIZE]; ///< 128-bit image GUID (binary, not text); stable across children.
|
|
uint8_t blockAlignmentShift; ///< log2 block alignment (block size alignment = 2^blockAlignmentShift bytes).
|
|
uint8_t dataShift; ///< log2 sectors/items per block-index increment in DDT entries (2^dataShift).
|
|
uint8_t tableShift; ///< log2 sectors spanned by each primary DDT entry (0 = single-level).
|
|
uint64_t featureCompatible; ///< Feature bits: unimplemented bits are ignorable (still R/W safe).
|
|
uint64_t featureCompatibleRo; ///< Feature bits: unimplemented -> degrade to read-only access.
|
|
uint64_t featureIncompatible; ///< Feature bits: any unimplemented -> abort (cannot open safely).
|
|
} AaruHeaderV2;
|
|
|
|
=== Field Descriptions
|
|
|
|
[cols="2,3,6",options="header"]
|
|
|===
|
|
| Name | Type | Description
|
|
| identifier | uint64_t | Header identifier constant. Must match the predefined `AARU_MAGIC` value to validate the format.
|
|
| application | uint8_t[HEADER_APP_NAME_LEN] | UTF-16LE in version 1, UTF-8 in version 2, encoded name of the application responsible for creating the image.
|
|
|
|
Length is defined by `HEADER_APP_NAME_LEN`.
|
|
| imageMajorVersion | uint8_t | Major version of the AaruFormat structure.
|
|
|
|
A bump indicates potential breaking changes.
|
|
| imageMinorVersion | uint8_t | Minor version of the format, for backward-compatible structural updates.
|
|
| applicationMajorVersion | uint8_t | Major version of the creating application.
|
|
| applicationMinorVersion | uint8_t | Minor version of the application.
|
|
| mediaType | uint32_t | Media type identifier denoting the nature of the captured content (e.g., floppy, optical disc, tape).
|
|
| indexOffset | uint64_t | Absolute file offset to the beginning of the index structure, used to locate blocks throughout the image.
|
|
| creationTime | int64_t | Timestamp (Windows filetime) representing when the image was first created.
|
|
| lastWrittenTime | int64_t | Timestamp (Windows filetime) of the last modification made to the image.
|
|
| guid | uint8_t[GUID_SIZE] | Globally Unique Identifier (GUID) that allows linking of related image derivatives and child snapshots.
|
|
|
|
Length is defined by `GUID_SIZE`.
|
|
| blockAlignmentShift | uint8_t | Determines block alignment boundaries using the formula 2 << blockAlignmentShift.
|
|
| dataShift | uint8_t | Determines the maximum number of data items in a block using the formula 2 << dataShift.
|
|
| tableShift | uint8_t | Shift used to calculate the number of sectors in a deduplication table entry, using the formula 2 << tableShift.
|
|
| featureCompatible | uint64_t | Bitmask of features that, even if not implemented, still allow reading and writing the image.
|
|
|
|
| featureCompatibleRo | uint64_t | Bitmask of features that allow read-only processing of the image if unsupported.
|
|
|
|
| featureIncompatible | uint64_t | Bitmask of features that must be supported to read or write the image at all.
|
|
|=== |