aaru-dps/libaaruformat
1
0
Fork 0
mirror of https://github.com/aaru-dps/libaaruformat.git synced 2026-07-09 02:16:24 +00:00
Code Issues 3 Packages Projects Releases Wiki Activity
Files
devel
libaaruformat/docs/html/metadata_8c.html

1665 lines
137 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.16.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libaaruformat: src/metadata.c File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">libaaruformat<span id="projectnumber">&#160;1.0</span>
</div>
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.16.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(function(){initNavTree('metadata_8c.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="headertitle"><div class="title">metadata.c File Reference</div></div>
</div><!--header-->
<div class="contents">
<p>Read-only metadata accessors for libaaruformat.
<a href="#details">More...</a></p>
<div class="textblock"><code>#include &lt;stddef.h&gt;</code><br />
<code>#include &lt;stdint.h&gt;</code><br />
<code>#include &quot;<a class="el" href="aaruformat_8h_source.html">aaruformat.h</a>&quot;</code><br />
<code>#include &quot;<a class="el" href="log_8h_source.html">log.h</a>&quot;</code><br />
</div>
<p><a href="metadata_8c_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:abbcf276c3518b3e666885ab250fd374e" id="r_abbcf276c3518b3e666885ab250fd374e"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#abbcf276c3518b3e666885ab250fd374e">aaruf_get_geometry</a> (const void *context, uint32_t *cylinders, uint32_t *heads, uint32_t *sectors_per_track)</td></tr>
<tr class="memdesc:abbcf276c3518b3e666885ab250fd374e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the logical CHS geometry from the AaruFormat image. <br /></td></tr>
<tr class="memitem:a42f191c2ea4c70c9d7b373c19b59c812" id="r_a42f191c2ea4c70c9d7b373c19b59c812"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a42f191c2ea4c70c9d7b373c19b59c812">aaruf_get_cicm_metadata</a> (const void *context, uint8_t *buffer, size_t *length)</td></tr>
<tr class="memdesc:a42f191c2ea4c70c9d7b373c19b59c812"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the embedded CICM XML metadata sidecar from the image. <br /></td></tr>
<tr class="memitem:a01cf0abe0b137236d4be0b91a29d4818" id="r_a01cf0abe0b137236d4be0b91a29d4818"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a01cf0abe0b137236d4be0b91a29d4818">aaruf_get_aaru_json_metadata</a> (const void *context, uint8_t *buffer, size_t *length)</td></tr>
<tr class="memdesc:a01cf0abe0b137236d4be0b91a29d4818"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the embedded Aaru metadata JSON from the image. <br /></td></tr>
<tr class="memitem:aa683ff7387ba3f505b1756da1b408f7e" id="r_aa683ff7387ba3f505b1756da1b408f7e"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#aa683ff7387ba3f505b1756da1b408f7e">aaruf_get_media_sequence</a> (const void *context, int32_t *sequence, int32_t *last_sequence)</td></tr>
<tr class="memdesc:aa683ff7387ba3f505b1756da1b408f7e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the media sequence metadata for multi-volume image sets. <br /></td></tr>
<tr class="memitem:a38d72be7e7854d6cb0bba89172e27b03" id="r_a38d72be7e7854d6cb0bba89172e27b03"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a38d72be7e7854d6cb0bba89172e27b03">aaruf_get_creator</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a38d72be7e7854d6cb0bba89172e27b03"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the recorded creator (operator) name from the MetadataBlock. <br /></td></tr>
<tr class="memitem:a9628bcfd2642649a6bcbf1f46d6b6705" id="r_a9628bcfd2642649a6bcbf1f46d6b6705"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a9628bcfd2642649a6bcbf1f46d6b6705">aaruf_get_comments</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a9628bcfd2642649a6bcbf1f46d6b6705"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the user comments or notes stored in the MetadataBlock. <br /></td></tr>
<tr class="memitem:af1ca27c052c6cde38a8d6d71e10936db" id="r_af1ca27c052c6cde38a8d6d71e10936db"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#af1ca27c052c6cde38a8d6d71e10936db">aaruf_get_media_title</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:af1ca27c052c6cde38a8d6d71e10936db"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the media title or label captured during image creation. <br /></td></tr>
<tr class="memitem:a515c264f726f8b0a5104778b383ad1d4" id="r_a515c264f726f8b0a5104778b383ad1d4"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a515c264f726f8b0a5104778b383ad1d4">aaruf_get_media_manufacturer</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a515c264f726f8b0a5104778b383ad1d4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the recorded media manufacturer name. <br /></td></tr>
<tr class="memitem:a509892f76c9a03a030693740d043adfc" id="r_a509892f76c9a03a030693740d043adfc"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a509892f76c9a03a030693740d043adfc">aaruf_get_media_model</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a509892f76c9a03a030693740d043adfc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the media model or product designation metadata. <br /></td></tr>
<tr class="memitem:a4cb7b7200e36efb4983cf2c5c5543313" id="r_a4cb7b7200e36efb4983cf2c5c5543313"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a4cb7b7200e36efb4983cf2c5c5543313">aaruf_get_media_serial_number</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a4cb7b7200e36efb4983cf2c5c5543313"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the media serial number recorded in the image metadata. <br /></td></tr>
<tr class="memitem:a580c8bf133cf3481deca14779b8b5419" id="r_a580c8bf133cf3481deca14779b8b5419"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a580c8bf133cf3481deca14779b8b5419">aaruf_get_media_barcode</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a580c8bf133cf3481deca14779b8b5419"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the barcode assigned to the physical media or its packaging. <br /></td></tr>
<tr class="memitem:a4cdfb46f5630fcf1fe6447b37ad18ae2" id="r_a4cdfb46f5630fcf1fe6447b37ad18ae2"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a4cdfb46f5630fcf1fe6447b37ad18ae2">aaruf_get_media_part_number</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a4cdfb46f5630fcf1fe6447b37ad18ae2"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the media part number recorded in the MetadataBlock. <br /></td></tr>
<tr class="memitem:a5d487a858c48838bcc9f3bba4b5944a1" id="r_a5d487a858c48838bcc9f3bba4b5944a1"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a5d487a858c48838bcc9f3bba4b5944a1">aaruf_get_drive_manufacturer</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a5d487a858c48838bcc9f3bba4b5944a1"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the drive manufacturer metadata captured during imaging. <br /></td></tr>
<tr class="memitem:a54d724659818ea4486f9981672f6d01e" id="r_a54d724659818ea4486f9981672f6d01e"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a54d724659818ea4486f9981672f6d01e">aaruf_get_drive_model</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a54d724659818ea4486f9981672f6d01e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the device model information for the imaging drive. <br /></td></tr>
<tr class="memitem:a1892cc8395305d7e85d04544ded62131" id="r_a1892cc8395305d7e85d04544ded62131"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a1892cc8395305d7e85d04544ded62131">aaruf_get_drive_serial_number</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a1892cc8395305d7e85d04544ded62131"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the imaging drive's serial number metadata. <br /></td></tr>
<tr class="memitem:a3db92f6bebf60195d6ab327e17988cee" id="r_a3db92f6bebf60195d6ab327e17988cee"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a3db92f6bebf60195d6ab327e17988cee">aaruf_get_drive_firmware_revision</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
<tr class="memdesc:a3db92f6bebf60195d6ab327e17988cee"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the firmware revision metadata for the imaging drive. <br /></td></tr>
<tr class="memitem:a7e63f10ff3ea353c8c3944cd836a85ee" id="r_a7e63f10ff3ea353c8c3944cd836a85ee"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a7e63f10ff3ea353c8c3944cd836a85ee">aaruf_get_user_sectors</a> (const void *context, uint64_t *sectors)</td></tr>
<tr class="memdesc:a7e63f10ff3ea353c8c3944cd836a85ee"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the total number of user-accessible sectors in the AaruFormat image. <br /></td></tr>
<tr class="memitem:a381655339050570d969d2ddb60c9407b" id="r_a381655339050570d969d2ddb60c9407b"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a381655339050570d969d2ddb60c9407b">aaruf_get_negative_sectors</a> (const void *context, uint32_t *sectors)</td></tr>
<tr class="memdesc:a381655339050570d969d2ddb60c9407b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the number of negative (pre-gap) sectors in the AaruFormat image. <br /></td></tr>
<tr class="memitem:a108f816aba81cbb0f1401c2a9588660a" id="r_a108f816aba81cbb0f1401c2a9588660a"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a108f816aba81cbb0f1401c2a9588660a">aaruf_get_overflow_sectors</a> (const void *context, uint32_t *sectors)</td></tr>
<tr class="memdesc:a108f816aba81cbb0f1401c2a9588660a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves the number of overflow (post-gap) sectors in the AaruFormat image. <br /></td></tr>
<tr class="memitem:a65c73217edb9661accbbe3de4f555b62" id="r_a65c73217edb9661accbbe3de4f555b62"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a65c73217edb9661accbbe3de4f555b62">aaruf_get_image_info</a> (const void *context, <a class="el" href="structImageInfo.html">ImageInfo</a> *image_info)</td></tr>
<tr class="memdesc:a65c73217edb9661accbbe3de4f555b62"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves a deep copy of the <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure from the AaruFormat image. <br /></td></tr>
</table>
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Read-only metadata accessors for libaaruformat. </p>
<p>Contains all aaruf_get_* functions that retrieve metadata from an opened AaruFormat image context. Writer-side functions (aaruf_set_*, aaruf_clear_*) are in <a class="el" href="metadata__write_8c.html" title="Write-path metadata mutators for libaaruformat.">metadata_write.c</a>.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="metadata__write_8c.html" title="Write-path metadata mutators for libaaruformat.">metadata_write.c</a> </dd></dl>
<p class="definition">Definition in file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
</div><a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
<a id="a01cf0abe0b137236d4be0b91a29d4818" name="a01cf0abe0b137236d4be0b91a29d4818"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a01cf0abe0b137236d4be0b91a29d4818">&#9670;&#160;</a></span>aaruf_get_aaru_json_metadata()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_aaru_json_metadata </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the embedded Aaru metadata JSON from the image. </p>
<p>Aaru metadata JSON is a structured metadata format that provides machine-readable, comprehensive information about the image, media, imaging session details, hardware configuration, optical disc tracks and sessions, checksums, and preservation metadata. This function extracts the raw JSON payload that was embedded in the AaruFormat image during creation. The JSON data is preserved in its original form without parsing or interpretation by the library, allowing callers to process the structured metadata using standard JSON parsing libraries.</p>
<p>This function supports a two-call pattern for buffer size determination:</p><ol type="1">
<li>First call with a buffer that may be too small returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size</li>
<li>Second call with a properly sized buffer retrieves the actual data</li>
</ol>
<p>Alternatively, if the caller already knows the buffer is large enough, a single call will succeed and populate the buffer with the Aaru JSON data.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
<tr><td class="paramname">buffer</td><td>Pointer to a buffer that will receive the Aaru metadata JSON. Must be large enough to hold the entire JSON payload (at least *length bytes on input). The buffer will contain raw UTF-8 encoded JSON data on success. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to a size_t that serves dual purpose:<ul>
<li>On input: size of the provided buffer in bytes</li>
<li>On output: actual size of the Aaru metadata JSON in bytes If the function returns AARUF_ERROR_BUFFER_TOO_SMALL, this will be updated to contain the required buffer size for a subsequent successful call.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Successfully retrieved Aaru metadata JSON. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The Aaru JSON block is present in the image (identifier == AaruMetadataJsonBlock)</li>
<li>The provided buffer is large enough (&gt;= required length)</li>
<li>The Aaru JSON data is successfully copied to the buffer</li>
<li>The *length parameter is set to the actual size of the JSON data</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></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 <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a67753dacbd0ffdd397e563a8a5ecd271" title="Generic block read failure (seek/read error).">AARUF_ERROR_CANNOT_READ_BLOCK</a></td><td>(-7) The Aaru JSON block is not present. This occurs when:<ul>
<li>The image was created without Aaru metadata JSON</li>
<li>ctx-&gt;jsonBlock is NULL (no data loaded)</li>
<li>ctx-&gt;jsonBlockHeader.length is 0 (empty metadata)</li>
<li>ctx-&gt;jsonBlockHeader.identifier doesn't equal AaruMetadataJsonBlock</li>
<li>The Aaru JSON block was not found during image opening</li>
<li>The *length output parameter is set to 0 to indicate no data available</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer is insufficient. This occurs when:<ul>
<li>The input *length is less than ctx-&gt;jsonBlockHeader.length</li>
<li>The *length parameter is updated to contain the required buffer size</li>
<li>No data is copied to the buffer</li>
<li>The caller should allocate a larger buffer and call again</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Aaru 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>The library treats the JSON as opaque binary data</li>
<li>No JSON parsing, interpretation, or validation is performed by libaaruformat</li>
<li>JSON schema validation and parsing are the caller's responsibility</li>
</ul>
</dd>
<dd>
Aaru Metadata JSON Purpose:<ul>
<li>Provides machine-readable structured metadata using modern JSON format</li>
<li>Includes comprehensive information about media, sessions, tracks, and checksums</li>
<li>Enables programmatic access to metadata without XML parsing overhead</li>
<li>Documents imaging session details, hardware configuration, and preservation data</li>
<li>Used by Aaru and compatible tools for metadata exchange and analysis</li>
<li>Complements or serves as alternative to CICM XML metadata</li>
</ul>
</dd>
<dd>
Buffer Size Handling:<ul>
<li>First call with insufficient buffer returns required size in *length</li>
<li>Caller allocates properly sized buffer based on returned length</li>
<li>Second call with adequate buffer retrieves the actual JSON data</li>
<li>Single call succeeds if buffer is already large enough</li>
</ul>
</dd>
<dd>
Data Availability:<ul>
<li>Aaru JSON blocks are optional in AaruFormat images</li>
<li>Not all images will contain Aaru metadata JSON</li>
<li>The presence of JSON data depends on how the image was created</li>
<li>Check return value to handle missing metadata gracefully</li>
<li>Images may contain CICM XML, Aaru JSON, both, or neither</li>
</ul>
</dd>
<dd>
Distinction from CICM XML:<ul>
<li>CICM XML follows the Canary Islands Computer Museum schema (older format)</li>
<li>Aaru JSON follows the Aaru-specific metadata schema (newer format)</li>
<li>Both can coexist in the same image file</li>
<li>Aaru JSON may provide more detailed or different metadata than CICM XML</li>
<li>Different tools and workflows may prefer one format over the other</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>This function reads from the in-memory Aaru JSON block loaded during <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations. The entire JSON is kept in memory for the lifetime of the context.</dd>
<dd>
The buffer parameter must be valid and large enough to hold the JSON data. Passing a buffer smaller than the required size will result in AARUF_ERROR_BUFFER_TOO_SMALL with no partial data copied.</dd>
<dd>
This function does not validate JSON syntax or schema. Corrupted JSON data will be retrieved successfully and errors will only be detected when attempting to parse.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="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>
<a class="el" href="#a42f191c2ea4c70c9d7b373c19b59c812" title="Retrieves the embedded CICM XML metadata sidecar from the image.">aaruf_get_cicm_metadata()</a> for retrieving CICM XML metadata. </dd>
<dd>
<a class="el" href="blocks_2metadata_8c.html#a84003ec881425a7b28ec24cb48d19f02" title="Processes an Aaru metadata JSON block from the image stream during image opening.">process_aaru_metadata_json_block()</a> for the loading process during image opening. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00399">399</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="enums_8h_source.html#l00183">AaruMetadataJsonBlock</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00121">AaruMetadataJsonBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00218">aaruformat_context::json_block</a>, <a class="el" href="context_8h_source.html#l00236">aaruformat_context::json_block_header</a>, <a class="el" href="metadata_8h_source.html#l00122">AaruMetadataJsonBlockHeader::length</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a42f191c2ea4c70c9d7b373c19b59c812" name="a42f191c2ea4c70c9d7b373c19b59c812"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a42f191c2ea4c70c9d7b373c19b59c812">&#9670;&#160;</a></span>aaruf_get_cicm_metadata()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_cicm_metadata </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the embedded CICM XML metadata sidecar from the image. </p>
<p>CICM (Canary Islands Computer Museum) XML is a standardized metadata format used for documenting preservation and archival information about media and disk images. This function extracts the raw CICM XML payload that was embedded in the AaruFormat image during creation. The XML data is preserved in its original form without parsing, interpretation, or validation by the library. The metadata typically includes detailed information about the physical media, imaging process, checksums, device information, and preservation metadata following the CICM schema.</p>
<p>This function supports a two-call pattern for buffer size determination:</p><ol type="1">
<li>First call with a buffer that may be too small returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size</li>
<li>Second call with a properly sized buffer retrieves the actual data</li>
</ol>
<p>Alternatively, if the caller already knows the buffer is large enough, a single call will succeed and populate the buffer with the CICM XML data.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
<tr><td class="paramname">buffer</td><td>Pointer to a buffer that will receive the CICM XML metadata. Must be large enough to hold the entire XML payload (at least *length bytes on input). The buffer will contain raw UTF-8 encoded XML data on success. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to a size_t that serves dual purpose:<ul>
<li>On input: size of the provided buffer in bytes</li>
<li>On output: actual size of the CICM XML metadata in bytes If the function returns AARUF_ERROR_BUFFER_TOO_SMALL, this will be updated to contain the required buffer size for a subsequent successful call.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Successfully retrieved CICM XML metadata. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The CICM block is present in the image (identifier == CicmBlock)</li>
<li>The provided buffer is large enough (&gt;= required length)</li>
<li>The CICM XML data is successfully copied to the buffer</li>
<li>The *length parameter is set to the actual size of the XML data</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></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 <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a67753dacbd0ffdd397e563a8a5ecd271" title="Generic block read failure (seek/read error).">AARUF_ERROR_CANNOT_READ_BLOCK</a></td><td>(-7) The CICM block is not present. This occurs when:<ul>
<li>The image was created without CICM XML metadata</li>
<li>ctx-&gt;cicmBlock is NULL (no data loaded)</li>
<li>ctx-&gt;cicmBlockHeader.length is 0 (empty metadata)</li>
<li>ctx-&gt;cicmBlockHeader.identifier doesn't equal CicmBlock</li>
<li>The CICM block was not found during image opening</li>
<li>The *length output parameter is set to 0 to indicate no data available</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer is insufficient. This occurs when:<ul>
<li>The input *length is less than ctx-&gt;cicmBlockHeader.length</li>
<li>The *length parameter is updated to contain the required buffer size</li>
<li>No data is copied to the buffer</li>
<li>The caller should allocate a larger buffer and call again</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>CICM XML Format:<ul>
<li>The XML is stored in UTF-8 encoding</li>
<li>The payload may or may not be null-terminated</li>
<li>The library treats the XML as opaque binary data</li>
<li>No XML parsing, interpretation, or validation is performed by libaaruformat</li>
<li>Schema validation and XML processing are the caller's responsibility</li>
</ul>
</dd>
<dd>
CICM Metadata Purpose:<ul>
<li>Developed by the Canary Islands Computer Museum for digital preservation</li>
<li>Documents comprehensive preservation metadata</li>
<li>Includes checksums for data integrity verification</li>
<li>Records detailed device and media information</li>
<li>Supports archival and long-term preservation requirements</li>
<li>Provides standardized metadata for digital preservation workflows</li>
<li>Used by cultural heritage institutions and archives</li>
</ul>
</dd>
<dd>
Buffer Size Handling:<ul>
<li>First call with insufficient buffer returns required size in *length</li>
<li>Caller allocates properly sized buffer based on returned length</li>
<li>Second call with adequate buffer retrieves the actual XML data</li>
<li>Single call succeeds if buffer is already large enough</li>
</ul>
</dd>
<dd>
Data Availability:<ul>
<li>CICM blocks are optional in AaruFormat images</li>
<li>Not all images will contain CICM metadata</li>
<li>The presence of CICM data depends on how the image was created</li>
<li>Check return value to handle missing metadata gracefully</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The XML data may contain sensitive information about the imaging environment, personnel, locations, or media content. Handle appropriately for your use case.</dd>
<dd>
This function reads from the in-memory CICM block loaded during <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations. The entire CICM XML is kept in memory for the lifetime of the context.</dd>
<dd>
The buffer parameter must be valid and large enough to hold the XML data. Passing a buffer smaller than the required size will result in AARUF_ERROR_BUFFER_TOO_SMALL with no partial data copied.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="structCicmMetadataBlock.html" title="Header for a CICM XML metadata block (identifier == BlockType::CicmBlock).">CicmMetadataBlock</a> for the on-disk structure definition. </dd>
<dd>
aaruf_set_cicm_metadata() for embedding CICM XML during image creation. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00244">244</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00217">aaruformat_context::cicm_block</a>, <a class="el" href="context_8h_source.html#l00234">aaruformat_context::cicm_block_header</a>, <a class="el" href="enums_8h_source.html#l00175">CicmBlock</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00109">CicmMetadataBlock::identifier</a>, <a class="el" href="metadata_8h_source.html#l00110">CicmMetadataBlock::length</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a9628bcfd2642649a6bcbf1f46d6b6705" name="a9628bcfd2642649a6bcbf1f46d6b6705"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a9628bcfd2642649a6bcbf1f46d6b6705">&#9670;&#160;</a></span>aaruf_get_comments()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_comments </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the user comments or notes stored in the MetadataBlock. </p>
<p>Provides access to the UTF-16LE encoded comments associated with the image. Comments are often used for provenance notes, imaging details, or curator remarks. The function follows the same two-call buffer sizing pattern used by other metadata retrieval APIs: the caller may probe the required size before allocating memory.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer that receives the comments data. May be NULL when probing size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t. On input it contains the size of <code class="param">buffer</code> in bytes; on output it is updated with the actual comments length.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Comments were available and copied successfully. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid or not a libaaruformat context. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No comments metadata exists in the image. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The supplied buffer was too small. *length is updated with the required size and no data is copied.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Comments are stored exactly as provided during image creation and may include multi-line text or other control characters. No validation or normalization is applied by the library. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00616">616</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00221">aaruformat_context::comments</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a38d72be7e7854d6cb0bba89172e27b03" name="a38d72be7e7854d6cb0bba89172e27b03"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a38d72be7e7854d6cb0bba89172e27b03">&#9670;&#160;</a></span>aaruf_get_creator()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_creator </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the recorded creator (operator) name from the MetadataBlock. </p>
<p>Copies the UTF-16LE encoded creator string that identifies the person or operator who created the image. The function supports the common two-call pattern: the caller first determines the required buffer size by passing a buffer that may be NULL or too small, then allocates sufficient memory and calls again to obtain the actual data. On success the buffer contains an opaque UTF-16LE string of length *length bytes (not null-terminated).</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context opened for reading or writing. </td></tr>
<tr><td class="paramname">buffer</td><td>Pointer to the destination buffer that will receive the creator string. May be NULL to query the required size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input specifies the size of <code class="param">buffer</code> in bytes and on output receives the actual length of the creator metadata.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) The creator string was copied successfully. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context is NULL or not an aaruformat context. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) Creator metadata has not been recorded in the image. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer was insufficient; *length contains the required size and no data was copied.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The returned data is UTF-16LE encoded and may contain embedded null characters. Callers should treat it as an opaque byte array unless they explicitly handle UTF-16LE strings.</dd>
<dd>
The function does not allocate memory. Callers are responsible for ensuring <code class="param">buffer</code> is large enough before requesting the data. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00544">544</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00219">aaruformat_context::creator</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a3db92f6bebf60195d6ab327e17988cee" name="a3db92f6bebf60195d6ab327e17988cee"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a3db92f6bebf60195d6ab327e17988cee">&#9670;&#160;</a></span>aaruf_get_drive_firmware_revision()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_drive_firmware_revision </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the firmware revision metadata for the imaging drive. </p>
<p>Returns the UTF-16LE encoded firmware revision string that was captured when the image was created. Firmware information is critical for reproducing imaging environments and diagnosing drive-specific behavior or bugs.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer for the firmware revision string. May be NULL when probing size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t that specifies the buffer capacity in bytes on input and is updated with the actual metadata length on output.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Firmware revision metadata was present and copied successfully. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No firmware metadata exists in the image. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The supplied buffer was too small; *length is updated.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Firmware revision formats vary between manufacturers (e.g., numeric, alphanumeric, dot-separated). The library stores the data verbatim without attempting normalization. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01318">1318</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00231">aaruformat_context::drive_firmware_revision</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a5d487a858c48838bcc9f3bba4b5944a1" name="a5d487a858c48838bcc9f3bba4b5944a1"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a5d487a858c48838bcc9f3bba4b5944a1">&#9670;&#160;</a></span>aaruf_get_drive_manufacturer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_drive_manufacturer </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the drive manufacturer metadata captured during imaging. </p>
<p>Copies the UTF-16LE encoded manufacturer name of the device used to read or write the medium. This information documents the hardware involved in the imaging process, which is crucial for forensic reporting and reproducibility studies.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer for the manufacturer string. May be NULL when querying required length. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t specifying the buffer size on input and receiving the actual metadata length on output.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Drive manufacturer metadata was copied successfully. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) The image lacks drive manufacturer metadata. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer is too small; *length holds the required size for a subsequent call.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The returned manufacturer string corresponds to the value recorded by <a class="el" href="decls_8h.html#a3acb21067897f9cfc40e6288050a60c1" title="Sets the drive manufacturer information for the image.">aaruf_set_drive_manufacturer()</a> and may include branding or OEM designations. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01108">1108</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00227">aaruformat_context::drive_manufacturer</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a54d724659818ea4486f9981672f6d01e" name="a54d724659818ea4486f9981672f6d01e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a54d724659818ea4486f9981672f6d01e">&#9670;&#160;</a></span>aaruf_get_drive_model()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_drive_model </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the device model information for the imaging drive. </p>
<p>Returns the UTF-16LE encoded model identifier for the drive used during acquisition. The model metadata provides finer granularity than the manufacturer name, enabling detailed documentation of imaging hardware capabilities and behavior.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Buffer that receives the model string; may be NULL while probing required capacity. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t indicating buffer size on input and receiving the metadata length on output.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Drive model metadata was available and copied. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No drive model metadata exists in the image. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The supplied buffer was insufficient; *length is updated.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Model strings can include firmware suffixes, interface hints, or OEM variations. Consume the data verbatim to maintain accurate provenance records. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01178">1178</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00228">aaruformat_context::drive_model</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a1892cc8395305d7e85d04544ded62131" name="a1892cc8395305d7e85d04544ded62131"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a1892cc8395305d7e85d04544ded62131">&#9670;&#160;</a></span>aaruf_get_drive_serial_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_drive_serial_number </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the imaging drive's serial number metadata. </p>
<p>Copies the UTF-16LE encoded serial number reported for the drive used during the imaging session. This metadata enables correlation between images and specific hardware units for forensic chain of custody or quality assurance workflows.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer for the serial number; may be NULL when querying size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t carrying the buffer size on input and receiving the actual serial number length on output.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Drive serial number metadata was copied to <code class="param">buffer</code>. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No drive serial number metadata is available. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer was insufficient.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Serial numbers are stored exactly as returned by the imaging hardware and may include leading zeros or spacing that should be preserved. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01248">1248</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00229">aaruformat_context::drive_serial_number</a>, <a class="el" href="metadata_8h_source.html#l00096">MetadataBlockHeader::driveSerialNumberLength</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="abbcf276c3518b3e666885ab250fd374e" name="abbcf276c3518b3e666885ab250fd374e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#abbcf276c3518b3e666885ab250fd374e">&#9670;&#160;</a></span>aaruf_get_geometry()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_geometry </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>cylinders</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>heads</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>sectors_per_track</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the logical CHS geometry from the AaruFormat image. </p>
<p>Reads the Cylinder-Head-Sector (CHS) geometry information from the image's geometry block and returns the values through output parameters. The geometry block contains legacy-style logical addressing parameters that describe how the storage medium was originally organized in terms of cylinders, heads (tracks per cylinder), and sectors per track. This information is essential for software that requires CHS addressing or for accurately representing the original medium's logical structure.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
<tr><td class="paramname">cylinders</td><td>Pointer to store the number of cylinders. Updated on success. </td></tr>
<tr><td class="paramname">heads</td><td>Pointer to store the number of heads (tracks per cylinder). Updated on success. </td></tr>
<tr><td class="paramname">sectors_per_track</td><td>Pointer to store the number of sectors per track. Updated on success.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Successfully retrieved geometry information. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The geometry block is present in the image (identifier == GeometryBlock)</li>
<li>All three output parameters are successfully populated with geometry values</li>
<li>The cylinders parameter contains the total number of cylinders</li>
<li>The heads parameter contains the number of heads per cylinder</li>
<li>The sectors_per_track parameter contains the number of sectors per track</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></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 <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a67753dacbd0ffdd397e563a8a5ecd271" title="Generic block read failure (seek/read error).">AARUF_ERROR_CANNOT_READ_BLOCK</a></td><td>(-7) The geometry block is not present. This occurs when:<ul>
<li>The image was created without geometry information</li>
<li>The geometryBlock.identifier field doesn't equal GeometryBlock</li>
<li>The geometry block was not found during image opening</li>
<li>The image format doesn't support or require CHS geometry</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Geometry Interpretation:<ul>
<li>Total logical sectors = cylinders × heads × sectors_per_track</li>
<li>Sector size is not included in the geometry block and must be obtained separately (typically 512 bytes for most block devices, but can vary)</li>
<li>The geometry represents logical addressing, not necessarily physical medium geometry</li>
<li>Modern storage devices often report translated or synthetic geometry values</li>
</ul>
</dd>
<dd>
CHS Addressing Context:<ul>
<li>CHS addressing was historically used for hard disk drives and floppy disks</li>
<li>Legacy BIOS and older operating systems relied on CHS parameters</li>
<li>LBA (Logical Block Addressing) has largely replaced CHS for modern devices</li>
<li>Some disk image formats and emulators still require CHS information</li>
</ul>
</dd>
<dd>
Geometry Block Availability:<ul>
<li>Not all image types contain geometry blocks</li>
<li>Optical media (CDs, DVDs) typically don't have CHS geometry</li>
<li>Modern large-capacity drives may not have meaningful CHS values</li>
<li>Check the return value to determine if geometry is available</li>
</ul>
</dd>
<dd>
Parameter Validation:<ul>
<li>All output parameters must be non-NULL valid pointers</li>
<li>The function does not validate the geometry values themselves</li>
<li>Geometry values of zero or unusually large values may indicate issues</li>
</ul>
</dd></dl>
<dl class="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>
This function reads from the in-memory geometry block loaded during <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations.</dd>
<dd>
Geometry values may not accurately represent physical device geometry, especially for modern drives with zone-based recording or flash storage. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00104">104</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="data_8h_source.html#l00093">GeometryBlockHeader::cylinders</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::geometry_block</a>, <a class="el" href="enums_8h_source.html#l00172">GeometryBlock</a>, <a class="el" href="data_8h_source.html#l00094">GeometryBlockHeader::heads</a>, <a class="el" href="data_8h_source.html#l00092">GeometryBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="data_8h_source.html#l00095">GeometryBlockHeader::sectorsPerTrack</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a65c73217edb9661accbbe3de4f555b62" name="a65c73217edb9661accbbe3de4f555b62"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a65c73217edb9661accbbe3de4f555b62">&#9670;&#160;</a></span>aaruf_get_image_info()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_image_info </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structImageInfo.html">ImageInfo</a> *</td> <td class="paramname"><span class="paramname"><em>image_info</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves a deep copy of the <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure from the AaruFormat image. </p>
<p>Returns a complete copy of the high-level image information summary containing metadata such as image size, sector count, sector size, version information, creation timestamps, and media type. This function performs a deep copy of all fields including string buffers, ensuring the caller receives a complete, independent copy of the image information.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
<tr><td class="paramname">image_info</td><td>Pointer to an <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure to receive the copied data. Must be a valid pointer to allocated memory.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Successfully copied image info. The image_info parameter contains a complete copy of all fields including:<ul>
<li>HasPartitions: Whether image contains partitions/tracks</li>
<li>HasSessions: Whether image contains multiple sessions</li>
<li>ImageSize: Size of image payload in bytes</li>
<li>Sectors: Total count of addressable sectors/blocks</li>
<li>SectorSize: Size of each logical sector in bytes</li>
<li>Version: Image format version string (NUL-terminated)</li>
<li>Application: Creating application name (NUL-terminated)</li>
<li>ApplicationVersion: Application version string (NUL-terminated)</li>
<li>CreationTime: Image creation timestamp (Windows FILETIME)</li>
<li>LastModificationTime: Last modification timestamp (Windows FILETIME)</li>
<li><a class="el" href="group__MediaTypes.html#ga1499e9f8a76cb81b43b7a4b0dbe7e44a" title="Enumerates every recognized media / cartridge / optical / tape / card / disk format.">MediaType</a>: Media type identifier</li>
<li>MetadataMediaType: Media type for sidecar generation</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></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</li>
<li>The context was not properly initialized</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure contains fixed-size character arrays that are properly NUL-terminated, making it safe to use as C strings.</dd>
<dd>
This function performs a complete deep copy using memcpy, copying all fields including strings, integers, and timestamps.</dd>
<dd>
The caller is responsible for allocating the <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure before calling this function. The structure is not dynamically allocated by this function.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The image_info parameter must point to valid, allocated memory of at least sizeof(ImageInfo) bytes. Passing NULL or invalid pointers will result in undefined behavior.</dd>
<dd>
This function reads from the in-memory image_info loaded during <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or populated during <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. It does not perform file I/O operations. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01774">1774</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00263">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a580c8bf133cf3481deca14779b8b5419" name="a580c8bf133cf3481deca14779b8b5419"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a580c8bf133cf3481deca14779b8b5419">&#9670;&#160;</a></span>aaruf_get_media_barcode()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_media_barcode </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the barcode assigned to the physical media or its packaging. </p>
<p>Returns the UTF-16LE encoded barcode string that was captured when the image was created. Barcodes are commonly used in institutional workflows for inventory tracking and automated retrieval.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Buffer that receives the barcode string; may be NULL when probing size requirements. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t specifying the buffer size on input and receiving the actual barcode length on output.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Barcode metadata was present and copied successfully. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No barcode metadata exists in the image. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The supplied buffer was too small.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Barcode values can be strict alphanumeric codes (e.g., LTO cartridge IDs) or full strings from custom labeling systems. Preserve the returned string exactly for catalog interoperability. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00965">965</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00225">aaruformat_context::media_barcode</a>, <a class="el" href="metadata_8h_source.html#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a515c264f726f8b0a5104778b383ad1d4" name="a515c264f726f8b0a5104778b383ad1d4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a515c264f726f8b0a5104778b383ad1d4">&#9670;&#160;</a></span>aaruf_get_media_manufacturer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_media_manufacturer </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the recorded media manufacturer name. </p>
<p>Provides access to the UTF-16LE encoded manufacturer metadata that identifies the company which produced the physical medium. This information is taken from the MetadataBlock and mirrors the value previously stored via <a class="el" href="decls_8h.html#a3d46262ff1f9d51d57d1e95648f4083b" title="Sets the media manufacturer information for the image.">aaruf_set_media_manufacturer()</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Buffer that receives the manufacturer string. May be NULL when probing size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t specifying the buffer size on input and receiving the actual manufacturer string length on output.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Manufacturer metadata was available and copied. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) The image lacks manufacturer metadata. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer was too small; *length indicates size.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Values may include trailing spaces or vendor-specific capitalization. Treat the returned data as authoritative and avoid trimming unless required by the consuming application. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00756">756</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00222">aaruformat_context::media_manufacturer</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a509892f76c9a03a030693740d043adfc" name="a509892f76c9a03a030693740d043adfc"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a509892f76c9a03a030693740d043adfc">&#9670;&#160;</a></span>aaruf_get_media_model()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_media_model </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the media model or product designation metadata. </p>
<p>Returns the UTF-16LE encoded model name that specifies the exact product variant of the physical medium. The function mirrors the set counterpart and is useful for accurately documenting media specifications during preservation workflows.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer for the model string; may be NULL when querying required size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input contains the buffer capacity in bytes and on output is updated with the actual metadata length.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Model metadata was successfully copied. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No media model metadata is present in the image. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The caller-provided buffer is too small.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Model strings often contain performance ratings (e.g., "16x", "LTO-7"). The data is opaque and should be handled without modification unless necessary. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00826">826</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00223">aaruformat_context::media_model</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a4cdfb46f5630fcf1fe6447b37ad18ae2" name="a4cdfb46f5630fcf1fe6447b37ad18ae2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4cdfb46f5630fcf1fe6447b37ad18ae2">&#9670;&#160;</a></span>aaruf_get_media_part_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_media_part_number </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the media part number recorded in the MetadataBlock. </p>
<p>Provides access to the UTF-16LE encoded part number identifying the precise catalog or ordering code for the physical medium. Part numbers help archivists procure exact replacements and document specific media variants used during acquisition.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer for the part number string. May be NULL while querying size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t that supplies the buffer size on input and is updated with the actual part number length on output.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Part number metadata was returned successfully. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No part number metadata exists. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer was insufficient; *length contains the required size.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Part numbers may include manufacturer-specific formatting such as hyphens or suffix letters. The library stores and returns the data verbatim. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01036">1036</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00226">aaruformat_context::media_part_number</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="aa683ff7387ba3f505b1756da1b408f7e" name="aa683ff7387ba3f505b1756da1b408f7e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa683ff7387ba3f505b1756da1b408f7e">&#9670;&#160;</a></span>aaruf_get_media_sequence()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_media_sequence </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>sequence</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>last_sequence</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the media sequence metadata for multi-volume image sets. </p>
<p>Reads the media sequence fields stored in the MetadataBlock header and returns the current media number together with the final media number for the complete set. This information indicates the position of the imaged medium within a multi-volume collection (for example, "disc 2 of 5"). The function operates entirely on in-memory structures populated during <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a>; no additional disk I/O is performed.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to an initialized aaruformat context opened for reading or writing. </td></tr>
<tr><td class="paramname">sequence</td><td>Pointer that receives the current media sequence number (typically 1-based). </td></tr>
<tr><td class="paramname">last_sequence</td><td>Pointer that receives the total number of media in the set.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Metadata was present and the output parameters were populated. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The provided context pointer is NULL or not an aaruformat context (magic mismatch). </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) The MetadataBlock was not present in the image, making sequence data unavailable.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>For standalone media, both sequence and last_sequence are commonly set to 1. Some creators may also set them to 0 to indicate the absence of sequence semantics; callers should handle either pattern gracefully.</dd>
<dd>
The function does not validate logical consistency (e.g., whether sequence &lt;= last_sequence); it simply returns the values stored in the image header. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00477">477</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="metadata_8h_source.html#l00074">MetadataBlockHeader::lastMediaSequence</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a4cb7b7200e36efb4983cf2c5c5543313" name="a4cb7b7200e36efb4983cf2c5c5543313"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4cb7b7200e36efb4983cf2c5c5543313">&#9670;&#160;</a></span>aaruf_get_media_serial_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_media_serial_number </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the media serial number recorded in the image metadata. </p>
<p>Copies the UTF-16LE encoded serial number identifying the specific physical medium. Serial numbers are particularly important for forensic tracking and archival provenance, enabling correlation between the physical item and its digital representation.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer for the serial number. May be NULL to determine required size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input holds the buffer size and on output receives the actual serial number length.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Serial number metadata was copied into <code class="param">buffer</code>. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No serial number metadata was stored in the image. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The provided buffer was too small.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Serial numbers may contain spaces, hyphens, or alphanumeric characters. The library does not normalize or validate these strings. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00896">896</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00224">aaruformat_context::media_serial_number</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="af1ca27c052c6cde38a8d6d71e10936db" name="af1ca27c052c6cde38a8d6d71e10936db"></a>
<h2 class="memtitle"><span class="permalink"><a href="#af1ca27c052c6cde38a8d6d71e10936db">&#9670;&#160;</a></span>aaruf_get_media_title()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_media_title </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the media title or label captured during image creation. </p>
<p>Returns the UTF-16LE encoded media title string, representing markings or labels present on the original physical media. This function allows applications to present or archive the media title alongside the image, preserving contextual information from the physical artifact.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
<tr><td class="paramname">buffer</td><td>Destination buffer for the UTF-16LE title string. May be NULL when querying size. </td></tr>
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input holds the buffer capacity in bytes and on output receives the actual title length.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) The media title was available and copied to <code class="param">buffer</code>. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></td><td>(-1) The context pointer is invalid. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a99ff8f6884fd5e21840b2e35240bc265" title="Requested metadata not present in image.">AARUF_ERROR_METADATA_NOT_PRESENT</a></td><td>(-30) No media title metadata exists. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#ae7eea5936a22100db46aac3e4312cdae" title="Caller-supplied buffer insufficient for data.">AARUF_ERROR_BUFFER_TOO_SMALL</a></td><td>(-10) The supplied buffer was insufficient.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Titles may contain international characters, control codes, or mixed casing. The library does not attempt to sanitize or interpret the string. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00686">686</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00220">aaruformat_context::media_title</a>, <a class="el" href="metadata_8h_source.html#l00080">MetadataBlockHeader::mediaTitleLength</a>, <a class="el" href="context_8h_source.html#l00233">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00173">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
<a id="a381655339050570d969d2ddb60c9407b" name="a381655339050570d969d2ddb60c9407b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a381655339050570d969d2ddb60c9407b">&#9670;&#160;</a></span>aaruf_get_negative_sectors()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_negative_sectors </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>sectors</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the number of negative (pre-gap) sectors in the AaruFormat image. </p>
<p>Returns the count of negative sectors that precede the standard user data area. Negative sectors are used to capture pre-gap data, lead-in areas, and other metadata that exists before the main user-accessible storage region. This is particularly important for optical media (CD, DVD, BD) where the lead-in contains the Table of Contents (TOC) and other essential disc structures, and for audio CDs where pre-gap sectors contain silence or hidden tracks. For most hard disk and floppy disk images, this value is typically zero.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context (must be properly initialized). </td></tr>
<tr><td class="paramname">sectors</td><td>Pointer to a uint16_t that receives the negative sector count on success.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Successfully retrieved the negative sector count. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context magic number matches AARU_MAGIC</li>
<li>The sectors parameter is successfully populated with the negative sector count</li>
<li>The value is taken from ctx-&gt;user_data_ddt_header.negative</li>
<li>For optical media with lead-in data: sectors may be non-zero</li>
<li>For standard hard disk/floppy images: sectors is typically 0</li>
<li>Maximum value is 65,535 (uint16_t limit)</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></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 <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Negative Sector Addressing:<ul>
<li>Negative sectors are addressed with the 'negative' flag set to true</li>
<li>Sector addresses range from 0 to (negative_sectors - 1)</li>
<li>When calling <a class="el" href="decls_8h.html#a2297e89619ba11cb0a0779a985fc1c34" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> or <a class="el" href="decls_8h.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>:<ul>
<li>Use negative=true</li>
<li>Use sector_address in range [0, negative_sectors - 1]</li>
<li>The actual logical position is before the user data area</li>
</ul>
</li>
</ul>
</dd>
<dd>
Optical Media Context:<ul>
<li><b>CD-ROM/CD-DA</b>: Negative sectors contain lead-in area with TOC (Table of Contents). The lead-in typically spans LBA -450000 to -1, though only a portion may be captured. Pre-gap sectors (usually 150 sectors/2 seconds before each track) may also be stored as negative sectors for the first track.</li>
<li><b>DVD</b>: May contain lead-in with disc structure information, copyright data, and region codes. The lead-in area varies by format (DVD-ROM, DVD-R, DVD+R, etc.).</li>
<li><b>Blu-ray</b>: Lead-in contains disc information, burst cutting area (BCA), and other metadata. The structure differs between BD-ROM, BD-R, and BD-RE.</li>
</ul>
</dd>
<dd>
Hard Disk and Floppy Context:<ul>
<li>Hard disk drives: Negative sectors are typically zero unless capturing special manufacturer reserved areas (HPA, DCO) that precede the standard user area.</li>
<li>Floppy disks: Negative sectors are typically zero as floppies have a simple linear sector layout without lead-in areas.</li>
</ul>
</dd>
<dd>
Audio CD Hidden Tracks:<ul>
<li>Some audio CDs contain hidden tracks in the pre-gap of the first track</li>
<li>These pre-gap sectors can extend up to several minutes before track 1</li>
<li>Negative sectors can capture this "hidden" audio data</li>
<li>The pre-gap for track 1 typically starts at LBA -150 (2 seconds)</li>
</ul>
</dd>
<dd>
DDT Header Source:<ul>
<li>The value is retrieved from ctx-&gt;user_data_ddt_header.negative</li>
<li>The DDT (Deduplication and Data Table) header tracks all sector allocation</li>
<li>This field is populated during image creation with <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The value is fixed for read-only images opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
<li>Maximum representable value is 65,535 (uint16_t)</li>
</ul>
</dd>
<dd>
Total Addressable Space:<ul>
<li>Total sectors = negative_sectors + user_sectors + overflow_sectors</li>
<li>The negative region comes first in logical order</li>
<li>Followed by the user region [0, user_sectors - 1]</li>
<li>Followed by the overflow region if present</li>
</ul>
</dd>
<dd>
Relationship to Image Creation:<ul>
<li>The negative_sectors value is specified when calling <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>It should be set based on the medium type and imaging requirements:<ul>
<li>Optical discs: Set to the number of lead-in sectors captured</li>
<li>Hard disks: Typically 0, unless capturing HPA/DCO areas</li>
<li>Floppy disks: Typically 0</li>
<li>Audio CDs: May be non-zero to capture pre-gap hidden tracks</li>
</ul>
</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The sectors parameter is only modified on success (AARUF_STATUS_OK). On error, its value remains unchanged. Initialize it before calling if a default value is needed on failure.</dd>
<dd>
This function reads from the in-memory DDT header loaded during <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or set during <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. It does not perform file I/O operations and executes quickly.</dd>
<dd>
The maximum negative sector count is 65,535 due to the uint16_t storage type. If imaging optical media with larger lead-in areas, some data may not be representable. This limit is generally sufficient for most practical cases.</dd>
<dd>
Negative sector data may contain copy-protected or encrypted content (e.g., CSS on DVDs, AACS on Blu-rays). Handle this data according to applicable laws and licensing agreements. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01557">1557</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00192">aaruformat_context::user_data_ddt_header</a>.</p>
</div>
</div>
<a id="a108f816aba81cbb0f1401c2a9588660a" name="a108f816aba81cbb0f1401c2a9588660a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a108f816aba81cbb0f1401c2a9588660a">&#9670;&#160;</a></span>aaruf_get_overflow_sectors()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_overflow_sectors </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>sectors</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the number of overflow (post-gap) sectors in the AaruFormat image. </p>
<p>Returns the count of overflow sectors that follow the standard user data area. Overflow sectors are used to capture post-gap data, lead-out areas, and other metadata that exists after the main user-accessible storage region. This is particularly important for optical media (CD, DVD, BD) where the lead-out marks the physical end of the recorded data and contains disc finalization information, and for multi-session discs where gaps between sessions need to be preserved. For most hard disk and floppy disk images, this value is typically zero.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context (must be properly initialized). </td></tr>
<tr><td class="paramname">sectors</td><td>Pointer to a uint16_t that receives the overflow sector count on success.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Successfully retrieved the overflow sector count. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context magic number matches AARU_MAGIC</li>
<li>The sectors parameter is successfully populated with the overflow sector count</li>
<li>The value is taken from ctx-&gt;user_data_ddt_header.overflow</li>
<li>For optical media with lead-out data: sectors may be non-zero</li>
<li>For standard hard disk/floppy images: sectors is typically 0</li>
<li>Maximum value is 65,535 (uint16_t limit)</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></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 <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Overflow Sector Addressing:<ul>
<li>Overflow sectors are addressed with the 'negative' flag set to false</li>
<li>Sector addresses range from user_sectors to (user_sectors + overflow_sectors - 1)</li>
<li>When calling <a class="el" href="decls_8h.html#a2297e89619ba11cb0a0779a985fc1c34" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> or <a class="el" href="decls_8h.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>:<ul>
<li>Use negative=false</li>
<li>Use sector_address in range [user_sectors, user_sectors + overflow_sectors - 1]</li>
<li>The actual logical position is after the user data area</li>
</ul>
</li>
</ul>
</dd>
<dd>
Optical Media Context:<ul>
<li><b>CD-ROM/CD-DA</b>: Overflow sectors contain the lead-out area, which marks the physical end of the disc's recorded data. The lead-out consists of unreadable sectors filled with specific patterns.</li>
<li><b>DVD</b>: May contain lead-out with disc finalization data, middle area (for dual-layer), and outer zone. DVD+R/RW discs may have substantial lead-out areas.</li>
<li><b>Blu-ray</b>: Lead-out contains disc finalization markers and padding. For multi-layer discs, may include middle zones and outer areas.</li>
</ul>
</dd>
<dd>
Multi-Session and Track Context:<ul>
<li>Multi-session optical discs have gaps between sessions</li>
<li>Audio CDs with post-gap after the last track may use overflow sectors</li>
<li>Track post-gaps (silence after audio tracks) typically 2 seconds/150 sectors</li>
</ul>
</dd>
<dd>
Hard Disk and Floppy Context:<ul>
<li>Hard disk drives: Overflow sectors are typically zero unless capturing special manufacturer reserved areas (like DCO or HPA) that follow the standard user area.</li>
<li>Floppy disks: Overflow sectors are typically zero as floppies have a simple linear sector layout without lead-out areas. They may contain mastering information.</li>
<li>Some proprietary copy protection schemes may place data beyond the normal capacity, which could be captured as overflow sectors.</li>
</ul>
</dd>
<dd>
DDT Header Source:<ul>
<li>The value is retrieved from ctx-&gt;user_data_ddt_header.overflow</li>
<li>The DDT (Deduplication and Data Table) header tracks all sector allocation</li>
<li>This field is populated during image creation with <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The value is fixed for read-only images opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
<li>Maximum representable value is 65,535 (uint16_t)</li>
</ul>
</dd>
<dd>
Total Addressable Space:<ul>
<li>Total sectors = negative_sectors + user_sectors + overflow_sectors</li>
<li>The negative region comes first in logical order</li>
<li>Followed by the user region [0, user_sectors - 1]</li>
<li>Followed by the overflow region at the end</li>
<li>Overflow represents the final addressable range in the image</li>
</ul>
</dd>
<dd>
Relationship to Image Creation:<ul>
<li>The overflow_sectors value is specified when calling <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>It should be set based on the medium type and imaging requirements:<ul>
<li>Optical discs: Set to the number of lead-out sectors captured</li>
<li>Multi-session discs: May include inter-session gaps</li>
<li>Hard disks: Typically 0, unless capturing post-user reserved areas</li>
<li>Floppy disks: Typically 0</li>
<li>Copy-protected media: May be non-zero to capture protection schemes</li>
</ul>
</li>
</ul>
</dd>
<dd>
Forensic Imaging Considerations:<ul>
<li>Some copy protection schemes intentionally place data in overflow regions</li>
<li>These "overburn" areas extend beyond the disc's rated capacity</li>
<li>Overflow sectors ensure complete forensic capture of all readable data</li>
<li>Important for authenticity verification and copy protection analysis</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The sectors parameter is only modified on success (AARUF_STATUS_OK). On error, its value remains unchanged. Initialize it before calling if a default value is needed on failure.</dd>
<dd>
This function reads from the in-memory DDT header loaded during <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or set during <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. It does not perform file I/O operations and executes quickly.</dd>
<dd>
The maximum overflow sector count is 65,535 due to the uint16_t storage type. If imaging optical media with larger lead-out areas or extensive overburn regions, some data may not be representable. This limit is generally sufficient for most practical cases.</dd>
<dd>
Overflow sector data may be difficult or impossible to read on some drives, as it often resides in lead-out areas or beyond rated capacity. The presence of overflow sectors in an image indicates the imaging drive was capable of reading these extended areas, but other drives may not be able to access them. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01692">1692</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00192">aaruformat_context::user_data_ddt_header</a>.</p>
</div>
</div>
<a id="a7e63f10ff3ea353c8c3944cd836a85ee" name="a7e63f10ff3ea353c8c3944cd836a85ee"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a7e63f10ff3ea353c8c3944cd836a85ee">&#9670;&#160;</a></span>aaruf_get_user_sectors()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_get_user_sectors </td>
<td>(</td>
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>sectors</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the total number of user-accessible sectors in the AaruFormat image. </p>
<p>Returns the count of standard user data sectors in the image, excluding any negative (pre-gap) or overflow (post-gap) sectors. This represents the primary addressable sector range that contains the main user data, typically corresponding to the logical capacity of the storage medium as it would be seen by an operating system or file system. For optical media, this excludes lead-in and lead-out areas. For hard disks, this represents the standard LBA-addressable range.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context (must be properly initialized). </td></tr>
<tr><td class="paramname">sectors</td><td>Pointer to a uint64_t that receives the total user sector count on success.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1d6e49f7e8a1fa489efa0a582e90b5de" title="Sector present and read without uncorrectable errors.">AARUF_STATUS_OK</a></td><td>(0) Successfully retrieved the user sector count. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context magic number matches AARU_MAGIC</li>
<li>The sectors parameter is successfully populated with the user sector count</li>
<li>The value is taken from ctx-&gt;user_data_ddt_header.blocks</li>
<li>For block devices: sectors typically equals the total capacity in sectors</li>
<li>For optical media: sectors represents the user data area excluding lead-in/lead-out</li>
<li>For tape media: sectors may represent the total block count across all files</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#abb63e240b11d790da83bd34507b57851" title="Input file/stream failed magic or structural validation.">AARUF_ERROR_NOT_AARUFORMAT</a></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 <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Sector Range Context:<ul>
<li>User sectors represent the standard addressable range: 0 to (user_sectors - 1)</li>
<li>Total addressable sectors = negative_sectors + user_sectors + overflow_sectors</li>
<li>Negative sectors precede user sectors (pre-gap, lead-in)</li>
<li>Overflow sectors follow user sectors (post-gap, lead-out)</li>
<li>Use <a class="el" href="#a381655339050570d969d2ddb60c9407b" title="Retrieves the number of negative (pre-gap) sectors in the AaruFormat image.">aaruf_get_negative_sectors()</a> to get the negative sector count</li>
<li>Use <a class="el" href="#a108f816aba81cbb0f1401c2a9588660a" title="Retrieves the number of overflow (post-gap) sectors in the AaruFormat image.">aaruf_get_overflow_sectors()</a> to get the overflow sector count</li>
</ul>
</dd>
<dd>
Media Type Considerations:<ul>
<li><b>Optical Media (CD/DVD/BD)</b>: User sectors exclude lead-in and lead-out areas. Negative sectors may contain TOC and pre-gap data. Overflow sectors may contain post-gap and lead-out data.</li>
<li><b>Hard Disk Drives</b>: User sectors represent the full LBA range. Negative and overflow sectors are typically zero unless capturing special areas.</li>
<li><b>Floppy Disks</b>: User sectors represent the standard formatted capacity.</li>
<li><b>Tape Media</b>: User sectors may represent the total block count. Negative and overflow sectors are typically not used for tape.</li>
</ul>
</dd>
<dd>
DDT Header Source:<ul>
<li>The value is retrieved from ctx-&gt;user_data_ddt_header.blocks</li>
<li>The DDT (Deduplication and Data Table) header tracks sector allocation</li>
<li>This field is populated during image creation with <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The value is fixed for read-only images opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
<li>For write-enabled images, this represents the allocated capacity</li>
</ul>
</dd>
<dd>
Addressing and I/O Operations:<ul>
<li>When reading/writing sectors with <a class="el" href="decls_8h.html#a2297e89619ba11cb0a0779a985fc1c34" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> or <a class="el" href="decls_8h.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>:<ul>
<li>Set negative=false and use sector_address in range [0, user_sectors - 1]</li>
<li>For negative sectors: set negative=true, sector_address in [0, negative_sectors - 1]</li>
<li>For overflow sectors: set negative=false, sector_address in [user_sectors, user_sectors + overflow_sectors</li>
</ul>
</li>
</ul>
</dd></dl>
<ul>
<li>1]</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>Relationship to Image Creation:<ul>
<li>The user_sectors value is specified when calling <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>It should match the logical capacity of the medium being imaged</li>
<li>For forensic images, ensure it matches the source medium exactly</li>
<li>For virtual disks, set it to the desired capacity </li>
</ul>
</dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01432">1432</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
<p class="reference">References <a class="el" href="decls_8h_source.html#l00046">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00055">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="ddt_8h_source.html#l00150">DdtHeader2::blocks</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00192">aaruformat_context::user_data_ddt_header</a>.</p>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a href="dir_68267d1309a1af8e8297ef4c3efbcdba.html">src</a></li><li class="navelem"><a href="metadata_8c.html">metadata.c</a></li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.16.1 </li>
</ul>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink