aaru-dps/libaaruformat
1
0
Fork 0
mirror of https://github.com/aaru-dps/libaaruformat.git synced 2026-04-20 13:03:27 +00:00
Code Issues 3 Packages Projects Releases Wiki Activity
Files
6aa55d7e3f7df772ebfa7ec9a100e383527cfdde
libaaruformat/docs/html/metadata__write_8c.html

2731 lines
228 KiB
HTML
Raw 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_write.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__write_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_write.c File Reference</div></div>
</div><!--header-->
<div class="contents">
<p>Write-path metadata mutators 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__write_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:ad0b5b12288f159780d065b12ba12bdcc" id="r_ad0b5b12288f159780d065b12ba12bdcc"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#ad0b5b12288f159780d065b12ba12bdcc">aaruf_set_geometry</a> (void *context, const uint32_t cylinders, const uint32_t heads, const uint32_t sectors_per_track)</td></tr>
<tr class="memdesc:ad0b5b12288f159780d065b12ba12bdcc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the logical CHS geometry for the AaruFormat image. <br /></td></tr>
<tr class="memitem:a10d528163caf65134a7cec4a0c0a33b8" id="r_a10d528163caf65134a7cec4a0c0a33b8"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a10d528163caf65134a7cec4a0c0a33b8">aaruf_set_media_sequence</a> (void *context, const int32_t sequence, const int32_t last_sequence)</td></tr>
<tr class="memdesc:a10d528163caf65134a7cec4a0c0a33b8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the media sequence information for multi-volume media sets. <br /></td></tr>
<tr class="memitem:af28837461d12252d8258032e370585ae" id="r_af28837461d12252d8258032e370585ae"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#af28837461d12252d8258032e370585ae">aaruf_set_creator</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:af28837461d12252d8258032e370585ae"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the creator (person/operator) information for the image. <br /></td></tr>
<tr class="memitem:ad24b15e067720825c47610e9477bfc2a" id="r_ad24b15e067720825c47610e9477bfc2a"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#ad24b15e067720825c47610e9477bfc2a">aaruf_set_comments</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:ad24b15e067720825c47610e9477bfc2a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets user comments or notes for the image. <br /></td></tr>
<tr class="memitem:a2f344544e412db0bfb46d3dfb509dd91" id="r_a2f344544e412db0bfb46d3dfb509dd91"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a2f344544e412db0bfb46d3dfb509dd91">aaruf_set_media_title</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:a2f344544e412db0bfb46d3dfb509dd91"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the media title or label for the image. <br /></td></tr>
<tr class="memitem:add92b8c91ede6a62dfda5f8980c3ce6d" id="r_add92b8c91ede6a62dfda5f8980c3ce6d"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#add92b8c91ede6a62dfda5f8980c3ce6d">aaruf_set_media_manufacturer</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:add92b8c91ede6a62dfda5f8980c3ce6d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the media manufacturer information for the image. <br /></td></tr>
<tr class="memitem:a0ed36b14e49f1e924906d9c4b26d6214" id="r_a0ed36b14e49f1e924906d9c4b26d6214"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a0ed36b14e49f1e924906d9c4b26d6214">aaruf_set_media_model</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:a0ed36b14e49f1e924906d9c4b26d6214"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the media model or product designation for the image. <br /></td></tr>
<tr class="memitem:ad06ae4d49d6de002ef565108c73451e1" id="r_ad06ae4d49d6de002ef565108c73451e1"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#ad06ae4d49d6de002ef565108c73451e1">aaruf_set_media_serial_number</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:ad06ae4d49d6de002ef565108c73451e1"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the media serial number for the image. <br /></td></tr>
<tr class="memitem:a0e5be9ff6d87218a8f5b451a27e1b39b" id="r_a0e5be9ff6d87218a8f5b451a27e1b39b"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a0e5be9ff6d87218a8f5b451a27e1b39b">aaruf_set_media_barcode</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:a0e5be9ff6d87218a8f5b451a27e1b39b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the media barcode information for the image. <br /></td></tr>
<tr class="memitem:ac7c87ae51a242428ceb6d2b0a75e0b70" id="r_ac7c87ae51a242428ceb6d2b0a75e0b70"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#ac7c87ae51a242428ceb6d2b0a75e0b70">aaruf_set_media_part_number</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:ac7c87ae51a242428ceb6d2b0a75e0b70"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the media part number or model designation for the image. <br /></td></tr>
<tr class="memitem:a223856fa226b26c466997800183c97c4" id="r_a223856fa226b26c466997800183c97c4"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a223856fa226b26c466997800183c97c4">aaruf_set_drive_manufacturer</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:a223856fa226b26c466997800183c97c4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the drive manufacturer information for the image. <br /></td></tr>
<tr class="memitem:a29b6c38ce4b3420368ecb84007d8738d" id="r_a29b6c38ce4b3420368ecb84007d8738d"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a29b6c38ce4b3420368ecb84007d8738d">aaruf_set_drive_model</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:a29b6c38ce4b3420368ecb84007d8738d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the drive model information for the image. <br /></td></tr>
<tr class="memitem:ae6b0a57476896bb90ee7bb8472e1078f" id="r_ae6b0a57476896bb90ee7bb8472e1078f"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#ae6b0a57476896bb90ee7bb8472e1078f">aaruf_set_drive_serial_number</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:ae6b0a57476896bb90ee7bb8472e1078f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the drive serial number for the image. <br /></td></tr>
<tr class="memitem:adaa13a82dfc90987efd6c9a366904dc4" id="r_adaa13a82dfc90987efd6c9a366904dc4"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#adaa13a82dfc90987efd6c9a366904dc4">aaruf_set_drive_firmware_revision</a> (void *context, const uint8_t *data, const int32_t length)</td></tr>
<tr class="memdesc:adaa13a82dfc90987efd6c9a366904dc4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the drive firmware revision for the image. <br /></td></tr>
<tr class="memitem:a8090a039e00ee003569939332d21094e" id="r_a8090a039e00ee003569939332d21094e"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a8090a039e00ee003569939332d21094e">aaruf_set_aaru_json_metadata</a> (void *context, uint8_t *data, size_t length)</td></tr>
<tr class="memdesc:a8090a039e00ee003569939332d21094e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets the Aaru metadata JSON for the image during creation. <br /></td></tr>
<tr class="memitem:a02699c3490df86f9919ac8f22f303d9e" id="r_a02699c3490df86f9919ac8f22f303d9e"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a02699c3490df86f9919ac8f22f303d9e">aaruf_clear_media_sequence</a> (void *context)</td></tr>
<tr class="memdesc:a02699c3490df86f9919ac8f22f303d9e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the media sequence information from the image metadata. <br /></td></tr>
<tr class="memitem:ac20c45113b5e1917fc550d1fb8342ba2" id="r_ac20c45113b5e1917fc550d1fb8342ba2"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#ac20c45113b5e1917fc550d1fb8342ba2">aaruf_clear_creator</a> (void *context)</td></tr>
<tr class="memdesc:ac20c45113b5e1917fc550d1fb8342ba2"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the creator (person/operator) information from the image metadata. <br /></td></tr>
<tr class="memitem:a878605956a88a3371f4f6e490ee9e2b8" id="r_a878605956a88a3371f4f6e490ee9e2b8"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a878605956a88a3371f4f6e490ee9e2b8">aaruf_clear_comments</a> (void *context)</td></tr>
<tr class="memdesc:a878605956a88a3371f4f6e490ee9e2b8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears user comments or notes from the image metadata. <br /></td></tr>
<tr class="memitem:a41bf934e213aad15df933590e6343c3e" id="r_a41bf934e213aad15df933590e6343c3e"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a41bf934e213aad15df933590e6343c3e">aaruf_clear_media_title</a> (void *context)</td></tr>
<tr class="memdesc:a41bf934e213aad15df933590e6343c3e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the media title or label from the image metadata. <br /></td></tr>
<tr class="memitem:a42e1c4b1876e6b28c774aae4de3c1f4e" id="r_a42e1c4b1876e6b28c774aae4de3c1f4e"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a42e1c4b1876e6b28c774aae4de3c1f4e">aaruf_clear_media_manufacturer</a> (void *context)</td></tr>
<tr class="memdesc:a42e1c4b1876e6b28c774aae4de3c1f4e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the media manufacturer information from the image metadata. <br /></td></tr>
<tr class="memitem:a938d3346f5347dc152b679e6cf619d94" id="r_a938d3346f5347dc152b679e6cf619d94"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a938d3346f5347dc152b679e6cf619d94">aaruf_clear_media_model</a> (void *context)</td></tr>
<tr class="memdesc:a938d3346f5347dc152b679e6cf619d94"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the media model or product designation from the image metadata. <br /></td></tr>
<tr class="memitem:a21d65b63e9806deb6dd0eb9c0e69eaf0" id="r_a21d65b63e9806deb6dd0eb9c0e69eaf0"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a21d65b63e9806deb6dd0eb9c0e69eaf0">aaruf_clear_media_serial_number</a> (void *context)</td></tr>
<tr class="memdesc:a21d65b63e9806deb6dd0eb9c0e69eaf0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the media serial number from the image metadata. <br /></td></tr>
<tr class="memitem:a2b5ef51f1913c62139b90cae0f97a9a2" id="r_a2b5ef51f1913c62139b90cae0f97a9a2"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a2b5ef51f1913c62139b90cae0f97a9a2">aaruf_clear_media_barcode</a> (void *context)</td></tr>
<tr class="memdesc:a2b5ef51f1913c62139b90cae0f97a9a2"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the media barcode information from the image metadata. <br /></td></tr>
<tr class="memitem:a8652ae4a4cdf400846621d7f497c8b60" id="r_a8652ae4a4cdf400846621d7f497c8b60"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a8652ae4a4cdf400846621d7f497c8b60">aaruf_clear_media_part_number</a> (void *context)</td></tr>
<tr class="memdesc:a8652ae4a4cdf400846621d7f497c8b60"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the media part number or model designation from the image metadata. <br /></td></tr>
<tr class="memitem:a62dc66d1bbbfacd41706bf4d87d11264" id="r_a62dc66d1bbbfacd41706bf4d87d11264"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a62dc66d1bbbfacd41706bf4d87d11264">aaruf_clear_drive_manufacturer</a> (void *context)</td></tr>
<tr class="memdesc:a62dc66d1bbbfacd41706bf4d87d11264"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the drive manufacturer information from the image metadata. <br /></td></tr>
<tr class="memitem:a43615f5e79107a192d383d230fa308e0" id="r_a43615f5e79107a192d383d230fa308e0"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a43615f5e79107a192d383d230fa308e0">aaruf_clear_drive_model</a> (void *context)</td></tr>
<tr class="memdesc:a43615f5e79107a192d383d230fa308e0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the drive model information from the image metadata. <br /></td></tr>
<tr class="memitem:aa6d7ceaf960a4e8d4494424f11815fcb" id="r_aa6d7ceaf960a4e8d4494424f11815fcb"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#aa6d7ceaf960a4e8d4494424f11815fcb">aaruf_clear_drive_serial_number</a> (void *context)</td></tr>
<tr class="memdesc:aa6d7ceaf960a4e8d4494424f11815fcb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the drive serial number from the image metadata. <br /></td></tr>
<tr class="memitem:a0d7349a92ffce2fa5515fae960c17b03" id="r_a0d7349a92ffce2fa5515fae960c17b03"><td class="memItemLeft">int32_t&#160;</td><td class="memItemRight"><a class="el" href="#a0d7349a92ffce2fa5515fae960c17b03">aaruf_clear_drive_firmware_revision</a> (void *context)</td></tr>
<tr class="memdesc:a0d7349a92ffce2fa5515fae960c17b03"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clears the drive firmware revision from the image metadata. <br /></td></tr>
</table>
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Write-path metadata mutators for libaaruformat. </p>
<p>Contains all aaruf_set_* and aaruf_clear_* functions that modify metadata in an AaruFormat image context opened for writing. Read-only accessors (aaruf_get_*) are in metadata.c.</p>
<dl class="section see"><dt>See also</dt><dd>metadata.c </dd></dl>
<p class="definition">Definition in file <a class="el" href="metadata__write_8c_source.html">metadata_write.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="a878605956a88a3371f4f6e490ee9e2b8" name="a878605956a88a3371f4f6e490ee9e2b8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a878605956a88a3371f4f6e490ee9e2b8">&#9670;&#160;</a></span>aaruf_clear_comments()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_comments </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears user comments or notes from the image metadata. </p>
<p>Removes the comments string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This effectively removes any user-provided annotations, notes, or descriptions associated with the image. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized to avoid writing an empty metadata block to the image file.</p>
<p>This function is useful when removing outdated notes, clearing test comments before production deployment, sanitizing images for distribution, or resetting an image to a clean metadata state for repurposing.</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, write-enabled image context).</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 cleared comments. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Either the metadata block was not initialized (early exit, nothing to clear)</li>
<li>Or the comments string is freed (if it existed) and the pointer set to NULL</li>
<li>The commentsLength field in the metadata block header is set to 0</li>
<li>If all metadata fields are now empty, the metadata block identifier is cleared</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management:<ul>
<li>If ctx-&gt;comments is not NULL, the allocated memory is freed before clearing</li>
<li>The ctx-&gt;comments pointer is set to NULL after freeing</li>
<li>Safe to call even if comments were never set (NULL check protects against errors)</li>
<li>No memory leaks occur when clearing previously set comments</li>
</ul>
</dd>
<dd>
Use Cases:<ul>
<li>Removing temporary or development notes before production deployment</li>
<li>Clearing outdated comments that no longer apply</li>
<li>Sanitizing images for distribution by removing internal notes</li>
<li>Resetting images for repurposing with new documentation</li>
<li>Removing potentially sensitive information from comments</li>
<li>Preparing images for archival with standardized, minimal metadata</li>
</ul>
</dd>
<dd>
Metadata Block State Management:<ul>
<li>If the metadata block header is not initialized, function returns success immediately</li>
<li>After clearing, checks if all metadata fields are empty</li>
<li>If all fields empty, sets metadata block identifier to 0 (deinitialized)</li>
<li>Prevents writing empty metadata blocks, optimizing storage efficiency</li>
</ul>
</dd>
<dd>
Information Loss Considerations:<ul>
<li>Comments may contain valuable provenance or preservation information</li>
<li>Consider archiving comments externally before clearing if they contain important data</li>
<li>Comments might document imaging conditions, errors encountered, or quality notes</li>
<li>Workflow history and processing information may be lost</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata changes are only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted to disk.</dd>
<dd>
After clearing, the comments are permanently lost unless:<ul>
<li>The image file is not closed (context remains in memory)</li>
<li>A backup of the original image exists</li>
<li>The comments are documented in external metadata systems</li>
</ul>
</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#ad24b15e067720825c47610e9477bfc2a" title="Sets user comments or notes for the image.">aaruf_set_comments()</a> for setting comment information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02238">2238</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</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="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="ac20c45113b5e1917fc550d1fb8342ba2" name="ac20c45113b5e1917fc550d1fb8342ba2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac20c45113b5e1917fc550d1fb8342ba2">&#9670;&#160;</a></span>aaruf_clear_creator()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_creator </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the creator (person/operator) information from the image metadata. </p>
<p>Removes the creator name string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This effectively removes any record of who created the image. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized to avoid writing an empty metadata block to the image file.</p>
<p>This function is useful when anonymizing images for distribution, removing personally identifiable information for privacy compliance (e.g., GDPR), or correcting metadata that was set incorrectly during image creation.</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, write-enabled image context).</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 cleared creator information. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Either the metadata block was not initialized (early exit, nothing to clear)</li>
<li>Or the creator string is freed (if it existed) and the pointer set to NULL</li>
<li>The creatorLength field in the metadata block header is set to 0</li>
<li>If all metadata fields are now empty, the metadata block identifier is cleared</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management:<ul>
<li>If ctx-&gt;creator is not NULL, the allocated memory is freed before clearing</li>
<li>The ctx-&gt;creator pointer is set to NULL after freeing</li>
<li>Safe to call even if creator was never set (NULL check protects against errors)</li>
<li>No memory leaks occur when clearing previously set creator information</li>
</ul>
</dd>
<dd>
Privacy and Anonymization:<ul>
<li>Removes personally identifiable information from image metadata</li>
<li>Important for GDPR compliance and privacy protection</li>
<li>Consider clearing creator before distributing images publicly</li>
<li>May be required by institutional privacy policies</li>
</ul>
</dd>
<dd>
Metadata Block State Management:<ul>
<li>If the metadata block header is not initialized, function returns success immediately</li>
<li>After clearing, checks if all metadata fields are empty</li>
<li>If all fields empty, sets metadata block identifier to 0 (deinitialized)</li>
<li>Prevents writing empty metadata blocks, saving storage space</li>
</ul>
</dd>
<dd>
Use Cases:<ul>
<li>Anonymizing images for public distribution or research datasets</li>
<li>Compliance with data protection regulations (GDPR, CCPA, etc.)</li>
<li>Removing incorrect or outdated operator information</li>
<li>Preparing images for archival with institutional rather than personal attribution</li>
<li>Sanitizing test or development images before production use</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata changes are only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted to disk.</dd>
<dd>
After clearing, the creator information is permanently lost unless:<ul>
<li>The image file is not closed (context remains in memory)</li>
<li>A backup of the original image exists</li>
<li>The information is reconstructed from external documentation</li>
</ul>
</dd>
<dd>
Clearing creator may affect:<ul>
<li>Forensic chain of custody requirements</li>
<li>Provenance documentation for archival purposes</li>
<li>Accountability and quality assurance workflows</li>
<li>Consider legal and institutional requirements before clearing</li>
</ul>
</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#af28837461d12252d8258032e370585ae" title="Sets the creator (person/operator) information for the image.">aaruf_set_creator()</a> for setting creator information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02109">2109</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</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="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a0d7349a92ffce2fa5515fae960c17b03" name="a0d7349a92ffce2fa5515fae960c17b03"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a0d7349a92ffce2fa5515fae960c17b03">&#9670;&#160;</a></span>aaruf_clear_drive_firmware_revision()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_drive_firmware_revision </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the drive firmware revision from the image metadata. </p>
<p>Removes the drive firmware revision string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes any record of the firmware version or revision of the drive or device used to read or write the physical storage media during the imaging process. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared drive firmware revision. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;drive_firmware_revision if not NULL and sets pointer to NULL. </dd>
<dd>
Technical Impact: Removes specific firmware behavior and capability documentation. </dd>
<dd>
Use Cases: Simplifying metadata, removing technical details, or correcting errors. </dd>
<dd>
Troubleshooting: May affect ability to diagnose firmware-specific issues. </dd>
<dd>
Reproducibility: Reduces ability to reproduce exact imaging conditions.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of firmware revision information reduces imaging environment documentation. </dd>
<dd>
Firmware versions significantly affect drive behavior and error handling. </dd>
<dd>
May affect ability to identify firmware-related imaging issues or quirks. </dd>
<dd>
Impacts scientific reproducibility and technical troubleshooting capabilities. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#adaa13a82dfc90987efd6c9a366904dc4" title="Sets the drive firmware revision for the image.">aaruf_set_drive_firmware_revision()</a> for setting drive firmware revision information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l03096">3096</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</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="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a62dc66d1bbbfacd41706bf4d87d11264" name="a62dc66d1bbbfacd41706bf4d87d11264"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a62dc66d1bbbfacd41706bf4d87d11264">&#9670;&#160;</a></span>aaruf_clear_drive_manufacturer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_drive_manufacturer </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the drive manufacturer information from the image metadata. </p>
<p>Removes the drive manufacturer name string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes any record of the company that manufactured the drive or device used to read or write the physical storage media during the imaging process. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared drive manufacturer. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;drive_manufacturer if not NULL and sets pointer to NULL. </dd>
<dd>
Provenance Impact: Removes imaging equipment context from preservation metadata. </dd>
<dd>
Use Cases: Anonymizing imaging environment, removing commercial info, or correcting errors. </dd>
<dd>
Quality Assessment: May affect ability to evaluate imaging tool quality and reliability.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of drive manufacturer information reduces imaging process documentation. </dd>
<dd>
May affect forensic provenance and imaging environment reconstruction. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a223856fa226b26c466997800183c97c4" title="Sets the drive manufacturer information for the image.">aaruf_set_drive_manufacturer()</a> for setting drive manufacturer information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02833">2833</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="context_8h_source.html#l00227">aaruformat_context::drive_manufacturer</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a43615f5e79107a192d383d230fa308e0" name="a43615f5e79107a192d383d230fa308e0"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a43615f5e79107a192d383d230fa308e0">&#9670;&#160;</a></span>aaruf_clear_drive_model()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_drive_model </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the drive model information from the image metadata. </p>
<p>Removes the drive model string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes any record of the specific model or product designation of the drive or device used to read or write the physical storage media during the imaging process. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared drive model. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;drive_model if not NULL and sets pointer to NULL. </dd>
<dd>
Technical Context: Removes specific drive capability and feature information. </dd>
<dd>
Use Cases: Anonymizing imaging equipment, simplifying metadata, or correcting errors. </dd>
<dd>
Troubleshooting: May affect ability to diagnose model-specific imaging issues.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of drive model information reduces imaging tool documentation completeness. </dd>
<dd>
May affect understanding of drive-specific capabilities or limitations. </dd>
<dd>
Important for reproducing imaging conditions or troubleshooting issues. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a29b6c38ce4b3420368ecb84007d8738d" title="Sets the drive model information for the image.">aaruf_set_drive_model()</a> for setting drive model information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02919">2919</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="context_8h_source.html#l00228">aaruformat_context::drive_model</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="aa6d7ceaf960a4e8d4494424f11815fcb" name="aa6d7ceaf960a4e8d4494424f11815fcb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa6d7ceaf960a4e8d4494424f11815fcb">&#9670;&#160;</a></span>aaruf_clear_drive_serial_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_drive_serial_number </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the drive serial number from the image metadata. </p>
<p>Removes the drive serial number string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes the unique identifier of the specific drive or device used to read or write the physical storage media during the imaging process. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared drive serial number. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;drive_serial_number if not NULL and sets pointer to NULL. </dd>
<dd>
Forensic Impact: Removes unique hardware identification from imaging provenance. </dd>
<dd>
Privacy: May be necessary for anonymizing specific equipment instances. </dd>
<dd>
Use Cases: Privacy compliance, equipment anonymization, or correcting errors. </dd>
<dd>
Equipment Tracking: Breaks correlation with equipment maintenance and calibration records.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of drive serial number eliminates unique hardware instance identification. </dd>
<dd>
May affect forensic chain of custody documentation requirements. </dd>
<dd>
Impacts ability to correlate images with specific equipment for quality analysis. </dd>
<dd>
Removes equipment tracking capability for maintenance and workload management. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#ae6b0a57476896bb90ee7bb8472e1078f" title="Sets the drive serial number for the image.">aaruf_set_drive_serial_number()</a> for setting drive serial number information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l03008">3008</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="context_8h_source.html#l00229">aaruformat_context::drive_serial_number</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a2b5ef51f1913c62139b90cae0f97a9a2" name="a2b5ef51f1913c62139b90cae0f97a9a2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2b5ef51f1913c62139b90cae0f97a9a2">&#9670;&#160;</a></span>aaruf_clear_media_barcode()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_media_barcode </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the media barcode information from the image metadata. </p>
<p>Removes the media barcode string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes any record of the barcode affixed to the physical storage media or its packaging, typically used in professional archival and library inventory systems. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared media barcode. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;media_barcode if not NULL and sets pointer to NULL. </dd>
<dd>
Inventory Impact: Removes correlation with physical media location systems. </dd>
<dd>
Use Cases: Anonymizing media, removing institutional tracking, or correcting errors. </dd>
<dd>
Archive Systems: May affect automated retrieval and inventory management.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of barcode breaks links to physical inventory and asset management systems. </dd>
<dd>
May affect robotic tape library operations and automated retrieval. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a0e5be9ff6d87218a8f5b451a27e1b39b" title="Sets the media barcode information for the image.">aaruf_set_media_barcode()</a> for setting media barcode information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02661">2661</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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="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="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a42e1c4b1876e6b28c774aae4de3c1f4e" name="a42e1c4b1876e6b28c774aae4de3c1f4e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a42e1c4b1876e6b28c774aae4de3c1f4e">&#9670;&#160;</a></span>aaruf_clear_media_manufacturer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_media_manufacturer </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the media manufacturer information from the image metadata. </p>
<p>Removes the media manufacturer name string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes any record of the company that manufactured the physical storage media. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared media manufacturer. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;media_manufacturer if not NULL and sets pointer to NULL. </dd>
<dd>
Preservation Impact: Removes valuable information about media quality and lifespan characteristics. </dd>
<dd>
Use Cases: Anonymizing media source, removing commercial information, or correcting errors.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of manufacturer information may affect preservation planning and media assessment. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#add92b8c91ede6a62dfda5f8980c3ce6d" title="Sets the media manufacturer information for the image.">aaruf_set_media_manufacturer()</a> for setting media manufacturer information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02405">2405</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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="context_8h_source.html#l00222">aaruformat_context::media_manufacturer</a>, <a class="el" href="metadata_8h_source.html#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a938d3346f5347dc152b679e6cf619d94" name="a938d3346f5347dc152b679e6cf619d94"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a938d3346f5347dc152b679e6cf619d94">&#9670;&#160;</a></span>aaruf_clear_media_model()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_media_model </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the media model or product designation from the image metadata. </p>
<p>Removes the media model string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes any record of the specific model, product line, or type designation of the physical storage media. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared media model. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;media_model if not NULL and sets pointer to NULL. </dd>
<dd>
Information Loss: Removes specific capacity, speed, and compatibility information. </dd>
<dd>
Use Cases: Removing product-specific details, generalizing metadata, or correcting errors.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of model information may affect media compatibility assessments. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a0ed36b14e49f1e924906d9c4b26d6214" title="Sets the media model or product designation for the image.">aaruf_set_media_model()</a> for setting media model information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02489">2489</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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="context_8h_source.html#l00223">aaruformat_context::media_model</a>, <a class="el" href="metadata_8h_source.html#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a8652ae4a4cdf400846621d7f497c8b60" name="a8652ae4a4cdf400846621d7f497c8b60"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8652ae4a4cdf400846621d7f497c8b60">&#9670;&#160;</a></span>aaruf_clear_media_part_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_media_part_number </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the media part number or model designation from the image metadata. </p>
<p>Removes the media part number string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes the manufacturer's part number or catalog designation used for procurement and exact product identification. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared media part number. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;media_part_number if not NULL and sets pointer to NULL. </dd>
<dd>
Procurement Impact: Removes exact ordering and catalog reference information. </dd>
<dd>
Use Cases: Removing commercial details, generalizing metadata, or correcting errors. </dd>
<dd>
Documentation: May affect ability to source compatible replacement media.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of part number affects precise product identification and procurement. </dd>
<dd>
May impact ability to cross-reference with manufacturer specifications. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#ac7c87ae51a242428ceb6d2b0a75e0b70" title="Sets the media part number or model designation for the image.">aaruf_set_media_part_number()</a> for setting media part number information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02747">2747</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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="context_8h_source.html#l00226">aaruformat_context::media_part_number</a>, <a class="el" href="metadata_8h_source.html#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a02699c3490df86f9919ac8f22f303d9e" name="a02699c3490df86f9919ac8f22f303d9e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a02699c3490df86f9919ac8f22f303d9e">&#9670;&#160;</a></span>aaruf_clear_media_sequence()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_media_sequence </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the media sequence information from the image metadata. </p>
<p>Removes the media sequence and last media sequence fields from the AaruFormat image's metadata block, effectively removing any indication that this media is part of a multi-volume set. Both the current sequence number and the total sequence count are reset to zero. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized (identifier set to 0) to avoid writing an empty metadata block to the image file.</p>
<p>This function is useful when repurposing an image that was originally part of a multi-disc set but is now being treated as standalone media, or when correcting metadata that was set incorrectly.</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, write-enabled image context).</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 cleared media sequence information. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Either the metadata block was not initialized (early exit, nothing to clear)</li>
<li>Or the mediaSequence and lastMediaSequence fields are set to 0</li>
<li>If all metadata fields are now empty, the metadata block identifier is cleared</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Metadata Block State Management:<ul>
<li>If the metadata block header is not initialized (identifier != MetadataBlock), the function returns successfully without any action (nothing to clear)</li>
<li>After clearing, if all metadata fields are empty, the metadata block header identifier is set to 0, preventing an empty block from being written</li>
<li>This automatic cleanup ensures efficient storage and avoids unnecessary blocks</li>
</ul>
</dd>
<dd>
Sequence Field Reset:<ul>
<li>Both mediaSequence and lastMediaSequence are set to 0</li>
<li>Zero values typically indicate "not part of a sequence" or "unknown sequence"</li>
<li>The function does not differentiate between never-set and explicitly-cleared</li>
</ul>
</dd>
<dd>
Use Cases:<ul>
<li>Correcting incorrectly set sequence metadata</li>
<li>Converting multi-volume images to standalone format</li>
<li>Removing obsolete sequence information during image repurposing</li>
<li>Cleaning up test or development images</li>
</ul>
</dd>
<dd>
Relationship to Other Metadata:<ul>
<li>This function only affects sequence fields; other metadata is preserved</li>
<li>Use <a class="el" href="#a10d528163caf65134a7cec4a0c0a33b8" title="Sets the media sequence information for multi-volume media sets.">aaruf_set_media_sequence()</a> to set new sequence values after clearing</li>
<li>If reconstructing multi-volume metadata, set sequence before other fields</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata changes are only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted to disk.</dd>
<dd>
After clearing, the sequence information is permanently lost unless:<ul>
<li>The image file is not closed (context remains in memory)</li>
<li>A backup of the original image exists</li>
<li>The information is reconstructed from external sources</li>
</ul>
</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a10d528163caf65134a7cec4a0c0a33b8" title="Sets the media sequence information for multi-volume media sets.">aaruf_set_media_sequence()</a> for setting sequence information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01978">1978</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a21d65b63e9806deb6dd0eb9c0e69eaf0" name="a21d65b63e9806deb6dd0eb9c0e69eaf0"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a21d65b63e9806deb6dd0eb9c0e69eaf0">&#9670;&#160;</a></span>aaruf_clear_media_serial_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_media_serial_number </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the media serial number from the image metadata. </p>
<p>Removes the media serial number string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This removes the unique identifier assigned to the specific piece of physical storage media by the manufacturer. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared media serial number. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;media_serial_number if not NULL and sets pointer to NULL. </dd>
<dd>
Forensic Impact: Removes unique identification critical for chain of custody. </dd>
<dd>
Privacy: May be necessary for anonymizing specific media instances. </dd>
<dd>
Use Cases: Privacy compliance, removing tracking identifiers, or correcting errors.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Loss of serial number eliminates unique media instance identification. </dd>
<dd>
May affect forensic chain of custody and authentication capabilities. </dd>
<dd>
Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#ad06ae4d49d6de002ef565108c73451e1" title="Sets the media serial number for the image.">aaruf_set_media_serial_number()</a> for setting media serial number information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02575">2575</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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="context_8h_source.html#l00224">aaruformat_context::media_serial_number</a>, <a class="el" href="metadata_8h_source.html#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a41bf934e213aad15df933590e6343c3e" name="a41bf934e213aad15df933590e6343c3e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a41bf934e213aad15df933590e6343c3e">&#9670;&#160;</a></span>aaruf_clear_media_title()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_clear_media_title </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clears the media title or label from the image metadata. </p>
<p>Removes the media title string from the AaruFormat image's metadata block, freeing the associated memory and resetting the length field to zero. This effectively removes any record of the title, label, or name that was printed or written on the physical storage media. If this operation results in all metadata fields being empty, the entire metadata block is deinitialized.</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, write-enabled image context).</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 cleared media title. </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. </td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Memory Management: Frees ctx-&gt;media_title if not NULL and sets pointer to NULL. </dd>
<dd>
Metadata Block: If all fields become empty, the metadata block is deinitialized. </dd>
<dd>
Use Cases: Removing physical label information, anonymizing media, or correcting errors.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Changes are only persisted during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Lost unless backed up or not closed.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a2f344544e412db0bfb46d3dfb509dd91" title="Sets the media title or label for the image.">aaruf_set_media_title()</a> for setting media title information. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l02321">2321</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="metadata_8h_source.html#l00078">MetadataBlockHeader::commentsLength</a>, <a class="el" href="metadata_8h_source.html#l00076">MetadataBlockHeader::creatorLength</a>, <a class="el" href="metadata_8h_source.html#l00098">MetadataBlockHeader::driveFirmwareRevisionLength</a>, <a class="el" href="metadata_8h_source.html#l00092">MetadataBlockHeader::driveManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00094">MetadataBlockHeader::driveModelLength</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#l00295">aaruformat_context::is_writing</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="context_8h_source.html#l00220">aaruformat_context::media_title</a>, <a class="el" href="metadata_8h_source.html#l00088">MetadataBlockHeader::mediaBarcodeLength</a>, <a class="el" href="metadata_8h_source.html#l00082">MetadataBlockHeader::mediaManufacturerLength</a>, <a class="el" href="metadata_8h_source.html#l00084">MetadataBlockHeader::mediaModelLength</a>, <a class="el" href="metadata_8h_source.html#l00090">MetadataBlockHeader::mediaPartNumberLength</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="metadata_8h_source.html#l00086">MetadataBlockHeader::mediaSerialNumberLength</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="a8090a039e00ee003569939332d21094e" name="a8090a039e00ee003569939332d21094e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8090a039e00ee003569939332d21094e">&#9670;&#160;</a></span>aaruf_set_aaru_json_metadata()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_aaru_json_metadata </td>
<td>(</td>
<td class="paramtype">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>data</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>Sets the Aaru metadata JSON for the image during creation. </p>
<p>Embeds Aaru metadata JSON into the image being created. The Aaru metadata JSON format is a structured, machine-readable representation of comprehensive image metadata including media information, imaging session details, hardware configuration, optical disc tracks and sessions, checksums, and preservation metadata. This function stores the JSON payload in its original form without parsing or validation, allowing callers to provide pre-generated JSON conforming to the Aaru metadata schema. The JSON data will be written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> as an AaruMetadataJsonBlock.</p>
<p>The function accepts raw UTF-8 encoded JSON data as an opaque byte array and creates an internal copy that persists for the lifetime of the context. If Aaru JSON metadata was previously set on this context, the old data is freed and replaced with the new JSON. The JSON is treated as opaque binary data by the library; no parsing, interpretation, or schema validation is performed during the set operation.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the Aaru metadata JSON data in UTF-8 encoding (opaque byte array). The JSON should conform to the Aaru metadata schema, though this is not validated. Must not be NULL. </td></tr>
<tr><td class="paramname">length</td><td>Length of the JSON data in bytes. The payload may or may not be null-terminated; the length should reflect the actual JSON data size.</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 set Aaru metadata JSON. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the JSON data succeeded</li>
<li>The JSON data is copied to ctx-&gt;jsonBlock</li>
<li>The jsonBlockHeader is initialized with identifier AaruMetadataJsonBlock</li>
<li>The jsonBlockHeader.length field is set to the provided length</li>
<li>Any previous Aaru JSON data is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the JSON data</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</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 must be valid UTF-8 encoded data</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 during set</li>
<li>Schema compliance is the caller's responsibility</li>
<li>Ensure the JSON conforms to the Aaru metadata schema for compatibility</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>
JSON Content Examples:<ul>
<li>Media type and physical characteristics</li>
<li>Track and session information for optical media</li>
<li>Partition and filesystem metadata</li>
<li><a class="el" href="structChecksums.html" title="Collected whole‑image checksums / hashes present in a checksum block.">Checksums</a> (MD5, SHA-1, SHA-256, etc.) for integrity verification</li>
<li>Hardware information (drive manufacturer, model, firmware)</li>
<li>Imaging software version and configuration</li>
<li>Timestamps for image creation and modification</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>The function creates an internal copy of the JSON data</li>
<li>The caller retains ownership of the input data buffer</li>
<li>The caller may free the input data immediately after this function returns</li>
<li>The internal copy is freed automatically during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a></li>
<li>Calling this function multiple times replaces previous JSON data</li>
</ul>
</dd>
<dd>
Relationship to CICM XML:<ul>
<li>Both CICM XML and Aaru JSON can be set on the same image</li>
<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>Setting one does not affect the other</li>
<li>Different tools may prefer one format over the other</li>
<li>Consider including both for maximum compatibility</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The Aaru JSON block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted to disk.</dd>
<dd>
No validation is performed on the JSON data:<ul>
<li>Invalid JSON syntax will be stored and only detected during parsing</li>
<li>Schema violations will not be caught by this function</li>
<li>Ensure JSON is valid and schema-compliant before calling</li>
<li>Use a JSON validation library before embedding if correctness is critical</li>
</ul>
</dd>
<dd>
The function accepts any length value:<ul>
<li>Ensure the length accurately reflects the JSON data size</li>
<li>Incorrect length values may cause truncation or include garbage data</li>
<li>For null-terminated JSON, length should not include the null terminator unless it is intended to be part of the stored data</li>
</ul>
</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="decls_8h.html#a01cf0abe0b137236d4be0b91a29d4818" title="Retrieves the embedded Aaru metadata JSON from the image.">aaruf_get_aaru_json_metadata()</a> for retrieving Aaru JSON from opened images. </dd>
<dd>
<a class="el" href="close__write_8c.html#ad94331170e773c67845daa357c6ecb42" title="Serialize the Aaru metadata JSON block to the image file.">write_aaru_json_block()</a> for the serialization process during image closing. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01858">1858</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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="context_8h_source.html#l00343">aaruformat_context::dirty_json_block</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#l00295">aaruformat_context::is_writing</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="ad24b15e067720825c47610e9477bfc2a" name="ad24b15e067720825c47610e9477bfc2a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad24b15e067720825c47610e9477bfc2a">&#9670;&#160;</a></span>aaruf_set_comments()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_comments </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets user comments or notes for the image. </p>
<p>Records arbitrary user-provided comments, notes, or annotations associated with the AaruFormat image. This metadata field allows users to document the image's purpose, provenance, condition, or any other relevant information. Comments are stored in UTF-16LE encoding and can contain multi-line text, special characters, and detailed descriptions.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the comments string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the comments data in bytes (must include full UTF-16LE character sequences).</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 set comments. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the comments string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The comments data is copied to ctx-&gt;imageInfo.Comments</li>
<li>The commentsLength field is set in the metadata block header</li>
<li>Any previous comments string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the comments string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>UTF-16LE Encoding:<ul>
<li>The data parameter must contain a valid UTF-16LE encoded string</li>
<li>Length must be in bytes, not character count</li>
<li>The library treats the data as opaque and does not validate encoding</li>
<li>Null termination is not required; length specifies the exact byte count</li>
</ul>
</dd>
<dd>
Common Uses for Comments:<ul>
<li>Documentation of image source and creation date</li>
<li>Notes about media condition or read errors encountered</li>
<li>Preservation metadata and archival notes</li>
<li>User annotations for organizing image collections</li>
<li>Workflow status or processing history</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>The function allocates a new buffer and copies the data</li>
<li>If previous comments exist, they are freed before replacement</li>
<li>The caller retains ownership of the input data buffer</li>
<li>The allocated memory is freed when the context is closed or destroyed</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00508">508</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="af28837461d12252d8258032e370585ae" name="af28837461d12252d8258032e370585ae"></a>
<h2 class="memtitle"><span class="permalink"><a href="#af28837461d12252d8258032e370585ae">&#9670;&#160;</a></span>aaruf_set_creator()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_creator </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the creator (person/operator) information for the image. </p>
<p>Records the name of the person or operator who created the AaruFormat image. This metadata identifies the individual responsible for the imaging process, which is valuable for provenance tracking, accountability, and understanding the human context in which the image was created. The creator name is stored in UTF-16LE encoding and preserved exactly as provided by the caller.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the creator name string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the creator data in bytes (must include full UTF-16LE character sequences).</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 set creator information. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the creator string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The creator data is copied to ctx-&gt;imageInfo.Creator</li>
<li>The creatorLength field is set in the metadata block header</li>
<li>Any previous creator string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the creator string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>UTF-16LE Encoding:<ul>
<li>The data parameter must contain a valid UTF-16LE encoded string</li>
<li>Length must be in bytes, not character count (UTF-16LE uses 2 or 4 bytes per character)</li>
<li>The library treats the data as opaque and does not validate UTF-16LE encoding</li>
<li>Null termination is not required; length specifies the exact byte count</li>
<li>Ensure even byte lengths to maintain UTF-16LE character alignment</li>
</ul>
</dd>
<dd>
Creator Name Format:<ul>
<li>Typically contains the full name of the person who created the image</li>
<li>May include titles, credentials, or institutional affiliations</li>
<li>Common formats: "John Smith", "Dr. Jane Doe", "Smith, John (Archivist)"</li>
<li>Should identify the individual operator, not the software used</li>
<li>May include contact information or employee/operator ID in institutional settings</li>
</ul>
</dd>
<dd>
Provenance and Accountability:<ul>
<li>Identifies who performed the imaging operation</li>
<li>Important for establishing chain of custody in forensic contexts</li>
<li>Provides contact point for questions about the imaging process</li>
<li>Supports institutional recordkeeping and quality assurance</li>
<li>May be required for compliance with archival standards</li>
</ul>
</dd>
<dd>
Privacy Considerations:<ul>
<li>Consider privacy implications when recording personal names</li>
<li>Some organizations may use operator IDs instead of full names</li>
<li>Institutional policies may govern what personal information is recorded</li>
<li>GDPR and similar regulations may apply in some jurisdictions</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>The function allocates a new buffer and copies the data</li>
<li>If a previous creator string exists, it is freed before replacement</li>
<li>The caller retains ownership of the input data buffer</li>
<li>The allocated memory is freed when the context is closed or destroyed</li>
</ul>
</dd>
<dd>
Metadata Block Initialization:<ul>
<li>If the metadata block header is not yet initialized, this function initializes it</li>
<li>The metadataBlockHeader.identifier is set to MetadataBlock automatically</li>
<li>Multiple metadata setter functions can be called to build complete metadata</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The data buffer must remain valid for the duration of this function call. After the function returns, the caller may free or reuse the data buffer.</dd>
<dd>
Invalid UTF-16LE encoding may cause issues when reading the metadata:<ul>
<li>The library does not validate UTF-16LE correctness</li>
<li>Malformed strings may display incorrectly or cause decoding errors</li>
<li>Ensure the data is properly encoded before calling this function</li>
</ul>
</dd>
<dd>
The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00394">394</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="adaa13a82dfc90987efd6c9a366904dc4" name="adaa13a82dfc90987efd6c9a366904dc4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#adaa13a82dfc90987efd6c9a366904dc4">&#9670;&#160;</a></span>aaruf_set_drive_firmware_revision()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_drive_firmware_revision </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the drive firmware revision for the image. </p>
<p>Records the firmware version or revision of the drive or device used to read or write the physical storage media. Firmware revisions can significantly affect drive behavior, error handling, performance, and compatibility. This metadata is crucial for understanding the imaging environment, troubleshooting issues, and ensuring reproducibility. Different firmware versions of the same drive model can behave quite differently, making this information essential for comprehensive documentation. The firmware revision is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the drive firmware revision string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the drive firmware revision data in bytes (must include full UTF-16LE character sequences).</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 set drive firmware revision. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the drive firmware revision string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The drive firmware revision data is copied to ctx-&gt;imageInfo.DriveFirmwareRevision</li>
<li>The driveFirmwareRevisionLength field is set in the metadata block header</li>
<li>Any previous drive firmware revision string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the drive firmware revision string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Firmware Revision Examples:<ul>
<li>Optical drives: "1.07", "1.00a", "VER A302"</li>
<li>Tape drives: "B8S1", "7760", "V4.0"</li>
<li>Hard drives: "CC45", "80.00A80", "HPG9"</li>
<li>Format varies by manufacturer and device type</li>
</ul>
</dd>
<dd>
Firmware Impact on Imaging:<ul>
<li>Different firmware versions may have different error recovery strategies</li>
<li>Bug fixes in newer firmware can improve read reliability</li>
<li>Some firmware versions have known issues with specific media types</li>
<li>Performance characteristics may vary between firmware revisions</li>
<li>Firmware can affect features like C2 error reporting on optical drives</li>
</ul>
</dd>
<dd>
Troubleshooting and Support:<ul>
<li>Essential for diagnosing drive-specific problems</li>
<li>Manufacturer support often requires firmware version information</li>
<li>Helps identify if issues are resolved in newer firmware</li>
<li>Enables correlation of problems with known firmware bugs</li>
<li>Supports decision-making about firmware updates</li>
</ul>
</dd>
<dd>
Reproducibility and Documentation:<ul>
<li>Complete environment documentation for scientific reproducibility</li>
<li>Important for forensic work requiring detailed equipment records</li>
<li>Helps explain variations in imaging results over time</li>
<li>Supports compliance with archival and preservation standards</li>
<li>Enables future researchers to understand imaging conditions</li>
</ul>
</dd>
<dd>
Historical Tracking:<ul>
<li>Documents firmware changes over the life of imaging equipment</li>
<li>Helps assess impact of firmware updates on imaging quality</li>
<li>Useful for long-term archival projects spanning years</li>
<li>Aids in understanding evolution of drive technology</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted.</dd>
<dd>
Firmware revisions are device-specific and format varies widely:<ul>
<li>No standard format exists across manufacturers</li>
<li>May include letters, numbers, dots, or other characters</li>
<li>Should be recorded exactly as reported by the device </li>
</ul>
</dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01695">1695</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="a223856fa226b26c466997800183c97c4" name="a223856fa226b26c466997800183c97c4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a223856fa226b26c466997800183c97c4">&#9670;&#160;</a></span>aaruf_set_drive_manufacturer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_drive_manufacturer </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the drive manufacturer information for the image. </p>
<p>Records the name of the company that manufactured the drive or device used to read or write the physical storage media. This metadata provides valuable context about the imaging process, as different drives may have different capabilities, error handling characteristics, and compatibility with specific media types. The manufacturer name is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the drive manufacturer string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the drive manufacturer data in bytes (must include full UTF-16LE character sequences).</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 set drive manufacturer. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the drive manufacturer string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The drive manufacturer data is copied to ctx-&gt;imageInfo.DriveManufacturer</li>
<li>The driveManufacturerLength field is set in the metadata block header</li>
<li>Any previous drive manufacturer string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the drive manufacturer string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Common Drive Manufacturers:<ul>
<li>Optical drives: Pioneer, Plextor, LG, ASUS, Sony, Samsung</li>
<li>Tape drives: HP, IBM, Quantum, Tandberg, Exabyte</li>
<li>Hard drives: Seagate, Western Digital, Hitachi, Toshiba</li>
<li>Floppy drives: Teac, Panasonic, Mitsumi, Sony</li>
</ul>
</dd>
<dd>
Imaging Context and Quality:<ul>
<li>Different manufacturers have varying error recovery capabilities</li>
<li>Some drives are better suited for archival-quality imaging</li>
<li>Plextor drives were historically preferred for optical disc preservation</li>
<li>Professional-grade drives often have better read accuracy</li>
<li>Important for understanding potential limitations in the imaging process</li>
</ul>
</dd>
<dd>
Forensic and Provenance Value:<ul>
<li>Documents the complete imaging environment</li>
<li>Helps assess reliability and trustworthiness of the image</li>
<li>Useful for troubleshooting or reproducing imaging results</li>
<li>May be required for forensic chain of custody</li>
<li>Supports quality assurance and validation processes</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01314">1314</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="a29b6c38ce4b3420368ecb84007d8738d" name="a29b6c38ce4b3420368ecb84007d8738d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a29b6c38ce4b3420368ecb84007d8738d">&#9670;&#160;</a></span>aaruf_set_drive_model()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_drive_model </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the drive model information for the image. </p>
<p>Records the specific model or product designation of the drive or device used to read or write the physical storage media. This metadata provides detailed information about the imaging equipment, which can be important for understanding the capabilities, limitations, and characteristics of the imaging process. Different drive models within the same manufacturer's product line may have significantly different features and performance characteristics. The model information is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the drive model string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the drive model data in bytes (must include full UTF-16LE character sequences).</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 set drive model. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the drive model string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The drive model data is copied to ctx-&gt;imageInfo.DriveModel</li>
<li>The driveModelLength field is set in the metadata block header</li>
<li>Any previous drive model string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the drive model string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Drive Model Examples:<ul>
<li>Optical drives: "DVR-111D" (Pioneer), "PX-716A" (Plextor), "GH24NSB0" (LG)</li>
<li>Tape drives: "Ultrium 7-SCSI" (HP), "TS1140" (IBM), "SDLT600" (Quantum)</li>
<li>Hard drives: "ST2000DM008" (Seagate), "WD40EZRZ" (Western Digital)</li>
<li>Floppy drives: "FD-235HF" (Teac), "JU-257A633P" (Panasonic)</li>
</ul>
</dd>
<dd>
Model-Specific Characteristics:<ul>
<li>Different models may have different error correction algorithms</li>
<li>Some models are known for superior read quality (e.g., Plextor Premium)</li>
<li>Certain models may have bugs or quirks in specific firmware versions</li>
<li>Professional models often have features not available in consumer versions</li>
<li>Important for reproducing imaging conditions or troubleshooting issues</li>
</ul>
</dd>
<dd>
Forensic Documentation:<ul>
<li>Complete drive identification aids in forensic reporting</li>
<li>Helps establish the reliability of the imaging process</li>
<li>May be required for compliance with forensic standards</li>
<li>Supports validation and verification procedures</li>
<li>Enables assessment of tool suitability for the imaging task</li>
</ul>
</dd>
<dd>
Historical and Research Value:<ul>
<li>Documents evolution of imaging technology over time</li>
<li>Helps identify best practices for specific media types</li>
<li>Useful for academic research on digital preservation</li>
<li>Aids in understanding drive availability and obsolescence</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01436">1436</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="ae6b0a57476896bb90ee7bb8472e1078f" name="ae6b0a57476896bb90ee7bb8472e1078f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae6b0a57476896bb90ee7bb8472e1078f">&#9670;&#160;</a></span>aaruf_set_drive_serial_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_drive_serial_number </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the drive serial number for the image. </p>
<p>Records the unique serial number of the drive or device used to read or write the physical storage media. This metadata provides a unique identifier for the specific piece of hardware used in the imaging process, which is particularly important for forensic work, equipment tracking, and quality assurance. The serial number enables correlation between multiple images created with the same drive and can help identify drive-specific issues or characteristics. The serial number is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the drive serial number string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the drive serial number data in bytes (must include full UTF-16LE character sequences).</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 set drive serial number. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the drive serial number string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The drive serial number data is copied to ctx-&gt;imageInfo.DriveSerialNumber</li>
<li>The driveSerialNumberLength field is set in the metadata block header</li>
<li>Any previous drive serial number string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the drive serial number string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Serial Number Sources:<ul>
<li>Hard drives and SSDs: Retrieved via ATA/SCSI IDENTIFY commands</li>
<li>Optical drives: Available through SCSI inquiry or ATA identify</li>
<li>Tape drives: Typically reported via SCSI inquiry data</li>
<li>USB devices: May have USB serial numbers or internal device serials</li>
<li>Some older or consumer devices may not report serial numbers</li>
</ul>
</dd>
<dd>
Forensic Applications:<ul>
<li>Critical for forensic chain of custody documentation</li>
<li>Uniquely identifies the specific hardware used for imaging</li>
<li>Enables tracking of drive calibration and maintenance history</li>
<li>Supports correlation of images created with the same equipment</li>
<li>May be required by forensic standards and best practices</li>
</ul>
</dd>
<dd>
Equipment Management:<ul>
<li>Helps track drive usage and workload for maintenance planning</li>
<li>Enables identification of drives requiring replacement or service</li>
<li>Supports equipment inventory and asset management systems</li>
<li>Useful for identifying drives with known issues or recalls</li>
<li>Facilitates warranty and support claim processing</li>
</ul>
</dd>
<dd>
Quality Assurance:<ul>
<li>Enables analysis of drive-specific error patterns</li>
<li>Helps identify if multiple imaging issues stem from the same drive</li>
<li>Supports statistical quality control processes</li>
<li>Aids in evaluating drive reliability over time</li>
<li>Can reveal degradation or calibration drift in aging hardware</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01560">1560</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="ad0b5b12288f159780d065b12ba12bdcc" name="ad0b5b12288f159780d065b12ba12bdcc"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad0b5b12288f159780d065b12ba12bdcc">&#9670;&#160;</a></span>aaruf_set_geometry()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_geometry </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const 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">const 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">const uint32_t</td> <td class="paramname"><span class="paramname"><em>sectors_per_track</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the logical CHS geometry for the AaruFormat image. </p>
<p>Configures the Cylinder-Head-Sector (CHS) geometry information for the image being created or modified. This function populates both the geometry block (used for storage in the image file) and the image information structure (used for runtime calculations). The geometry block contains legacy-style logical addressing parameters that describe how the storage medium should be logically organized in terms of cylinders, heads (tracks per cylinder), and sectors per track. This information is crucial for creating images that will be used with software requiring CHS addressing or for accurately preserving 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, write-enabled image context). </td></tr>
<tr><td class="paramname">cylinders</td><td>The number of cylinders to set for the geometry. </td></tr>
<tr><td class="paramname">heads</td><td>The number of heads (tracks per cylinder) to set for the geometry. </td></tr>
<tr><td class="paramname">sectors_per_track</td><td>The number of sectors per track to set for the geometry.</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 set geometry information. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>The geometry block identifier is set to GeometryBlock</li>
<li>The geometry block fields (cylinders, heads, sectorsPerTrack) are updated</li>
<li>The image info fields (Cylinders, Heads, SectorsPerTrack) are synchronized</li>
<li>All parameters are stored for subsequent write operations</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Dual Storage:<ul>
<li>Geometry is stored in two locations within the context:<ol type="1">
<li>ctx-&gt;geometryBlock: Written to the image file as a GeometryBlock during close</li>
<li>ctx-&gt;imageInfo: Used for runtime calculations and metadata queries</li>
</ol>
</li>
<li>Both locations are kept synchronized by this function</li>
</ul>
</dd>
<dd>
Geometry Calculation:<ul>
<li>Total logical sectors = cylinders × heads × sectors_per_track</li>
<li>Ensure the product matches the actual sector count in the image</li>
<li>Mismatched geometry may cause issues with legacy software or emulators</li>
<li>Sector size is separate and should be set via other API calls</li>
</ul>
</dd>
<dd>
CHS Addressing Requirements:<ul>
<li>Required for images intended for legacy BIOS or MBR partition schemes</li>
<li>Essential for floppy disk images and older hard disk images</li>
<li>May be optional or synthetic for modern large-capacity drives</li>
<li>Some virtualization platforms require valid CHS geometry</li>
</ul>
</dd>
<dd>
Parameter Constraints:<ul>
<li>No validation is performed on the geometry values</li>
<li>Zero values are technically accepted but may cause issues</li>
<li>Extremely large values may overflow in calculations (cylinders × heads × sectors_per_track)</li>
<li>Common constraints for legacy systems:<ul>
<li>Cylinders: typically 1-1024 for BIOS, up to 65535 for modern systems</li>
<li>Heads: typically 1-255 for most systems</li>
<li>Sectors per track: typically 1-63 for BIOS, up to 255 for modern systems</li>
</ul>
</li>
</ul>
</dd>
<dd>
Write Mode Requirement:<ul>
<li>This function is intended for use during image creation</li>
<li>Should be called after <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a> and before writing sector data</li>
<li>The geometry block is serialized during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a></li>
<li>Must be used with a write-enabled context</li>
</ul>
</dd>
<dd>
Historical Context:<ul>
<li>CHS geometry was the original addressing scheme for disk drives</li>
<li>Physical CHS reflected actual disk platters, heads, and sector layout</li>
<li>Logical CHS often differs from physical due to zone-bit recording and translation</li>
<li>Modern drives use LBA (Logical Block Addressing) internally</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>This function does not validate geometry consistency:<ul>
<li>Does not check if cylinders × heads × sectors_per_track equals image sector count</li>
<li>Does not prevent overflow in the multiplication</li>
<li>Caller must ensure geometry values are appropriate for the medium type</li>
<li>Invalid geometry may cause boot failures or data access issues</li>
</ul>
</dd>
<dd>
The geometry block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted.</dd>
<dd>
Changing geometry after writing sector data may create inconsistencies. Set geometry before beginning sector write operations for best results.</dd>
<dd>
Some image formats and use cases don't require CHS geometry:<ul>
<li>Optical media (CD/DVD/BD) use different addressing schemes</li>
<li>Modern GPT-partitioned disks don't rely on CHS</li>
<li>Flash-based storage typically doesn't have meaningful CHS geometry</li>
<li>Setting geometry for such media types is harmless but unnecessary </li>
</ul>
</dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00128">128</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00237">aaruformat_context::cylinders</a>, <a class="el" href="data_8h_source.html#l00093">GeometryBlockHeader::cylinders</a>, <a class="el" href="context_8h_source.html#l00339">aaruformat_context::dirty_geometry_block</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="context_8h_source.html#l00238">aaruformat_context::heads</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#l00295">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00239">aaruformat_context::sectors_per_track</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="a0e5be9ff6d87218a8f5b451a27e1b39b" name="a0e5be9ff6d87218a8f5b451a27e1b39b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a0e5be9ff6d87218a8f5b451a27e1b39b">&#9670;&#160;</a></span>aaruf_set_media_barcode()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_media_barcode </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the media barcode information for the image. </p>
<p>Records the barcode affixed to the physical storage media or its packaging. Barcodes are commonly used in professional archival and library environments for automated inventory management, tracking, and retrieval systems. This metadata enables correlation between physical media location systems and digital image files. The barcode is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the media barcode string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the media barcode data in bytes (must include full UTF-16LE character sequences).</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 set media barcode. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the media barcode string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The media barcode data is copied to ctx-&gt;imageInfo.MediaBarcode</li>
<li>The mediaBarcodeLength field is set in the metadata block header</li>
<li>Any previous media barcode string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the media barcode string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Common Barcode Uses:<ul>
<li>Library and archival tape management systems</li>
<li>Automated tape library robotics (e.g., LTO tape cartridges)</li>
<li>Inventory tracking in large media collections</li>
<li>Asset management in corporate or institutional settings</li>
<li>Chain of custody tracking in forensic environments</li>
</ul>
</dd>
<dd>
Barcode Types and Formats:<ul>
<li>Code 39 and Code 128 are common for media labeling</li>
<li>LTO tapes use specific 6 or 8-character barcode formats</li>
<li>May include library-specific prefixes or location codes</li>
<li>Some systems use 2D barcodes (QR codes, Data Matrix)</li>
<li>Barcode should be recorded exactly as it appears</li>
</ul>
</dd>
<dd>
Integration with Physical Systems:<ul>
<li>Enables automated correlation between physical and digital catalogs</li>
<li>Supports robotic tape library operations</li>
<li>Facilitates retrieval from off-site storage facilities</li>
<li>Links to broader asset management databases</li>
<li>Critical for large-scale archival operations</li>
</ul>
</dd>
<dd>
Preservation Context:<ul>
<li>Important for long-term archival planning</li>
<li>Helps maintain inventory accuracy over time</li>
<li>Supports audit and compliance requirements</li>
<li>Enables efficient physical media location and retrieval</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01078">1078</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="add92b8c91ede6a62dfda5f8980c3ce6d" name="add92b8c91ede6a62dfda5f8980c3ce6d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#add92b8c91ede6a62dfda5f8980c3ce6d">&#9670;&#160;</a></span>aaruf_set_media_manufacturer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_media_manufacturer </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the media manufacturer information for the image. </p>
<p>Records the name of the company that manufactured the physical storage media. This metadata is valuable for preservation and forensic purposes, as it can help identify the media type, quality characteristics, and manufacturing period. The manufacturer name is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the media manufacturer string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the media manufacturer data in bytes (must include full UTF-16LE character sequences).</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 set media manufacturer. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the media manufacturer string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The media manufacturer data is copied to ctx-&gt;imageInfo.MediaManufacturer</li>
<li>The mediaManufacturerLength field is set in the metadata block header</li>
<li>Any previous media manufacturer string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the media manufacturer string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Common Media Manufacturers:<ul>
<li>Optical discs: Verbatim, Sony, Maxell, TDK, Taiyo Yuden</li>
<li>Magnetic tapes: Fujifilm, Maxell, Sony, IBM</li>
<li>Floppy disks: 3M, Maxell, Sony, Verbatim</li>
<li>Flash media: SanDisk, Kingston, Samsung</li>
</ul>
</dd>
<dd>
Identification Methods:<ul>
<li>May be printed on the media surface or packaging</li>
<li>Can sometimes be detected from media ID codes (e.g., ATIP for CD-R)</li>
<li>Historical records or catalogs may provide this information</li>
<li>Important for understanding media quality and longevity characteristics</li>
</ul>
</dd>
<dd>
Preservation Value:<ul>
<li>Helps assess expected media lifespan and degradation patterns</li>
<li>Useful for identifying counterfeit or remarked media</li>
<li>Aids in research about media quality and failure modes</li>
<li>Provides context for archival planning and migration strategies</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00734">734</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="a0ed36b14e49f1e924906d9c4b26d6214" name="a0ed36b14e49f1e924906d9c4b26d6214"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a0ed36b14e49f1e924906d9c4b26d6214">&#9670;&#160;</a></span>aaruf_set_media_model()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_media_model </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the media model or product designation for the image. </p>
<p>Records the specific model, product line, or type designation of the physical storage media. This is more specific than the manufacturer and identifies the exact product variant. This metadata helps in identifying specific media characteristics, performance specifications, and compatibility information. The model information is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the media model string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the media model data in bytes (must include full UTF-16LE character sequences).</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 set media model. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the media model string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The media model data is copied to ctx-&gt;imageInfo.MediaModel</li>
<li>The mediaModelLength field is set in the metadata block header</li>
<li>Any previous media model string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the media model string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Model Designation Examples:<ul>
<li>Optical discs: "DVD+R 16x", "CD-R 80min", "BD-R DL 50GB"</li>
<li>Tapes: "LTO-7", "DLT-IV", "AIT-3"</li>
<li>Floppy disks: "HD 1.44MB", "DD 720KB"</li>
<li>Flash cards: "SDHC Class 10", "CompactFlash 1000x"</li>
</ul>
</dd>
<dd>
Model Information Usage:<ul>
<li>Identifies specific capacity and speed ratings</li>
<li>Indicates format compatibility (e.g., DVD-R vs DVD+R)</li>
<li>Helps determine recording characteristics and quality tier</li>
<li>Useful for matching replacement media or troubleshooting issues</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00841">841</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="ac7c87ae51a242428ceb6d2b0a75e0b70" name="ac7c87ae51a242428ceb6d2b0a75e0b70"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac7c87ae51a242428ceb6d2b0a75e0b70">&#9670;&#160;</a></span>aaruf_set_media_part_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_media_part_number </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the media part number or model designation for the image. </p>
<p>Records the manufacturer's part number or catalog designation for the specific type of physical storage media. This is distinct from the media model in that it represents the exact ordering or catalog number used for procurement and inventory purposes. Part numbers are particularly important for sourcing compatible replacement media and for precise identification in technical documentation. The part number is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the media part number string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the media part number data in bytes (must include full UTF-16LE character sequences).</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 set media part number. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the media part number string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The media part number data is copied to ctx-&gt;imageInfo.MediaPartNumber</li>
<li>The mediaPartNumberLength field is set in the metadata block header</li>
<li>Any previous media part number string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the media part number string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Part Number Examples:<ul>
<li>Optical media: "MR-25332" (Verbatim DVD+R), "CDR80JC" (Sony CD-R)</li>
<li>Tape media: "C7973A" (HP LTO-3), "TK88" (Maxell DLT-IV)</li>
<li>Floppy disks: "MF2HD" (3.5" high-density), "2D" (5.25" double-density)</li>
<li>May include regional variations or packaging size indicators</li>
</ul>
</dd>
<dd>
Practical Applications:<ul>
<li>Procurement and ordering of compatible replacement media</li>
<li>Cross-referencing with manufacturer specifications and datasheets</li>
<li>Identifying specific product revisions or manufacturing batches</li>
<li>Ensuring compatibility for archival media migration projects</li>
<li>Tracking costs and suppliers in institutional settings</li>
</ul>
</dd>
<dd>
Relationship to Model:<ul>
<li>Part number is more specific than model designation</li>
<li>Model might be "DVD+R 16x", part number "MR-25332"</li>
<li>Part numbers may vary by region, packaging quantity, or color</li>
<li>Critical for exact product identification in catalogs and databases</li>
</ul>
</dd>
<dd>
Documentation and Compliance:<ul>
<li>Useful for creating detailed preservation documentation</li>
<li>Supports compliance with archival standards and best practices</li>
<li>Enables precise replication of archival environments</li>
<li>Facilitates research on media types and failure modes</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l01199">1199</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="a10d528163caf65134a7cec4a0c0a33b8" name="a10d528163caf65134a7cec4a0c0a33b8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a10d528163caf65134a7cec4a0c0a33b8">&#9670;&#160;</a></span>aaruf_set_media_sequence()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_media_sequence </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const 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">const int32_t</td> <td class="paramname"><span class="paramname"><em>last_sequence</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the media sequence information for multi-volume media sets. </p>
<p>Configures the sequence numbering for media that is part of a larger set, such as multi-disk software distributions, backup sets spanning multiple tapes, or optical disc sets. This function records both the current media's position in the sequence and the total number of media in the complete set. This metadata is essential for proper ordering and completeness verification when working with multi-volume archives.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">sequence</td><td>The sequence number of this media (1-based index indicating position in the set). </td></tr>
<tr><td class="paramname">last_sequence</td><td>The total number of media in the complete set (indicates the final sequence number).</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 set media sequence information. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The mediaSequence field is set to the provided sequence value</li>
<li>The lastMediaSequence field is set to the provided last_sequence value</li>
<li>Both values are stored for serialization during image close</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Sequence Numbering:<ul>
<li>Sequence numbers are typically 1-based (first disc is 1, not 0)</li>
<li>The sequence parameter should be in the range [1, last_sequence]</li>
<li>last_sequence indicates the total count of media in the set</li>
<li>Example: For a 3-disc set, disc 2 would have sequence=2, last_sequence=3</li>
</ul>
</dd>
<dd>
Common Use Cases:<ul>
<li>Multi-CD/DVD software installations (e.g., "Disc 2 of 4")</li>
<li>Backup tape sets spanning multiple volumes</li>
<li>Split archive formats requiring sequential processing</li>
<li>Multi-floppy disk software distributions</li>
<li>Large data sets divided across multiple optical discs</li>
</ul>
</dd>
<dd>
Metadata Block Initialization:<ul>
<li>If the metadata block header is not yet initialized, this function initializes it</li>
<li>The metadataBlockHeader.identifier is set to MetadataBlock automatically</li>
<li>Multiple metadata setter functions can be called to build complete metadata</li>
<li>All metadata is written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a></li>
</ul>
</dd>
<dd>
Single Media Images:<ul>
<li>For standalone media not part of a set, use sequence=1, last_sequence=1</li>
<li>Setting both values to 0 may be used to indicate "not part of a sequence"</li>
<li>The function does not validate that sequence &lt;= last_sequence</li>
</ul>
</dd>
<dd>
Parameter Validation:<ul>
<li>No validation is performed on sequence numbers</li>
<li>Negative values are accepted but may be semantically incorrect</li>
<li>sequence &gt; last_sequence is not prevented but indicates an error condition</li>
<li>Callers should ensure sequence and last_sequence are logically consistent</li>
</ul>
</dd>
<dd>
Archive Integrity:<ul>
<li>Proper sequence metadata is crucial for multi-volume restoration</li>
<li>Archival software may refuse to extract if sequence information is incorrect</li>
<li>Missing volumes can be detected by checking sequence completeness</li>
<li>Helps prevent data loss from incomplete multi-volume sets</li>
</ul>
</dd>
<dd>
Historical Context:<ul>
<li>Multi-volume sets were common in the floppy disk era due to size constraints</li>
<li>CD/DVD sets were used for large software distributions (operating systems, games)</li>
<li>Tape backup systems still use multi-volume sets for large archives</li>
<li>Modern optical media (BD-R DL) reduced the need for multi-disc sets</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>This function does not validate the logical consistency of sequence numbers:<ul>
<li>Does not check if sequence &lt;= last_sequence</li>
<li>Does not prevent negative or zero values if semantically inappropriate</li>
<li>Caller must ensure values represent a valid sequence relationship</li>
</ul>
</dd>
<dd>
The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted.</dd>
<dd>
Incorrect sequence information may prevent proper reconstruction:<ul>
<li>Software relying on sequence numbers may fail to recognize media order</li>
<li>Archival systems may incorrectly report missing volumes</li>
<li>Restoration processes may fail if sequence is inconsistent </li>
</ul>
</dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00263">263</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="ad06ae4d49d6de002ef565108c73451e1" name="ad06ae4d49d6de002ef565108c73451e1"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad06ae4d49d6de002ef565108c73451e1">&#9670;&#160;</a></span>aaruf_set_media_serial_number()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_media_serial_number </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the media serial number for the image. </p>
<p>Records the unique serial number assigned to the physical storage media by the manufacturer. This metadata provides a unique identifier for the specific piece of media, which is invaluable for tracking, authentication, and forensic analysis. Not all media types have serial numbers; this is most common with professional-grade media and some consumer optical discs. The serial number is stored in UTF-16LE encoding.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the media serial number string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the media serial number data in bytes (must include full UTF-16LE character sequences).</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 set media serial number. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the media serial number string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The media serial number data is copied to ctx-&gt;imageInfo.MediaSerialNumber</li>
<li>The mediaSerialNumberLength field is set in the metadata block header</li>
<li>Any previous media serial number string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the media serial number string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Serial Number Availability:<ul>
<li>Professional tape media (LTO, DLT, etc.) typically have printed serial numbers</li>
<li>Some optical discs have embedded media IDs that can serve as serial numbers</li>
<li>Hard drives and SSDs have electronically-readable serial numbers</li>
<li>Consumer recordable media (CD-R, DVD-R) rarely have unique serial numbers</li>
<li>May be printed on labels, hubs, or cartridge shells</li>
</ul>
</dd>
<dd>
Forensic and Archival Importance:<ul>
<li>Uniquely identifies the specific physical media instance</li>
<li>Critical for chain of custody in forensic investigations</li>
<li>Enables tracking of media throughout its lifecycle</li>
<li>Helps prevent mix-ups in large media collections</li>
<li>Can verify authenticity and detect counterfeits</li>
</ul>
</dd>
<dd>
Format Considerations:<ul>
<li>Serial numbers may be alphanumeric, numeric, or contain special characters</li>
<li>Format varies widely between manufacturers and media types</li>
<li>May include check digits or formatting separators</li>
<li>Should be recorded exactly as it appears on the media</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00956">956</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</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#l00295">aaruformat_context::is_writing</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="a2f344544e412db0bfb46d3dfb509dd91" name="a2f344544e412db0bfb46d3dfb509dd91"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2f344544e412db0bfb46d3dfb509dd91">&#9670;&#160;</a></span>aaruf_set_media_title()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_set_media_title </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the media title or label for the image. </p>
<p>Records the title, label, or name printed or written on the physical storage media. This metadata is particularly useful for identifying discs, tapes, or other media that have user-applied labels or manufacturer-printed titles. The title is stored in UTF-16LE encoding to support international characters and special symbols.</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, write-enabled image context). </td></tr>
<tr><td class="paramname">data</td><td>Pointer to the media title string data in UTF-16LE encoding (opaque byte array). </td></tr>
<tr><td class="paramname">length</td><td>Length of the media title data in bytes (must include full UTF-16LE character sequences).</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 set media title. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx-&gt;isWriting is true)</li>
<li>Memory allocation for the media title string succeeded</li>
<li>The metadata block header is initialized (identifier set to MetadataBlock)</li>
<li>The media title data is copied to ctx-&gt;imageInfo.MediaTitle</li>
<li>The mediaTitleLength field is set in the metadata block header</li>
<li>Any previous media title string is properly freed before replacement</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#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#a1df49eaa19eaa14891b6aaab966a9bc6" title="Operation requires write mode but context is read-only.">AARUF_READ_ONLY</a></td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#a5cea94dcb9c08a646f7f7160ec8418de" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
</td></tr>
<tr><td class="paramname"><a class="el" href="errors_8h.html#a35a771e3648bf971a004d4b2be9b5ec4" title="Memory allocation failure (critical).">AARUF_ERROR_NOT_ENOUGH_MEMORY</a></td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>malloc() failed to allocate the required memory for the media title string</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>The requested allocation size is too large</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Common Media Title Examples:<ul>
<li>Handwritten labels on optical discs or tapes</li>
<li>Pre-printed software names on distribution media (e.g., "Windows 95 Setup Disk 1")</li>
<li>Volume labels or disc names (e.g., "BACKUP_2024", "INSTALL_CD")</li>
<li>Game titles printed on cartridges or discs</li>
<li>Album or movie titles on multimedia discs</li>
</ul>
</dd>
<dd>
Preservation Context:<ul>
<li>Important for archival purposes to record exactly what appears on the media</li>
<li>Helps identify media in large collections</li>
<li>May differ from filesystem volume labels</li>
<li>Useful for matching physical media to digital images</li>
</ul>
</dd>
<dd>
UTF-16LE Encoding:<ul>
<li>The data parameter must contain a valid UTF-16LE encoded string</li>
<li>Length must be in bytes, not character count</li>
<li>Supports international characters, emoji, and special symbols</li>
<li>Null termination is not required; length specifies the exact byte count</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The metadata block is only written to the image file during <a class="el" href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="metadata__write_8c_source.html#l00621">621</a> of file <a class="el" href="metadata__write_8c_source.html">metadata_write.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#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00081">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00340">aaruformat_context::dirty_metadata_block</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#l00295">aaruformat_context::is_writing</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>
</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__write_8c.html">metadata_write.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