metadata.c File Reference

#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include "aaruformat.h"
#include "log.h"

Go to the source code of this file.

Functions
void	process_metadata_block (aaruformat_context *ctx, const IndexEntry *entry)
	Processes a metadata block from the image stream.
void	process_geometry_block (aaruformat_context *ctx, const IndexEntry *entry)
	Processes a logical geometry block from the image stream.
void	process_cicm_block (aaruformat_context *ctx, const IndexEntry *entry)
	Processes a CICM XML metadata block from the image stream.
void	process_aaru_metadata_json_block (aaruformat_context *ctx, const IndexEntry *entry)
	Processes an Aaru metadata JSON block from the image stream during image opening.
int32_t	aaruf_get_readable_sector_tags (const void *context, uint8_t *buffer, size_t *length)
	Retrieves which sector tags are readable in the AaruFormat image.
int32_t	aaruf_get_readable_media_tags (const void *context, uint8_t *buffer, size_t *length)
	Retrieves which media tags are present in the AaruFormat image.

Function Documentation

aaruf_get_readable_media_tags()

int32_t aaruf_get_readable_media_tags	(	const void *	context,
		uint8_t *	buffer,
		size_t *	length )

Retrieves which media tags are present in the AaruFormat image.

Returns an array of booleans indicating the presence of each MediaTagType in the image. The array is indexed by MediaTagType enum values (0 to MaxMediaTag), where each boolean is true if the corresponding media tag exists in the image's mediaTags hash table.

Parameters

context	Pointer to the aaruformat context (must be a valid, opened image context).
buffer	Pointer to a buffer to store the boolean array. Can be NULL to query required length.
length	Pointer to the buffer length. On input, contains buffer size; on output, contains required size.

Returns

Returns one of the following status codes:

Return values

AARUF_STATUS_OK	(0) Successfully retrieved readable media tags. This is returned when: The context is valid and properly initialized The buffer is large enough to hold all MediaTagType values (0 to MaxMediaTag) The output array has been populated with true/false for each MediaTagType
AARUF_ERROR_NOT_AARUFORMAT	(-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type)
AARUF_ERROR_BUFFER_TOO_SMALL	(-10) The buffer is too small. This occurs when: The buffer parameter is NULL The length parameter is NULL The provided buffer is smaller than required (size = MaxMediaTag + 1 bytes) The length output will contain the required buffer size

Note

Buffer Size: The buffer must be at least (MaxMediaTag + 1) bytes, where each byte represents whether the corresponding MediaTagType is present in the image.

Query Mode: To query the required buffer size, pass buffer == NULL or *length < required. The function will return AARUF_ERROR_BUFFER_TOO_SMALL and set *length to required size.

Warning

The output parameters are only modified on success (AARUF_STATUS_OK). On error, their values remain unchanged.

Definition at line 711 of file metadata.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_NOT_AARUFORMAT, AARUF_STATUS_OK, FATAL, aaruformat_context::magic, MaxMediaTag, aaruformat_context::mediaTags, and TRACE.

aaruf_get_readable_sector_tags()

int32_t aaruf_get_readable_sector_tags	(	const void *	context,
		uint8_t *	buffer,
		size_t *	length )

Retrieves which sector tags are readable in the AaruFormat image.

Returns an array of booleans indicating whether each SectorTagType was successfully read from the image. The array is indexed by SectorTagType enum values (0 to MaxSectorTag), where each boolean is true if the corresponding sector tag data is present and readable in the image. Sector tags contain per-sector metadata such as sync headers, ECC/EDC codes, subchannels, and other sector-level information essential for exact media reconstruction.

Parameters

context	Pointer to the aaruformat context (must be a valid, opened image context).
buffer	Pointer to a buffer to store the boolean array. Can be NULL to query required length.
length	Pointer to the buffer length. On input, contains buffer size; on output, contains required size.

Returns

Returns one of the following status codes:

Return values

