From e4c9b3f295719e89c571be818ea1657836007b52 Mon Sep 17 00:00:00 2001 From: Natalia Portillo Date: Thu, 9 Oct 2025 15:31:34 +0100 Subject: [PATCH] Update ImageInfo documentation. --- include/aaru.h | 125 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 93 insertions(+), 32 deletions(-) diff --git a/include/aaru.h b/include/aaru.h index 7dc7b0d..2ff2e0c 100644 --- a/include/aaru.h +++ b/include/aaru.h @@ -780,45 +780,106 @@ typedef enum /** \struct ImageInfo * \ingroup MediaTypes - * \brief High-level summary of an opened Aaru image. + * \brief High-level summary of an opened Aaru image containing metadata and media characteristics. * - * Field semantics: - * - HasPartitions: Non-zero if partition (or track, for optical) metadata structures were discovered. - * - HasSessions: Non-zero if multiple sessions (optical) are described. - * - ImageSize: Total number of addressable user-data bytes (excluding container / format headers). - * - Sectors / SectorSize: Logical block count and size. Note: (Sectors * SectorSize) may be <= ImageSize when - * variable-sized tracks exist or gap/padding bytes are preserved separately. - * - *_Time: Signed UNIX epoch seconds; negative denotes unknown / unset. - * - MediaType: Numeric value from \ref MediaType (cast-safe). 0 (Unknown) when detection failed or media is exotic. - * - XmlMediaType: Legacy compact identifier used in historical XML sidecars; retained for backward compatibility. - * - CHS geometry fields: Provided for legacy tooling; may be zero if not derivable. For variable track layouts the - * minimum SectorsPerTrack is reported (use per-track descriptors for exact geometry when available). + * 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. * - * Pointer members: - * - All uint8_t* strings are UTF-8, NUL-terminated, and owned by the library. They may be NULL if absent. - * - Copy any needed strings before destroying/closing the image context to avoid dangling pointers. + * \par Field Semantics: * - * Initialization contract: - * - A zeroed ImageInfo is a valid input to any population routine. - * - Callers must NOT free individual pointer members—use the designated image/context destroy API instead. + * \b 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. * - * Design note: This struct intentionally contains many fields for completeness / binary compatibility. - * Refactoring into sub-structures would break the public ABI, so a linter warning about field count is suppressed. + * \b 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. + * + * \b 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. + * + * \b 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. + * + * \b 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. + * + * \b 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. + * + * \b 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. + * + * \b 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. + * + * \b 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. + * + * \b 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. + * + * \b MediaType (uint32_t): + * - Numeric identifier from the \ref MediaType enumeration representing the physical/logical media. + * - Value 0 (\ref Unknown) when automatic detection failed or media is unrecognized/exotic. + * - Stable across versions; safe to persist and compare. + * - Usage: Cast to \c MediaType enum for switch/case logic; always include default/Unknown handling. + * + * \b 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. + * + * \par 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 \ref MediaType enum; out-of-range values are possible for future extensions. + * + * \par 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). + * + * \par 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. */ typedef struct ImageInfo // NOLINT { - uint8_t HasPartitions; ///< Image contains partitions (or tracks for optical media) - uint8_t HasSessions; ///< Image contains sessions (optical media only) - uint64_t ImageSize; ///< Size of the image without headers - uint64_t Sectors; ///< Sectors contained in the image - uint32_t SectorSize; ///< Size of sectors contained in the image - char Version[32]; ///< Image version - char Application[64]; ///< Application that created the image - char ApplicationVersion[32]; ///< Version of the application that created the image - int64_t CreationTime; ///< Image creation time - int64_t LastModificationTime; ///< Image last modification time - uint32_t MediaType; ///< Media type represented by the image - uint8_t MetadataMediaType; ///< Type of the media represented by the image to use in XML sidecars + 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 \ref MediaType enum; 0=Unknown) + uint8_t MetadataMediaType; ///< Media type for sidecar generation (internal archival use) } ImageInfo; /** \addtogroup SectorTags Per-sector metadata tag types