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.

Function Documentation

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 470 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 306 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 246 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().