AARUF_STATUS_OK	(0) Successfully retrieved readable sector tags. This is returned when: The context is valid and properly initialized The readableSectorTags array is populated in the context The buffer is large enough to hold all SectorTagType values (0 to MaxSectorTag) The output array has been successfully copied from the internal readableSectorTags
AARUF_ERROR_NOT_AARUFORMAT	(-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type) The context was not properly initialized by aaruf_open() or aaruf_create()
AARUF_ERROR_METADATA_NOT_PRESENT	(-30) The sector tags array is not available. This occurs when: The readableSectorTags array is NULL (not initialized in the context) The image was created without sector tag support The image format does not support or require sector tags
AARUF_ERROR_BUFFER_TOO_SMALL	(-10) The buffer is too small. This occurs when: The buffer parameter is NULL The length parameter is NULL The provided buffer is smaller than required (size = (MaxSectorTag + 1) * sizeof(bool)) The length output will contain the required buffer size in bytes

Note

Buffer Size: The buffer must be at least (MaxSectorTag + 1) bytes, where each byte represents whether the corresponding SectorTagType data was successfully read in the image. On most systems, sizeof(bool) == 1, so the required size is (MaxSectorTag + 1) bytes.

Sector Tag Types: Sector tags preserve on-disk structures not part of main user data. Examples include:

• CD sector sync/header information (CdSectorSync, CdSectorHeader)
• CD subheaders and ECC/EDC codes (CdSectorSubHeader, CdSectorEcc, CdSectorEdc)
• DVD sector numbers and IED (DvdSectorNumber)
• Media-specific proprietary tags (AppleProfileTagAaru, PriamDataTowerTagAaru)

Query Mode: To query the required buffer size, pass buffer == NULL or *length < required. The function will return AARUF_ERROR_BUFFER_TOO_SMALL and set *length to required size. This allows allocation of properly sized buffers without prior knowledge of MaxSectorTag.

Data Interpretation: A true value (non-zero) at buffer[i] indicates sector tag type i was readable. A false value (zero) at buffer[i] indicates that sector tag type i is either not present or was not successfully read from the image during opening. The readableSectorTags array is populated during image opening/processing in data blocks.

Image Opening Context: The readableSectorTags array is initialized during aaruf_open() or aaruf_create() and populated as data blocks are processed. It reflects what was actually present and readable in the image file, not what theoretically could be present for the media type.

Warning

The output parameters are only modified on success (AARUF_STATUS_OK). On error, their values remain unchanged. Initialize them before calling if default values are needed on failure.

If readableSectorTags is NULL in the context, AARUF_ERROR_NOT_FOUND is returned. This typically indicates the image format does not support sector-level tags, rather than indicating an error state. Check return value to distinguish.

See also

SectorTagType for enumeration of all available sector tag types

aaruf_read_sector_tag() for reading individual sector tag data

aaruf_write_sector_tag() for writing sector tags during image creation

Definition at line 623 of file metadata.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_METADATA_NOT_PRESENT, AARUF_ERROR_NOT_AARUFORMAT, AARUF_STATUS_OK, FATAL, aaruformat_context::magic, MaxSectorTag, aaruformat_context::readableSectorTags, and TRACE.

process_aaru_metadata_json_block()

void process_aaru_metadata_json_block	(	aaruformat_context *	ctx,
		const IndexEntry *	entry )

Processes an Aaru metadata JSON block from the image stream during image opening.

Reads an Aaru metadata JSON block from the image file and loads its contents into the context for subsequent retrieval. The Aaru metadata JSON format is a structured representation of comprehensive image metadata including media information, imaging session details, hardware configuration, optical disc tracks and sessions, checksums, and preservation metadata. The JSON payload is stored in its original form without parsing or interpretation by this function, allowing higher-level code to process the structured data as needed.

This function is called during the image opening process (aaruf_open) when an index entry indicates the presence of an AaruMetadataJsonBlock. The function is non-critical; if reading fails or memory allocation fails, the error is logged but the image opening continues. This allows images without JSON metadata or with corrupted JSON blocks to still be opened for data access.

Processing sequence:

1. Validate context and image stream
2. Seek to the block offset specified by the index entry
3. Read the AaruMetadataJsonBlockHeader (8 bytes: identifier + length)
4. Validate the block identifier matches AaruMetadataJsonBlock
5. Allocate memory for the JSON payload
6. Read the JSON data from the file stream
7. Store header and data pointer in the context for later retrieval

Memory allocation: The function allocates memory (via malloc) sized to hold the entire JSON payload as specified by ctx->jsonBlockHeader.length. This memory remains allocated for the lifetime of the context and is freed during aaruf_close(). If allocation fails, the function returns gracefully without the JSON metadata, allowing the image to still be opened.

Image size tracking: The function increments ctx->imageInfo.ImageSize by the length of the JSON payload to track the total size of metadata and structural blocks in the image.

Error handling: All errors are non-fatal and handled gracefully:

• Seek failures: logged and function returns early
• Header read failures: header zeroed, function returns
• Identifier mismatches: header zeroed, processing continues but data is not loaded
• Memory allocation failures: header zeroed, function returns
• Data read failures: header zeroed, allocated memory freed, function returns

In all error cases, the ctx->jsonBlockHeader is zeroed (memset to 0) to indicate that no valid JSON metadata is available, and any allocated memory is properly freed.

Parameters

ctx	Pointer to an initialized aaruformatContext being populated during image opening. Must not be NULL. ctx->imageStream must be open and readable. On success, ctx->jsonBlockHeader will contain the block header and ctx->jsonBlock will point to the allocated JSON data.
entry	Pointer to the IndexEntry that specifies the file offset where the AaruMetadataJsonBlock begins. Must not be NULL. entry->offset indicates the position of the block header in the file.

Note

JSON Format and Encoding:

• The JSON payload is stored in UTF-8 encoding
• The payload may or may not be null-terminated
• This function treats the JSON as opaque binary data
• No JSON parsing, interpretation, or validation is performed during loading
• JSON schema validation is the responsibility of code that retrieves the metadata

Aaru Metadata JSON Purpose:

• Provides machine-readable structured metadata about the image
• Includes comprehensive information about media, sessions, tracks, and checksums
• Enables programmatic access to metadata without XML parsing overhead
• Complements CICM XML with a more modern, structured format
• Used by Aaru and compatible tools for metadata exchange

Non-Critical Nature:

• JSON metadata is optional and supplementary to core image data
• Failures reading this block do not prevent image opening
• The image remains fully functional for sector data access without JSON metadata
• Higher-level code should check if ctx->jsonBlock is non-NULL before use

Distinction from CICM XML:

• Both CICM and Aaru JSON blocks can coexist in the same image
• CICM XML follows the Canary Islands Computer Museum schema
• Aaru JSON follows the Aaru-specific metadata schema
• Different tools may prefer one format over the other

Warning

Memory allocated for ctx->jsonBlock persists for the context lifetime and must be freed during context cleanup (aaruf_close).

This function does not validate JSON syntax or schema. Corrupted JSON data will be loaded successfully and errors will only be detected when attempting to parse.

See also

AaruMetadataJsonBlockHeader for the on-disk structure definition.

process_cicm_block() for processing CICM XML metadata blocks.

aaruf_open() for the overall image opening sequence.

Definition at line 475 of file metadata.c.

References AaruMetadataJsonBlock, FATAL, AaruMetadataJsonBlockHeader::identifier, aaruformat_context::image_info, ImageInfo::ImageSize, aaruformat_context::imageStream, aaruformat_context::json_block, aaruformat_context::json_block_header, AaruMetadataJsonBlockHeader::length, IndexEntry::offset, and TRACE.

Referenced by aaruf_open().

process_cicm_block()

void process_cicm_block	(	aaruformat_context *	ctx,
		const IndexEntry *	entry )

Processes a CICM XML metadata block from the image stream.

Reads a CICM XML metadata block from the image and updates the context with its contents.

Parameters

