<trclass="memdesc:a43974d4c183240be30d49ff09ef7b8c2"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Processes a metadata block from the image stream. <br/></td></tr>
<trclass="memdesc:a81d410de6727d95a85b827067e1a8bc6"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Processes a logical geometry block from the image stream. <br/></td></tr>
<trclass="memdesc:a5e0397faed8aea27c5a6a3881875de54"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Processes a CICM XML metadata block from the image stream. <br/></td></tr>
<trclass="memdesc:a84003ec881425a7b28ec24cb48d19f02"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Processes an Aaru metadata JSON block from the image stream during image opening. <br/></td></tr>
<trclass="memdesc:aa9ed74c6988c035d9ba0d11965d5cf10"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Retrieves which sector tags are readable in the AaruFormat image. <br/></td></tr>
<trclass="memdesc:a9cfc80d1cfa399bfea980b6ac4e2208a"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Retrieves which media tags are present in the AaruFormat image. <br/></td></tr>
<p>Retrieves which media tags are present in the AaruFormat image. </p>
<p>Returns an array of booleans indicating the presence of each <aclass="el"href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> in the image. The array is indexed by <aclass="el"href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> enum values (0 to MaxMediaTag), where each boolean is true if the corresponding media tag exists in the image's mediaTags hash table.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
<tr><tdclass="paramname">buffer</td><td>Pointer to a buffer to store the boolean array. Can be NULL to query required length. </td></tr>
<tr><tdclass="paramname">length</td><td>Pointer to the buffer length. On input, contains buffer size; on output, contains required size.</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved readable media tags. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The buffer is large enough to hold all <aclass="el"href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> values (0 to MaxMediaTag)</li>
<li>The output array has been populated with true/false for each <aclass="el"href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a></li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The buffer is too small. This occurs when:<ul>
<li>The buffer parameter is NULL</li>
<li>The length parameter is NULL</li>
<li>The provided buffer is smaller than required (size = MaxMediaTag + 1 bytes)</li>
<li>The length output will contain the required buffer size</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>Buffer Size: The buffer must be at least (MaxMediaTag + 1) bytes, where each byte represents whether the corresponding <aclass="el"href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> is present in the image.</dd>
<dd>
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.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The output parameters are only modified on success (AARUF_STATUS_OK). On error, their values remain unchanged. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="blocks_2metadata_8c_source.html#l00706">706</a> of file <aclass="el"href="blocks_2metadata_8c_source.html">metadata.c</a>.</p>
<p>Retrieves which sector tags are readable in the AaruFormat image. </p>
<p>Returns an array of booleans indicating whether each <aclass="el"href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> was successfully read from the image. The array is indexed by <aclass="el"href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> 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.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
<tr><tdclass="paramname">buffer</td><td>Pointer to a buffer to store the boolean array. Can be NULL to query required length. </td></tr>
<tr><tdclass="paramname">length</td><td>Pointer to the buffer length. On input, contains buffer size; on output, contains required size.</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved readable sector tags. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The readableSectorTags array is populated in the context</li>
<li>The buffer is large enough to hold all <aclass="el"href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> values (0 to MaxSectorTag)</li>
<li>The output array has been successfully copied from the internal readableSectorTags</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
<li>The context was not properly initialized by <aclass="el"href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656"title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <aclass="el"href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013"title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) The sector tags array is not available. This occurs when:<ul>
<li>The readableSectorTags array is NULL (not initialized in the context)</li>
<li>The image was created without sector tag support</li>
<li>The image format does not support or require sector tags</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The buffer is too small. This occurs when:<ul>
<li>The buffer parameter is NULL</li>
<li>The length parameter is NULL</li>
<li>The provided buffer is smaller than required (size = (MaxSectorTag + 1) * sizeof(bool))</li>
<li>The length output will contain the required buffer size in bytes</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>Buffer Size: The buffer must be at least (MaxSectorTag + 1) bytes, where each byte represents whether the corresponding <aclass="el"href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> data was successfully read in the image. On most systems, sizeof(bool) == 1, so the required size is (MaxSectorTag + 1) bytes.</dd>
<dd>
Sector Tag Types: Sector tags preserve on-disk structures not part of main user data. Examples include:<ul>
<li>CD sector sync/header information (CdSectorSync, CdSectorHeader)</li>
<li>CD subheaders and ECC/EDC codes (CdSectorSubHeader, CdSectorEcc, CdSectorEdc)</li>
<li>DVD sector numbers and IED (DvdSectorNumber)</li>
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.</dd>
<dd>
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.</dd>
<dd>
Image Opening Context: The readableSectorTags array is initialized during <aclass="el"href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656"title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <aclass="el"href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013"title="Creates a new AaruFormat image file.">aaruf_create()</a> 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.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>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.</dd>
<dd>
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.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> for enumeration of all available sector tag types </dd>
<dd>
<aclass="el"href="decls_8h.html#ae5a85524a6e27339c02c4a5791e0db57"title="Reads a specific sector tag from the AaruFormat image.">aaruf_read_sector_tag()</a> for reading individual sector tag data </dd>
<dd>
<aclass="el"href="decls_8h.html#a6a8994cd006711347fb03cec465eafa6"title="Writes per-sector tag data (auxiliary metadata) for a specific sector.">aaruf_write_sector_tag()</a> for writing sector tags during image creation </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="blocks_2metadata_8c_source.html#l00618">618</a> of file <aclass="el"href="blocks_2metadata_8c_source.html">metadata.c</a>.</p>
<p>Processes an Aaru metadata JSON block from the image stream during image opening. </p>
<p>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.</p>
<p>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.</p>
<p><b>Processing sequence:</b></p><oltype="1">
<li>Validate context and image stream</li>
<li>Seek to the block offset specified by the index entry</li>
<li>Read the <aclass="el"href="structAaruMetadataJsonBlockHeader.html"title="Header for an Aaru metadata JSON block (identifier == BlockType::AaruMetadataJsonBlock).">AaruMetadataJsonBlockHeader</a> (8 bytes: identifier + length)</li>
<li>Validate the block identifier matches AaruMetadataJsonBlock</li>
<li>Allocate memory for the JSON payload</li>
<li>Read the JSON data from the file stream</li>
<li>Store header and data pointer in the context for later retrieval</li>
</ol>
<p><b>Memory allocation:</b> 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 <aclass="el"href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49"title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. If allocation fails, the function returns gracefully without the JSON metadata, allowing the image to still be opened.</p>
<p><b>Image size tracking:</b> 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.</p>
<p><b>Error handling:</b> All errors are non-fatal and handled gracefully:</p><ul>
<li>Seek failures: logged and function returns early</li>
<li>Header read failures: header zeroed, function returns</li>
<li>Identifier mismatches: header zeroed, processing continues but data is not loaded</li>
<li>Memory allocation failures: header zeroed, function returns</li>
<li>Data read failures: header zeroed, allocated memory freed, function returns</li>
</ul>
<p>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.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>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. </td></tr>
<tr><tdclass="paramname">entry</td><td>Pointer to the <aclass="el"href="structIndexEntry.html"title="Single index entry describing a block's type, (optional) data classification, and file offset.">IndexEntry</a> 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.</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>JSON Format and Encoding:<ul>
<li>The JSON payload is stored in UTF-8 encoding</li>
<li>The payload may or may not be null-terminated</li>
<li>This function treats the JSON as opaque binary data</li>
<li>No JSON parsing, interpretation, or validation is performed during loading</li>
<li>JSON schema validation is the responsibility of code that retrieves the metadata</li>
</ul>
</dd>
<dd>
Aaru Metadata JSON Purpose:<ul>
<li>Provides machine-readable structured metadata about the image</li>
<li>Includes comprehensive information about media, sessions, tracks, and checksums</li>
<li>Enables programmatic access to metadata without XML parsing overhead</li>
<li>Complements CICM XML with a more modern, structured format</li>
<li>Used by Aaru and compatible tools for metadata exchange</li>
</ul>
</dd>
<dd>
Non-Critical Nature:<ul>
<li>JSON metadata is optional and supplementary to core image data</li>
<li>Failures reading this block do not prevent image opening</li>
<li>The image remains fully functional for sector data access without JSON metadata</li>
<li>Higher-level code should check if ctx->jsonBlock is non-NULL before use</li>
</ul>
</dd>
<dd>
Distinction from CICM XML:<ul>
<li>Both CICM and Aaru JSON blocks can coexist in the same image</li>
<li>CICM XML follows the Canary Islands Computer Museum schema</li>
<li>Aaru JSON follows the Aaru-specific metadata schema</li>
<li>Different tools may prefer one format over the other</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>Memory allocated for ctx->jsonBlock persists for the context lifetime and must be freed during context cleanup (aaruf_close).</dd>
<dd>
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.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="structAaruMetadataJsonBlockHeader.html"title="Header for an Aaru metadata JSON block (identifier == BlockType::AaruMetadataJsonBlock).">AaruMetadataJsonBlockHeader</a> for the on-disk structure definition. </dd>
<dd>
<aclass="el"href="#a5e0397faed8aea27c5a6a3881875de54"title="Processes a CICM XML metadata block from the image stream.">process_cicm_block()</a> for processing CICM XML metadata blocks. </dd>
<dd>
<aclass="el"href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656"title="Opens an existing AaruFormat image file.">aaruf_open()</a> for the overall image opening sequence. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="blocks_2metadata_8c_source.html#l00470">470</a> of file <aclass="el"href="blocks_2metadata_8c_source.html">metadata.c</a>.</p>
<p>Processes a CICM XML metadata block from the image stream. </p>
<p>Reads a CICM XML metadata block from the image and updates the context with its contents.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context. </td></tr>
<tr><tdclass="paramname">entry</td><td>Pointer to the index entry describing the CICM block. </td></tr>
</table>
</dd>
</dl>
<pclass="definition">Definition at line <aclass="el"href="blocks_2metadata_8c_source.html#l00306">306</a> of file <aclass="el"href="blocks_2metadata_8c_source.html">metadata.c</a>.</p>
<p>Processes a logical geometry block from the image stream. </p>
<p>Reads a logical geometry block from the image and updates the context with its contents.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context. </td></tr>
<tr><tdclass="paramname">entry</td><td>Pointer to the index entry describing the geometry block. </td></tr>
</table>
</dd>
</dl>
<pclass="definition">Definition at line <aclass="el"href="blocks_2metadata_8c_source.html#l00246">246</a> of file <aclass="el"href="blocks_2metadata_8c_source.html">metadata.c</a>.</p>
<p>Processes a metadata block from the image stream. </p>
<p>Reads a metadata block from the image and updates the context with its contents.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context. </td></tr>
<tr><tdclass="paramname">entry</td><td>Pointer to the index entry describing the metadata block. </td></tr>
</table>
</dd>
</dl>
<pclass="definition">Definition at line <aclass="el"href="blocks_2metadata_8c_source.html#l00035">35</a> of file <aclass="el"href="blocks_2metadata_8c_source.html">metadata.c</a>.</p>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.14.0 </li>
