mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 11:14:39 +00:00
81 lines
4.5 KiB
Plaintext
81 lines
4.5 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
|
|
{
|
|
/**Header identifier, see AARU_MAGIC */
|
|
uint64_t identifier;
|
|
/**UTF-16LE name of the application that created the image */
|
|
uint8_t application[HEADER_APP_NAME_LEN];
|
|
/**Image format major version. A new major version means a possibly incompatible change of format */
|
|
uint8_t imageMajorVersion;
|
|
/**Image format minor version. A new minor version indicates a compatible change of format */
|
|
uint8_t imageMinorVersion;
|
|
/**Major version of the application that created the image */
|
|
uint8_t applicationMajorVersion;
|
|
/**Minor version of the application that created the image */
|
|
uint8_t applicationMinorVersion;
|
|
/**Type of media contained on image */
|
|
uint32_t mediaType;
|
|
/**Offset to index */
|
|
uint64_t indexOffset;
|
|
/**Windows filetime (100 nanoseconds since 1601/01/01 00:00:00 UTC) of image creation time */
|
|
int64_t creationTime;
|
|
/**Windows filetime (100 nanoseconds since 1601/01/01 00:00:00 UTC) of image last written time */
|
|
int64_t lastWrittenTime;
|
|
/**Unique identifier that allows children images to recognize and find this image */
|
|
uint8_t guid[GUID_SIZE];
|
|
/**Block alignment shift. All blocks in the image are aligned at 2 << blockAlignmentShift bytes */
|
|
uint8_t blockAlignmentShift;
|
|
/**Data shift. All data blocks in the image contain 2 << dataShift items at most */
|
|
uint8_t dataShift;
|
|
/**Table shift. All deduplication tables in the image use this shift to calculate the position of an item */
|
|
uint8_t tableShift;
|
|
/**Features used in this image that if unsupported are still compatible for reading and writing implementations */
|
|
uint64_t featureCompatible;
|
|
/**Features used in this image that if unsupported are still compatible for reading implementations but not for writing */
|
|
uint64_t featureCompatibleRo;
|
|
/**Features used in this image that if unsupported prevent reading or writing the image */
|
|
uint64_t featureIncompatible;
|
|
} 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.
|
|
|=== |