ctx	Pointer to the aaruformat context.
entry	Pointer to the index entry describing the CICM block.

Definition at line 311 of file metadata.c.

References aaruformat_context::cicm_block, aaruformat_context::cicm_block_header, CicmBlock, FATAL, CicmMetadataBlock::identifier, aaruformat_context::image_info, ImageInfo::ImageSize, aaruformat_context::imageStream, CicmMetadataBlock::length, IndexEntry::offset, and TRACE.

Referenced by aaruf_open().

process_geometry_block()

void process_geometry_block	(	aaruformat_context *	ctx,
		const IndexEntry *	entry )

Processes a logical geometry block from the image stream.

Reads a logical geometry block from the image and updates the context with its contents.

Parameters

ctx	Pointer to the aaruformat context.
entry	Pointer to the index entry describing the geometry block.

Definition at line 251 of file metadata.c.

References aaruformat_context::cylinders, GeometryBlockHeader::cylinders, FATAL, aaruformat_context::geometry_block, GeometryBlock, aaruformat_context::heads, GeometryBlockHeader::heads, GeometryBlockHeader::identifier, aaruformat_context::image_info, ImageInfo::ImageSize, aaruformat_context::imageStream, IndexEntry::offset, aaruformat_context::sectors_per_track, GeometryBlockHeader::sectorsPerTrack, and TRACE.

Referenced by aaruf_open().

process_metadata_block()

void process_metadata_block	(	aaruformat_context *	ctx,
		const IndexEntry *	entry )

Processes a metadata block from the image stream.

Reads a metadata block from the image and updates the context with its contents.

Parameters

ctx	Pointer to the aaruformat context.
entry	Pointer to the index entry describing the metadata block.

Definition at line 35 of file metadata.c.

References MetadataBlockHeader::blockSize, IndexEntry::blockType, aaruformat_context::comments, MetadataBlockHeader::commentsLength, MetadataBlockHeader::commentsOffset, aaruformat_context::creator, MetadataBlockHeader::creatorLength, MetadataBlockHeader::creatorOffset, aaruformat_context::drive_firmware_revision, aaruformat_context::drive_manufacturer, aaruformat_context::drive_model, aaruformat_context::drive_serial_number, MetadataBlockHeader::driveFirmwareRevisionLength, MetadataBlockHeader::driveFirmwareRevisionOffset, MetadataBlockHeader::driveManufacturerLength, MetadataBlockHeader::driveManufacturerOffset, MetadataBlockHeader::driveModelLength, MetadataBlockHeader::driveModelOffset, MetadataBlockHeader::driveSerialNumberLength, MetadataBlockHeader::driveSerialNumberOffset, FATAL, MetadataBlockHeader::identifier, aaruformat_context::image_info, ImageInfo::ImageSize, aaruformat_context::imageStream, aaruformat_context::last_media_sequence, MetadataBlockHeader::lastMediaSequence, aaruformat_context::media_barcode, aaruformat_context::media_manufacturer, aaruformat_context::media_model, aaruformat_context::media_part_number, aaruformat_context::media_sequence, aaruformat_context::media_serial_number, aaruformat_context::media_title, MetadataBlockHeader::mediaBarcodeLength, MetadataBlockHeader::mediaBarcodeOffset, MetadataBlockHeader::mediaManufacturerLength, MetadataBlockHeader::mediaManufacturerOffset, MetadataBlockHeader::mediaModelLength, MetadataBlockHeader::mediaModelOffset, MetadataBlockHeader::mediaPartNumberLength, MetadataBlockHeader::mediaPartNumberOffset, MetadataBlockHeader::mediaSequence, MetadataBlockHeader::mediaSerialNumberLength, MetadataBlockHeader::mediaSerialNumberOffset, MetadataBlockHeader::mediaTitleLength, MetadataBlockHeader::mediaTitleOffset, aaruformat_context::metadata_block, aaruformat_context::metadata_block_header, IndexEntry::offset, and TRACE.

Referenced by aaruf_open().