libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
ImageInfo Struct Reference
Media type classification

High-level summary of an opened Aaru image containing metadata and media characteristics. More...

`#include <aaru.h>`

## Data Fields
uint8_t | HasPartitions
| Image contains partitions (or tracks for optical media); 0=no, non-zero=yes.
uint8_t | HasSessions
| Image contains multiple sessions (optical media); 0=single/none, non-zero=multi.
uint64_t | ImageSize
| Size of the image payload in bytes (excludes headers/metadata)
uint64_t | Sectors
| Total count of addressable logical sectors/blocks.
uint32_t | SectorSize
| Size of each logical sector in bytes (512, 2048, 2352, 4096, etc.)
char | Version [32]
| Image format version string (NUL-terminated, e.g., "6.0")
char | Application [64]
| Name of application that created the image (NUL-terminated)
char | ApplicationVersion [32]
| Version of the creating application (NUL-terminated)
int64_t | CreationTime
| Image creation timestamp (Windows FILETIME: 100ns since 1601-01-01 UTC)
int64_t | LastModificationTime
| Last modification timestamp (Windows FILETIME format)
uint32_t | MediaType
| Media type identifier (see MediaType enum; 0=Unknown)
uint8_t | MetadataMediaType
| Media type for sidecar generation (internal archival use)

## Detailed Description

High-level summary of an opened Aaru image containing metadata and media characteristics.

This structure aggregates essential information extracted from an Aaru format image file, providing callers with a comprehensive view of the imaged media without requiring access to internal image structures. All fields are read-only from the caller's perspective and reflect the state at the time the image was created or last modified.

Field Semantics:

HasPartitions (uint8_t):

- Non-zero (typically 1) if the image contains partition table metadata (MBR, GPT, APM, etc.) or, for optical media, track information structures.
- Zero if no partition/track structures were detected or if the media is unpartitioned.
- Usage: Check this before attempting to enumerate partitions/tracks via dedicated APIs.

HasSessions (uint8_t):

- Non-zero (typically 1) if multiple recording sessions are present (primarily optical media).
- Zero for single-session media or media types that don't support sessions (e.g., floppy, HDD).
- Usage: Multi-session handling may require session-specific TOC/track enumeration.

ImageSize (uint64_t):

- Total size in bytes of image payload data, excluding format headers, metadata, and container overhead.
- May not reflect current file size due to compression, sparse allocation, or incremental updates.
- Usage: For informational/statistical purposes; not reliable for disk space calculations.

Sectors (uint64_t):

- Total count of addressable logical blocks (sectors) in the image.
- Range: [1, 2^64-1] for valid images; 0 indicates corruption or initialization failure.
- Usage: Multiply by SectorSize to determine total addressable capacity.

SectorSize (uint32_t):

- Size of each logical sector in bytes. Common values: 512, 2048, 2352, 4096.
- Guaranteed to be non-zero for valid images; may vary by media type (CD: 2352, HDD: 512/4096).
- Usage: Required for LBA-to-byte offset calculations and buffer allocation.

Version[32] (char array):

- NUL-terminated string identifying the Aaru image format version (e.g., "6.0", "5.3").
- Not necessarily the application version; reflects on-disk format compatibility level.
- Empty string if version information is unavailable or unrecognized.

Application[64] (char array):

- NUL-terminated string naming the application that created the image (e.g., "Aaru", "DiscImageChef").
- May contain vendor/project identifiers; not guaranteed to match executable name.
- Empty string if creator information was not stored or is unavailable.

ApplicationVersion[32] (char array):

- NUL-terminated string specifying the version of the creating application (e.g., "6.0.0-alpha1").
- Semantic versioning format recommended but not enforced.
- Empty string if version metadata is absent.

CreationTime (int64_t):

- Image creation timestamp as Windows FILETIME: 100-nanosecond intervals since January 1, 1601 00:00:00 UTC.
- Zero (0) may represent epoch or absence of creation time; check for < 0 for explicit invalidity.
- Usage: Convert to UNIX timestamp via: (CreationTime / 10000000) - 11644473600.

LastModificationTime (int64_t):

- Last modification timestamp in Windows FILETIME format (same encoding as CreationTime).
- Updated when image data or metadata is altered; not filesystem modification time.
- May equal CreationTime for unmodified images.
- Negative values indicate missing/invalid metadata.

MediaType (uint32_t):

- Numeric identifier from the MediaType enumeration representing the physical/logical media.
- Value 0 (Unknown) when automatic detection failed or media is unrecognized/exotic.
- Stable across versions; safe to persist and compare.
- Usage: Cast to `MediaType` enum for switch/case logic; always include default/Unknown handling.

MetadataMediaType (uint8_t):

- Internal identifier used for sidecar/metadata generation (METS/CICM/ALTO compatibility).
- Not directly useful for most callers; primarily for serialization/archival workflows.

Invariants and Constraints:
  - All pointer-like char arrays are guaranteed NUL-terminated and safe for string functions.
  - Sectors > 0 and SectorSize > 0 for structurally valid images.
  - Timestamps may be 0 or negative; consumers must validate before using.
  - MediaType range corresponds to MediaType enum; out-of-range values are possible for future extensions.

Thread Safety:
  - Struct contents are stable after retrieval; safe for concurrent reads.
  - Do not cache ImageInfo across context operations that may invalidate it (e.g., re-opening).

ABI Stability:
  - Field layout is ABI-stable; new fields append to end in future versions.
  - Reordering or removing fields constitutes a major version break.
  - Linter suppressions acknowledge intentionally large field count for completeness.

Definition at line 869 of file aaru.h.

## Field Documentation

## ◆ Application

char ImageInfo::Application[64]

Name of application that created the image (NUL-terminated)

Definition at line 877 of file aaru.h.

Referenced by aaruf_create(), and aaruf_open().

## ◆ ApplicationVersion

char ImageInfo::ApplicationVersion[32]

Version of the creating application (NUL-terminated)

Definition at line 878 of file aaru.h.

Referenced by aaruf_create(), and aaruf_open().

## ◆ CreationTime

int64_t ImageInfo::CreationTime

Image creation timestamp (Windows FILETIME: 100ns since 1601-01-01 UTC)

Definition at line 879 of file aaru.h.

Referenced by aaruf_create(), and aaruf_open().

## ◆ HasPartitions

uint8_t ImageInfo::HasPartitions

Image contains partitions (or tracks for optical media); 0=no, non-zero=yes.

Definition at line 871 of file aaru.h.

Referenced by aaruf_set_tracks(), and process_tracks_block().

## ◆ HasSessions

uint8_t ImageInfo::HasSessions

Image contains multiple sessions (optical media); 0=single/none, non-zero=multi.

Definition at line 872 of file aaru.h.

Referenced by aaruf_set_tracks(), and process_tracks_block().

## ◆ ImageSize

uint64_t ImageInfo::ImageSize

Size of the image payload in bytes (excludes headers/metadata)

Definition at line 873 of file aaru.h.

Referenced by aaruf_create(), aaruf_open(), process_aaru_metadata_json_block(), process_cicm_block(), process_data_block(), process_ddt_v1(), process_ddt_v2(), process_geometry_block(), process_metadata_block(), process_tape_files_block(), process_tape_partitions_block(), and process_tracks_block().

## ◆ LastModificationTime

int64_t ImageInfo::LastModificationTime

Last modification timestamp (Windows FILETIME format)

Definition at line 880 of file aaru.h.

Referenced by aaruf_create(), and aaruf_open().

## ◆ MediaType

uint32_t ImageInfo::MediaType

Media type identifier (see MediaType enum; 0=Unknown)

Definition at line 881 of file aaru.h.

Referenced by aaruf_create(), aaruf_open(), aaruf_read_sector_long(), aaruf_write_sector(), aaruf_write_sector_long(), and write_sector_subchannel().

## ◆ MetadataMediaType

uint8_t ImageInfo::MetadataMediaType

Media type for sidecar generation (internal archival use)

Definition at line 882 of file aaru.h.

Referenced by aaruf_create(), aaruf_open(), aaruf_read_sector_long(), aaruf_read_sector_tag(), aaruf_read_track_sector(), aaruf_write_sector(), aaruf_write_sector_long(), aaruf_write_sector_tag(), and write_sector_subchannel().

## ◆ Sectors

uint64_t ImageInfo::Sectors

Total count of addressable logical sectors/blocks.

Definition at line 874 of file aaru.h.

Referenced by aaruf_create(), aaruf_open(), aaruf_read_sector(), aaruf_read_sector_long(), aaruf_read_sector_tag(), aaruf_write_sector(), aaruf_write_sector_long(), aaruf_write_sector_tag(), process_ddt_v1(), process_ddt_v2(), write_dvd_long_sector_blocks(), write_dvd_title_key_decrypted_block(), write_mode2_subheaders_block(), write_sector_prefix_ddt(), write_sector_subchannel(), and write_sector_suffix_ddt().

## ◆ SectorSize

uint32_t ImageInfo::SectorSize

Size of each logical sector in bytes (512, 2048, 2352, 4096, etc.)

Definition at line 875 of file aaru.h.

Referenced by aaruf_create(), aaruf_open(), aaruf_read_sector(), and process_data_block().

## ◆ Version

char ImageInfo::Version[32]

Image format version string (NUL-terminated, e.g., "6.0")

Definition at line 876 of file aaru.h.

Referenced by aaruf_create(), and aaruf_open().

The documentation for this struct was generated from the following file:

- include/aaru.h