mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 19:24:40 +00:00
8859 lines
721 KiB
HTML
8859 lines
721 KiB
HTML
<!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.14.0"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>libaaruformat: include/aaruformat/decls.h 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"> 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.14.0 -->
|
||
<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('decls_8h.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">decls.h File Reference</div></div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><code>#include "<a class="el" href="aaru_8h_source.html">aaru.h</a>"</code><br />
|
||
<code>#include "<a class="el" href="crc64_8h_source.html">crc64.h</a>"</code><br />
|
||
<code>#include "<a class="el" href="md5_8h_source.html">md5.h</a>"</code><br />
|
||
<code>#include "<a class="el" href="sha1_8h_source.html">sha1.h</a>"</code><br />
|
||
<code>#include "<a class="el" href="sha256_8h_source.html">sha256.h</a>"</code><br />
|
||
<code>#include "<a class="el" href="simd_8h_source.html">simd.h</a>"</code><br />
|
||
<code>#include "<a class="el" href="spamsum_8h_source.html">spamsum.h</a>"</code><br />
|
||
<code>#include "<a class="el" href="optical_8h_source.html">structs/optical.h</a>"</code><br />
|
||
</div>
|
||
<p><a href="decls_8h_source.html">Go to the source code of this file.</a></p>
|
||
<table class="memberdecls">
|
||
<tr class="heading"><td colspan="2"><h2 id="header-define-members" class="groupheader"><a id="define-members" name="define-members"></a>
|
||
Macros</h2></td></tr>
|
||
<tr class="memitem:a95e1d92b2619a326b2e86600f3d23100" id="r_a95e1d92b2619a326b2e86600f3d23100"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="#a95e1d92b2619a326b2e86600f3d23100">EXTERNC</a></td></tr>
|
||
<tr class="memitem:a018e0da1c1f7e4f6187a982c0e40e056" id="r_a018e0da1c1f7e4f6187a982c0e40e056"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="#a018e0da1c1f7e4f6187a982c0e40e056">AARU_CALL</a></td></tr>
|
||
<tr class="memitem:a9001412c35f3c92d3a9320d27b0d97f9" id="r_a9001412c35f3c92d3a9320d27b0d97f9"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="#a9001412c35f3c92d3a9320d27b0d97f9">AARU_EXPORT</a>   <a class="el" href="#a95e1d92b2619a326b2e86600f3d23100">EXTERNC</a></td></tr>
|
||
<tr class="memitem:a8a7eac34f7a0caaa0d4a57e9627ba173" id="r_a8a7eac34f7a0caaa0d4a57e9627ba173"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="#a8a7eac34f7a0caaa0d4a57e9627ba173">AARU_LOCAL</a></td></tr>
|
||
<tr class="memitem:ac032d233a8ebfcd82fd49d0824eefb18" id="r_ac032d233a8ebfcd82fd49d0824eefb18"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="#ac032d233a8ebfcd82fd49d0824eefb18">FORCE_INLINE</a>   static inline <a class="el" href="lru_8c.html#a8c8313d05785802938c6d8a2a7fa3e09">__attribute__</a>((always_inline))</td></tr>
|
||
</table><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:a74c444fbd394f58aefd2fabff221231b" id="r_a74c444fbd394f58aefd2fabff221231b"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#a74c444fbd394f58aefd2fabff221231b">aaruf_identify</a> (const char *filename)</td></tr>
|
||
<tr class="memdesc:a74c444fbd394f58aefd2fabff221231b"><td class="mdescLeft"> </td><td class="mdescRight">Identifies a file as an AaruFormat image using a file path. <br /></td></tr>
|
||
<tr class="memitem:a6f30353aff3ece1e889542c26f7146e2" id="r_a6f30353aff3ece1e889542c26f7146e2"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#a6f30353aff3ece1e889542c26f7146e2">aaruf_identify_stream</a> (FILE *image_stream)</td></tr>
|
||
<tr class="memdesc:a6f30353aff3ece1e889542c26f7146e2"><td class="mdescLeft"> </td><td class="mdescRight">Identifies a file as an AaruFormat image using an open stream. <br /></td></tr>
|
||
<tr class="memitem:afc4932cdc795ffb2ef3a33d5b8c57656" id="r_afc4932cdc795ffb2ef3a33d5b8c57656"><td class="memItemLeft" align="right" valign="top">void * </td><td class="memItemRight" valign="bottom"><a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656">aaruf_open</a> (const char *filepath)</td></tr>
|
||
<tr class="memdesc:afc4932cdc795ffb2ef3a33d5b8c57656"><td class="mdescLeft"> </td><td class="mdescRight">Opens an existing AaruFormat image file. <br /></td></tr>
|
||
<tr class="memitem:a7065a9fefcaabfecc4184528f01ef013" id="r_a7065a9fefcaabfecc4184528f01ef013"><td class="memItemLeft" align="right" valign="top">void * </td><td class="memItemRight" valign="bottom"><a class="el" href="#a7065a9fefcaabfecc4184528f01ef013">aaruf_create</a> (const char *filepath, uint32_t media_type, uint32_t sector_size, uint64_t user_sectors, uint64_t negative_sectors, uint64_t overflow_sectors, const char *options, const uint8_t *application_name, uint8_t application_name_length, uint8_t application_major_version, uint8_t application_minor_version, bool is_tape)</td></tr>
|
||
<tr class="memdesc:a7065a9fefcaabfecc4184528f01ef013"><td class="mdescLeft"> </td><td class="mdescRight">Creates a new AaruFormat image file. <br /></td></tr>
|
||
<tr class="memitem:a6823e139f81a9dfd08efcb0e9b213a49" id="r_a6823e139f81a9dfd08efcb0e9b213a49"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49">aaruf_close</a> (void *context)</td></tr>
|
||
<tr class="memdesc:a6823e139f81a9dfd08efcb0e9b213a49"><td class="mdescLeft"> </td><td class="mdescRight">Close an Aaru image context, flushing pending data structures and releasing resources. <br /></td></tr>
|
||
<tr class="memitem:a48f93ec154d0aed7cb713391a7717b46" id="r_a48f93ec154d0aed7cb713391a7717b46"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a48f93ec154d0aed7cb713391a7717b46">aaruf_read_media_tag</a> (void *context, uint8_t *data, int32_t tag, uint32_t *length)</td></tr>
|
||
<tr class="memdesc:a48f93ec154d0aed7cb713391a7717b46"><td class="mdescLeft"> </td><td class="mdescRight">Reads a media tag from the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a66567ca64e31a687d4982cb254b45196" id="r_a66567ca64e31a687d4982cb254b45196"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structcrc64__ctx.html">crc64_ctx</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="#a66567ca64e31a687d4982cb254b45196">aaruf_crc64_init</a> ()</td></tr>
|
||
<tr class="memdesc:a66567ca64e31a687d4982cb254b45196"><td class="mdescLeft"> </td><td class="mdescRight">Initializes a CRC64 context. <br /></td></tr>
|
||
<tr class="memitem:a1fb4423a841ccd728e3ad0d028cbc9b4" id="r_a1fb4423a841ccd728e3ad0d028cbc9b4"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#a1fb4423a841ccd728e3ad0d028cbc9b4">aaruf_crc64_update</a> (<a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *ctx, const uint8_t *data, uint32_t len)</td></tr>
|
||
<tr class="memdesc:a1fb4423a841ccd728e3ad0d028cbc9b4"><td class="mdescLeft"> </td><td class="mdescRight">Updates the CRC64 context with new data. <br /></td></tr>
|
||
<tr class="memitem:ae48cfb59c6585e9ffd4cd1a97044891f" id="r_ae48cfb59c6585e9ffd4cd1a97044891f"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#ae48cfb59c6585e9ffd4cd1a97044891f">aaruf_crc64_final</a> (<a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *ctx, uint64_t *crc)</td></tr>
|
||
<tr class="memdesc:ae48cfb59c6585e9ffd4cd1a97044891f"><td class="mdescLeft"> </td><td class="mdescRight">Computes the final CRC64 value from the context. <br /></td></tr>
|
||
<tr class="memitem:a4943569a8623eb2e3e0adc276c433097" id="r_a4943569a8623eb2e3e0adc276c433097"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a4943569a8623eb2e3e0adc276c433097">aaruf_crc64_free</a> (<a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *ctx)</td></tr>
|
||
<tr class="memdesc:a4943569a8623eb2e3e0adc276c433097"><td class="mdescLeft"> </td><td class="mdescRight">Frees a CRC64 context. <br /></td></tr>
|
||
<tr class="memitem:a83ecd1f5636915aebacfd29fc6306520" id="r_a83ecd1f5636915aebacfd29fc6306520"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a83ecd1f5636915aebacfd29fc6306520">aaruf_crc64_slicing</a> (uint64_t *previous_crc, const uint8_t *data, uint32_t len)</td></tr>
|
||
<tr class="memdesc:a83ecd1f5636915aebacfd29fc6306520"><td class="mdescLeft"> </td><td class="mdescRight">Updates a CRC64 value using the slicing-by-8 algorithm. <br /></td></tr>
|
||
<tr class="memitem:a0fee4834bf0747bcd933c4e754aa4692" id="r_a0fee4834bf0747bcd933c4e754aa4692"><td class="memItemLeft" align="right" valign="top">uint64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a0fee4834bf0747bcd933c4e754aa4692">aaruf_crc64_data</a> (const uint8_t *data, uint32_t len)</td></tr>
|
||
<tr class="memitem:a2ce65757ca5209f17d467c51ba7d445d" id="r_a2ce65757ca5209f17d467c51ba7d445d"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a2ce65757ca5209f17d467c51ba7d445d">aaruf_get_tracks</a> (const void *context, uint8_t *buffer, size_t *length)</td></tr>
|
||
<tr class="memdesc:a2ce65757ca5209f17d467c51ba7d445d"><td class="mdescLeft"> </td><td class="mdescRight">Retrieve the array of track descriptors contained in an opened AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a518d8d68debf1b9a24af3eb6bc2f9e49" id="r_a518d8d68debf1b9a24af3eb6bc2f9e49"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a518d8d68debf1b9a24af3eb6bc2f9e49">aaruf_set_tracks</a> (void *context, <a class="el" href="structTrackEntry.html">TrackEntry</a> *tracks, const int count)</td></tr>
|
||
<tr class="memdesc:a518d8d68debf1b9a24af3eb6bc2f9e49"><td class="mdescLeft"> </td><td class="mdescRight">Replace (or clear) the in-memory track table for an AaruFormat image context. <br /></td></tr>
|
||
<tr class="memitem:a53397980f6b05e3ad0145f2941de16d2" id="r_a53397980f6b05e3ad0145f2941de16d2"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a53397980f6b05e3ad0145f2941de16d2">aaruf_read_sector</a> (void *context, uint64_t sector_address, bool negative, uint8_t *data, uint32_t *length)</td></tr>
|
||
<tr class="memdesc:a53397980f6b05e3ad0145f2941de16d2"><td class="mdescLeft"> </td><td class="mdescRight">Reads a sector from the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a719a992be38ee90a5e302725c18a791b" id="r_a719a992be38ee90a5e302725c18a791b"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a719a992be38ee90a5e302725c18a791b">aaruf_read_sector_long</a> (void *context, uint64_t sector_address, bool negative, uint8_t *data, uint32_t *length)</td></tr>
|
||
<tr class="memdesc:a719a992be38ee90a5e302725c18a791b"><td class="mdescLeft"> </td><td class="mdescRight">Reads a complete sector with all metadata from the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a4b8cd2bb5fd9e2c670a0a13695c6f9e3" id="r_a4b8cd2bb5fd9e2c670a0a13695c6f9e3"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a4b8cd2bb5fd9e2c670a0a13695c6f9e3">aaruf_write_sector</a> (void *context, uint64_t sector_address, bool negative, const uint8_t *data, uint8_t sector_status, uint32_t length)</td></tr>
|
||
<tr class="memdesc:a4b8cd2bb5fd9e2c670a0a13695c6f9e3"><td class="mdescLeft"> </td><td class="mdescRight">Writes a sector to the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a69ca66242c0becf7640b3d1cc8da8f9c" id="r_a69ca66242c0becf7640b3d1cc8da8f9c"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a69ca66242c0becf7640b3d1cc8da8f9c">aaruf_write_sector_long</a> (void *context, uint64_t sector_address, bool negative, const uint8_t *data, uint8_t sector_status, uint32_t length)</td></tr>
|
||
<tr class="memdesc:a69ca66242c0becf7640b3d1cc8da8f9c"><td class="mdescLeft"> </td><td class="mdescRight">Writes a full ("long") raw sector from optical or block media, parsing structure and validating content. <br /></td></tr>
|
||
<tr class="memitem:aa041a789fbae70c1e1ec3e38f1ab369d" id="r_aa041a789fbae70c1e1ec3e38f1ab369d"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#aa041a789fbae70c1e1ec3e38f1ab369d">aaruf_write_media_tag</a> (void *context, const uint8_t *data, int32_t type, uint32_t length)</td></tr>
|
||
<tr class="memdesc:aa041a789fbae70c1e1ec3e38f1ab369d"><td class="mdescLeft"> </td><td class="mdescRight">Writes a media tag to the AaruFormat image, storing medium-specific metadata and descriptors. <br /></td></tr>
|
||
<tr class="memitem:a6a8994cd006711347fb03cec465eafa6" id="r_a6a8994cd006711347fb03cec465eafa6"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a6a8994cd006711347fb03cec465eafa6">aaruf_write_sector_tag</a> (void *context, uint64_t sector_address, bool negative, const uint8_t *data, size_t length, int32_t tag)</td></tr>
|
||
<tr class="memdesc:a6a8994cd006711347fb03cec465eafa6"><td class="mdescLeft"> </td><td class="mdescRight">Writes per-sector tag data (auxiliary metadata) for a specific sector. <br /></td></tr>
|
||
<tr class="memitem:a8cbf4d8059c4b36e8ab5e18fec057b52" id="r_a8cbf4d8059c4b36e8ab5e18fec057b52"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a8cbf4d8059c4b36e8ab5e18fec057b52">aaruf_verify_image</a> (void *context)</td></tr>
|
||
<tr class="memdesc:a8cbf4d8059c4b36e8ab5e18fec057b52"><td class="mdescLeft"> </td><td class="mdescRight">Verifies the integrity of an AaruFormat image file. <br /></td></tr>
|
||
<tr class="memitem:a0b29337ce6fedc79bf7d1a84d92173d6" id="r_a0b29337ce6fedc79bf7d1a84d92173d6"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a0b29337ce6fedc79bf7d1a84d92173d6">aaruf_cst_transform</a> (const uint8_t *interleaved, uint8_t *sequential, size_t length)</td></tr>
|
||
<tr class="memdesc:a0b29337ce6fedc79bf7d1a84d92173d6"><td class="mdescLeft"> </td><td class="mdescRight">Transforms interleaved subchannel data to sequential format. <br /></td></tr>
|
||
<tr class="memitem:adee4702d830dc13b78e0a6803658c40e" id="r_adee4702d830dc13b78e0a6803658c40e"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#adee4702d830dc13b78e0a6803658c40e">aaruf_cst_untransform</a> (const uint8_t *sequential, uint8_t *interleaved, size_t length)</td></tr>
|
||
<tr class="memdesc:adee4702d830dc13b78e0a6803658c40e"><td class="mdescLeft"> </td><td class="mdescRight">Reverses the CST (Claunia's Subchannel Transform) transformation from sequential to interleaved data. <br /></td></tr>
|
||
<tr class="memitem:ac1a30bb251ac148f485c51593c0740c1" id="r_ac1a30bb251ac148f485c51593c0740c1"><td class="memItemLeft" align="right" valign="top">void * </td><td class="memItemRight" valign="bottom"><a class="el" href="#ac1a30bb251ac148f485c51593c0740c1">aaruf_ecc_cd_init</a> ()</td></tr>
|
||
<tr class="memdesc:ac1a30bb251ac148f485c51593c0740c1"><td class="mdescLeft"> </td><td class="mdescRight">Initializes a Compact Disc ECC context. <br /></td></tr>
|
||
<tr class="memitem:afbc09e16b1a654de04706e07c3212ecb" id="r_afbc09e16b1a654de04706e07c3212ecb"><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="#afbc09e16b1a654de04706e07c3212ecb">aaruf_ecc_cd_is_suffix_correct</a> (void *context, const uint8_t *sector)</td></tr>
|
||
<tr class="memdesc:afbc09e16b1a654de04706e07c3212ecb"><td class="mdescLeft"> </td><td class="mdescRight">Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 1). <br /></td></tr>
|
||
<tr class="memitem:ab77ca170a2e8d2f0a2a7ea1a8a51690a" id="r_ab77ca170a2e8d2f0a2a7ea1a8a51690a"><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="#ab77ca170a2e8d2f0a2a7ea1a8a51690a">aaruf_ecc_cd_is_suffix_correct_mode2</a> (void *context, const uint8_t *sector)</td></tr>
|
||
<tr class="memdesc:ab77ca170a2e8d2f0a2a7ea1a8a51690a"><td class="mdescLeft"> </td><td class="mdescRight">Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 2). <br /></td></tr>
|
||
<tr class="memitem:a562bb88bbf499eac272182acb5528dea" id="r_a562bb88bbf499eac272182acb5528dea"><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="#a562bb88bbf499eac272182acb5528dea">aaruf_ecc_cd_check</a> (void *context, const uint8_t *address, const uint8_t *data, uint32_t major_count, uint32_t minor_count, uint32_t major_mult, uint32_t minor_inc, const uint8_t *ecc, int32_t address_offset, int32_t data_offset, int32_t ecc_offset)</td></tr>
|
||
<tr class="memdesc:a562bb88bbf499eac272182acb5528dea"><td class="mdescLeft"> </td><td class="mdescRight">Checks the ECC of a CD sector. <br /></td></tr>
|
||
<tr class="memitem:a892f09f0b28f1183064eef6eb4d46f42" id="r_a892f09f0b28f1183064eef6eb4d46f42"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a892f09f0b28f1183064eef6eb4d46f42">aaruf_ecc_cd_write</a> (void *context, const uint8_t *address, const uint8_t *data, uint32_t major_count, uint32_t minor_count, uint32_t major_mult, uint32_t minor_inc, uint8_t *ecc, int32_t address_offset, int32_t data_offset, int32_t ecc_offset)</td></tr>
|
||
<tr class="memdesc:a892f09f0b28f1183064eef6eb4d46f42"><td class="mdescLeft"> </td><td class="mdescRight">Writes ECC for a CD sector. <br /></td></tr>
|
||
<tr class="memitem:a322819729519cc5e0fcd625510158e18" id="r_a322819729519cc5e0fcd625510158e18"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a322819729519cc5e0fcd625510158e18">aaruf_ecc_cd_write_sector</a> (void *context, const uint8_t *address, const uint8_t *data, uint8_t *ecc, int32_t address_offset, int32_t data_offset, int32_t ecc_offset)</td></tr>
|
||
<tr class="memdesc:a322819729519cc5e0fcd625510158e18"><td class="mdescLeft"> </td><td class="mdescRight">Writes ECC for a full CD sector (both P and Q ECC). <br /></td></tr>
|
||
<tr class="memitem:a033bfc0dd219563f45b7e5c85dd5d3fa" id="r_a033bfc0dd219563f45b7e5c85dd5d3fa"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a033bfc0dd219563f45b7e5c85dd5d3fa">aaruf_cd_lba_to_msf</a> (int64_t pos, uint8_t *minute, uint8_t *second, uint8_t *frame)</td></tr>
|
||
<tr class="memdesc:a033bfc0dd219563f45b7e5c85dd5d3fa"><td class="mdescLeft"> </td><td class="mdescRight">Converts a CD LBA (Logical Block Address) to MSF (Minute:Second:Frame) format. <br /></td></tr>
|
||
<tr class="memitem:a73c3788f7376196abd596d6d846466b1" id="r_a73c3788f7376196abd596d6d846466b1"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a73c3788f7376196abd596d6d846466b1">aaruf_ecc_cd_reconstruct_prefix</a> (uint8_t *sector, uint8_t type, int64_t lba)</td></tr>
|
||
<tr class="memdesc:a73c3788f7376196abd596d6d846466b1"><td class="mdescLeft"> </td><td class="mdescRight">Reconstructs the prefix (sync, address, mode) of a CD sector. <br /></td></tr>
|
||
<tr class="memitem:a9c9e2440119b8d7e67cb2c40125bf295" id="r_a9c9e2440119b8d7e67cb2c40125bf295"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a9c9e2440119b8d7e67cb2c40125bf295">aaruf_ecc_cd_reconstruct</a> (void *context, uint8_t *sector, uint8_t type)</td></tr>
|
||
<tr class="memdesc:a9c9e2440119b8d7e67cb2c40125bf295"><td class="mdescLeft"> </td><td class="mdescRight">Reconstructs the EDC and ECC fields of a CD sector. <br /></td></tr>
|
||
<tr class="memitem:a67c65c3f2ca5cdf1596c16fa35558df1" id="r_a67c65c3f2ca5cdf1596c16fa35558df1"><td class="memItemLeft" align="right" valign="top">uint32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a67c65c3f2ca5cdf1596c16fa35558df1">aaruf_edc_cd_compute</a> (void *context, uint32_t edc, const uint8_t *src, int size, int pos)</td></tr>
|
||
<tr class="memdesc:a67c65c3f2ca5cdf1596c16fa35558df1"><td class="mdescLeft"> </td><td class="mdescRight">Computes the EDC (Error Detection Code) for a CD sector. <br /></td></tr>
|
||
<tr class="memitem:a33f54ac12ab867e9a9b2347c239e6c6e" id="r_a33f54ac12ab867e9a9b2347c239e6c6e"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a33f54ac12ab867e9a9b2347c239e6c6e">aaruf_read_track_sector</a> (void *context, uint8_t *data, uint64_t sector_address, uint32_t *length, uint8_t track)</td></tr>
|
||
<tr class="memdesc:a33f54ac12ab867e9a9b2347c239e6c6e"><td class="mdescLeft"> </td><td class="mdescRight">Reads a sector from a specific track in the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:ae5a85524a6e27339c02c4a5791e0db57" id="r_ae5a85524a6e27339c02c4a5791e0db57"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#ae5a85524a6e27339c02c4a5791e0db57">aaruf_read_sector_tag</a> (const void *context, uint64_t sector_address, bool negative, uint8_t *buffer, uint32_t *length, int32_t tag)</td></tr>
|
||
<tr class="memdesc:ae5a85524a6e27339c02c4a5791e0db57"><td class="mdescLeft"> </td><td class="mdescRight">Reads a specific sector tag from the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a554f1cbd4c013c46788b2276c3244c32" id="r_a554f1cbd4c013c46788b2276c3244c32"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a554f1cbd4c013c46788b2276c3244c32">aaruf_get_media_tag_type_for_datatype</a> (int32_t type)</td></tr>
|
||
<tr class="memdesc:a554f1cbd4c013c46788b2276c3244c32"><td class="mdescLeft"> </td><td class="mdescRight">Converts an image data type to an Aaru media tag type. <br /></td></tr>
|
||
<tr class="memitem:a8d042b26980b56b5dd872f21fa33de70" id="r_a8d042b26980b56b5dd872f21fa33de70"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a8d042b26980b56b5dd872f21fa33de70">aaruf_get_datatype_for_media_tag_type</a> (int32_t tag_type)</td></tr>
|
||
<tr class="memdesc:a8d042b26980b56b5dd872f21fa33de70"><td class="mdescLeft"> </td><td class="mdescRight">Converts an Aaru media tag type to an image data type. <br /></td></tr>
|
||
<tr class="memitem:ac5f5334a51424028574a5433a0e24b20" id="r_ac5f5334a51424028574a5433a0e24b20"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#ac5f5334a51424028574a5433a0e24b20">aaruf_get_xml_mediatype</a> (int32_t type)</td></tr>
|
||
<tr class="memitem:abbcf276c3518b3e666885ab250fd374e" id="r_abbcf276c3518b3e666885ab250fd374e"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#abbcf276c3518b3e666885ab250fd374e">aaruf_get_geometry</a> (const void *context, uint32_t *cylinders, uint32_t *heads, uint32_t *sectors_per_track)</td></tr>
|
||
<tr class="memdesc:abbcf276c3518b3e666885ab250fd374e"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the logical CHS geometry from the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a21f4b3cf398b1a1c008c9a070ef9277b" id="r_a21f4b3cf398b1a1c008c9a070ef9277b"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a21f4b3cf398b1a1c008c9a070ef9277b">aaruf_set_geometry</a> (void *context, uint32_t cylinders, uint32_t heads, uint32_t sectors_per_track)</td></tr>
|
||
<tr class="memdesc:a21f4b3cf398b1a1c008c9a070ef9277b"><td class="mdescLeft"> </td><td class="mdescRight">Sets the logical CHS geometry for the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a00537ecc9cb55b4ce3c92d61a8cea094" id="r_a00537ecc9cb55b4ce3c92d61a8cea094"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a00537ecc9cb55b4ce3c92d61a8cea094">aaruf_set_media_sequence</a> (void *context, int32_t sequence, int32_t last_sequence)</td></tr>
|
||
<tr class="memdesc:a00537ecc9cb55b4ce3c92d61a8cea094"><td class="mdescLeft"> </td><td class="mdescRight">Sets the media sequence information for multi-volume media sets. <br /></td></tr>
|
||
<tr class="memitem:a1da2dd0571762fa7c13bc956ec12dfab" id="r_a1da2dd0571762fa7c13bc956ec12dfab"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a1da2dd0571762fa7c13bc956ec12dfab">aaruf_set_creator</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a1da2dd0571762fa7c13bc956ec12dfab"><td class="mdescLeft"> </td><td class="mdescRight">Sets the creator (person/operator) information for the image. <br /></td></tr>
|
||
<tr class="memitem:af7fcca1ab5ff0422ec81ec6e99001b38" id="r_af7fcca1ab5ff0422ec81ec6e99001b38"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#af7fcca1ab5ff0422ec81ec6e99001b38">aaruf_set_comments</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:af7fcca1ab5ff0422ec81ec6e99001b38"><td class="mdescLeft"> </td><td class="mdescRight">Sets user comments or notes for the image. <br /></td></tr>
|
||
<tr class="memitem:a37f50b38ceaee7db0b7731ee978b8241" id="r_a37f50b38ceaee7db0b7731ee978b8241"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a37f50b38ceaee7db0b7731ee978b8241">aaruf_set_media_title</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a37f50b38ceaee7db0b7731ee978b8241"><td class="mdescLeft"> </td><td class="mdescRight">Sets the media title or label for the image. <br /></td></tr>
|
||
<tr class="memitem:a3d46262ff1f9d51d57d1e95648f4083b" id="r_a3d46262ff1f9d51d57d1e95648f4083b"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a3d46262ff1f9d51d57d1e95648f4083b">aaruf_set_media_manufacturer</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a3d46262ff1f9d51d57d1e95648f4083b"><td class="mdescLeft"> </td><td class="mdescRight">Sets the media manufacturer information for the image. <br /></td></tr>
|
||
<tr class="memitem:a8eed9fbf0341f48bac755524f4c99ef2" id="r_a8eed9fbf0341f48bac755524f4c99ef2"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a8eed9fbf0341f48bac755524f4c99ef2">aaruf_set_media_model</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a8eed9fbf0341f48bac755524f4c99ef2"><td class="mdescLeft"> </td><td class="mdescRight">Sets the media model or product designation for the image. <br /></td></tr>
|
||
<tr class="memitem:a2dff9d23775ba429c38efd251844092d" id="r_a2dff9d23775ba429c38efd251844092d"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a2dff9d23775ba429c38efd251844092d">aaruf_set_media_serial_number</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a2dff9d23775ba429c38efd251844092d"><td class="mdescLeft"> </td><td class="mdescRight">Sets the media serial number for the image. <br /></td></tr>
|
||
<tr class="memitem:a4499e33d2fd3f8b514e510180972ec6f" id="r_a4499e33d2fd3f8b514e510180972ec6f"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a4499e33d2fd3f8b514e510180972ec6f">aaruf_set_media_barcode</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a4499e33d2fd3f8b514e510180972ec6f"><td class="mdescLeft"> </td><td class="mdescRight">Sets the media barcode information for the image. <br /></td></tr>
|
||
<tr class="memitem:a05157a196fb583605599414d7ab06f53" id="r_a05157a196fb583605599414d7ab06f53"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a05157a196fb583605599414d7ab06f53">aaruf_set_media_part_number</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a05157a196fb583605599414d7ab06f53"><td class="mdescLeft"> </td><td class="mdescRight">Sets the media part number or model designation for the image. <br /></td></tr>
|
||
<tr class="memitem:a3acb21067897f9cfc40e6288050a60c1" id="r_a3acb21067897f9cfc40e6288050a60c1"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a3acb21067897f9cfc40e6288050a60c1">aaruf_set_drive_manufacturer</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a3acb21067897f9cfc40e6288050a60c1"><td class="mdescLeft"> </td><td class="mdescRight">Sets the drive manufacturer information for the image. <br /></td></tr>
|
||
<tr class="memitem:a1b4d35ee16a27a13f1bc16b0a17d65d1" id="r_a1b4d35ee16a27a13f1bc16b0a17d65d1"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a1b4d35ee16a27a13f1bc16b0a17d65d1">aaruf_set_drive_model</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:a1b4d35ee16a27a13f1bc16b0a17d65d1"><td class="mdescLeft"> </td><td class="mdescRight">Sets the drive model information for the image. <br /></td></tr>
|
||
<tr class="memitem:aef269305958754978beedf4c44618d98" id="r_aef269305958754978beedf4c44618d98"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#aef269305958754978beedf4c44618d98">aaruf_set_drive_serial_number</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:aef269305958754978beedf4c44618d98"><td class="mdescLeft"> </td><td class="mdescRight">Sets the drive serial number for the image. <br /></td></tr>
|
||
<tr class="memitem:add7cede9e5544ae12ae2b22eaf48e54c" id="r_add7cede9e5544ae12ae2b22eaf48e54c"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#add7cede9e5544ae12ae2b22eaf48e54c">aaruf_set_drive_firmware_revision</a> (void *context, const uint8_t *data, int32_t length)</td></tr>
|
||
<tr class="memdesc:add7cede9e5544ae12ae2b22eaf48e54c"><td class="mdescLeft"> </td><td class="mdescRight">Sets the drive firmware revision for the image. <br /></td></tr>
|
||
<tr class="memitem:aa683ff7387ba3f505b1756da1b408f7e" id="r_aa683ff7387ba3f505b1756da1b408f7e"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#aa683ff7387ba3f505b1756da1b408f7e">aaruf_get_media_sequence</a> (const void *context, int32_t *sequence, int32_t *last_sequence)</td></tr>
|
||
<tr class="memdesc:aa683ff7387ba3f505b1756da1b408f7e"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the media sequence metadata for multi-volume image sets. <br /></td></tr>
|
||
<tr class="memitem:a38d72be7e7854d6cb0bba89172e27b03" id="r_a38d72be7e7854d6cb0bba89172e27b03"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a38d72be7e7854d6cb0bba89172e27b03">aaruf_get_creator</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a38d72be7e7854d6cb0bba89172e27b03"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the recorded creator (operator) name from the MetadataBlock. <br /></td></tr>
|
||
<tr class="memitem:a9628bcfd2642649a6bcbf1f46d6b6705" id="r_a9628bcfd2642649a6bcbf1f46d6b6705"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a9628bcfd2642649a6bcbf1f46d6b6705">aaruf_get_comments</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a9628bcfd2642649a6bcbf1f46d6b6705"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the user comments or notes stored in the MetadataBlock. <br /></td></tr>
|
||
<tr class="memitem:af1ca27c052c6cde38a8d6d71e10936db" id="r_af1ca27c052c6cde38a8d6d71e10936db"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#af1ca27c052c6cde38a8d6d71e10936db">aaruf_get_media_title</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:af1ca27c052c6cde38a8d6d71e10936db"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the media title or label captured during image creation. <br /></td></tr>
|
||
<tr class="memitem:a515c264f726f8b0a5104778b383ad1d4" id="r_a515c264f726f8b0a5104778b383ad1d4"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a515c264f726f8b0a5104778b383ad1d4">aaruf_get_media_manufacturer</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a515c264f726f8b0a5104778b383ad1d4"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the recorded media manufacturer name. <br /></td></tr>
|
||
<tr class="memitem:a509892f76c9a03a030693740d043adfc" id="r_a509892f76c9a03a030693740d043adfc"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a509892f76c9a03a030693740d043adfc">aaruf_get_media_model</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a509892f76c9a03a030693740d043adfc"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the media model or product designation metadata. <br /></td></tr>
|
||
<tr class="memitem:a4cb7b7200e36efb4983cf2c5c5543313" id="r_a4cb7b7200e36efb4983cf2c5c5543313"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a4cb7b7200e36efb4983cf2c5c5543313">aaruf_get_media_serial_number</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a4cb7b7200e36efb4983cf2c5c5543313"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the media serial number recorded in the image metadata. <br /></td></tr>
|
||
<tr class="memitem:a580c8bf133cf3481deca14779b8b5419" id="r_a580c8bf133cf3481deca14779b8b5419"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a580c8bf133cf3481deca14779b8b5419">aaruf_get_media_barcode</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a580c8bf133cf3481deca14779b8b5419"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the barcode assigned to the physical media or its packaging. <br /></td></tr>
|
||
<tr class="memitem:a4cdfb46f5630fcf1fe6447b37ad18ae2" id="r_a4cdfb46f5630fcf1fe6447b37ad18ae2"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a4cdfb46f5630fcf1fe6447b37ad18ae2">aaruf_get_media_part_number</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a4cdfb46f5630fcf1fe6447b37ad18ae2"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the media part number recorded in the MetadataBlock. <br /></td></tr>
|
||
<tr class="memitem:a5d487a858c48838bcc9f3bba4b5944a1" id="r_a5d487a858c48838bcc9f3bba4b5944a1"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a5d487a858c48838bcc9f3bba4b5944a1">aaruf_get_drive_manufacturer</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a5d487a858c48838bcc9f3bba4b5944a1"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the drive manufacturer metadata captured during imaging. <br /></td></tr>
|
||
<tr class="memitem:a54d724659818ea4486f9981672f6d01e" id="r_a54d724659818ea4486f9981672f6d01e"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a54d724659818ea4486f9981672f6d01e">aaruf_get_drive_model</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a54d724659818ea4486f9981672f6d01e"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the device model information for the imaging drive. <br /></td></tr>
|
||
<tr class="memitem:a1892cc8395305d7e85d04544ded62131" id="r_a1892cc8395305d7e85d04544ded62131"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a1892cc8395305d7e85d04544ded62131">aaruf_get_drive_serial_number</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a1892cc8395305d7e85d04544ded62131"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the imaging drive's serial number metadata. <br /></td></tr>
|
||
<tr class="memitem:a3db92f6bebf60195d6ab327e17988cee" id="r_a3db92f6bebf60195d6ab327e17988cee"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a3db92f6bebf60195d6ab327e17988cee">aaruf_get_drive_firmware_revision</a> (const void *context, uint8_t *buffer, int32_t *length)</td></tr>
|
||
<tr class="memdesc:a3db92f6bebf60195d6ab327e17988cee"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the firmware revision metadata for the imaging drive. <br /></td></tr>
|
||
<tr class="memitem:a42f191c2ea4c70c9d7b373c19b59c812" id="r_a42f191c2ea4c70c9d7b373c19b59c812"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a42f191c2ea4c70c9d7b373c19b59c812">aaruf_get_cicm_metadata</a> (const void *context, uint8_t *buffer, size_t *length)</td></tr>
|
||
<tr class="memdesc:a42f191c2ea4c70c9d7b373c19b59c812"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the embedded CICM XML metadata sidecar from the image. <br /></td></tr>
|
||
<tr class="memitem:a01cf0abe0b137236d4be0b91a29d4818" id="r_a01cf0abe0b137236d4be0b91a29d4818"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a01cf0abe0b137236d4be0b91a29d4818">aaruf_get_aaru_json_metadata</a> (const void *context, uint8_t *buffer, size_t *length)</td></tr>
|
||
<tr class="memdesc:a01cf0abe0b137236d4be0b91a29d4818"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the embedded Aaru metadata JSON from the image. <br /></td></tr>
|
||
<tr class="memitem:a8090a039e00ee003569939332d21094e" id="r_a8090a039e00ee003569939332d21094e"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><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"> </td><td class="mdescRight">Sets the Aaru metadata JSON for the image during creation. <br /></td></tr>
|
||
<tr class="memitem:a7e63f10ff3ea353c8c3944cd836a85ee" id="r_a7e63f10ff3ea353c8c3944cd836a85ee"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a7e63f10ff3ea353c8c3944cd836a85ee">aaruf_get_user_sectors</a> (const void *context, uint64_t *sectors)</td></tr>
|
||
<tr class="memdesc:a7e63f10ff3ea353c8c3944cd836a85ee"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the total number of user-accessible sectors in the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a8e00d26a8e751fbd412868ac4f92a3c0" id="r_a8e00d26a8e751fbd412868ac4f92a3c0"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a8e00d26a8e751fbd412868ac4f92a3c0">aaruf_get_negative_sectors</a> (const void *context, uint16_t *sectors)</td></tr>
|
||
<tr class="memdesc:a8e00d26a8e751fbd412868ac4f92a3c0"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the number of negative (pre-gap) sectors in the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:aeeae64b120a10bac5e3d757a07a9691a" id="r_aeeae64b120a10bac5e3d757a07a9691a"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#aeeae64b120a10bac5e3d757a07a9691a">aaruf_get_overflow_sectors</a> (const void *context, uint16_t *sectors)</td></tr>
|
||
<tr class="memdesc:aeeae64b120a10bac5e3d757a07a9691a"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the number of overflow (post-gap) sectors in the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a65c73217edb9661accbbe3de4f555b62" id="r_a65c73217edb9661accbbe3de4f555b62"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a65c73217edb9661accbbe3de4f555b62">aaruf_get_image_info</a> (const void *context, <a class="el" href="structImageInfo.html">ImageInfo</a> *image_info)</td></tr>
|
||
<tr class="memdesc:a65c73217edb9661accbbe3de4f555b62"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves a deep copy of the <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure from the AaruFormat image. <br /></td></tr>
|
||
<tr class="memitem:a1c8d4faf14212a4c46c1fb47bf25ac1e" id="r_a1c8d4faf14212a4c46c1fb47bf25ac1e"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a1c8d4faf14212a4c46c1fb47bf25ac1e">aaruf_get_tape_file</a> (const void *context, uint8_t partition, uint32_t file, uint64_t *starting_block, uint64_t *ending_block)</td></tr>
|
||
<tr class="memdesc:a1c8d4faf14212a4c46c1fb47bf25ac1e"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the block range for a specific tape file from an Aaru tape image. <br /></td></tr>
|
||
<tr class="memitem:a01c915ab49a4b47fd6768a2055208c48" id="r_a01c915ab49a4b47fd6768a2055208c48"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a01c915ab49a4b47fd6768a2055208c48">aaruf_set_tape_file</a> (void *context, uint8_t partition, uint32_t file, uint64_t starting_block, uint64_t ending_block)</td></tr>
|
||
<tr class="memdesc:a01c915ab49a4b47fd6768a2055208c48"><td class="mdescLeft"> </td><td class="mdescRight">Sets or updates the block range for a specific tape file in an Aaru tape image. <br /></td></tr>
|
||
<tr class="memitem:ab1ca1a092699df0f43ea050812f6c6b1" id="r_ab1ca1a092699df0f43ea050812f6c6b1"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#ab1ca1a092699df0f43ea050812f6c6b1">aaruf_get_tape_partition</a> (const void *context, uint8_t partition, uint64_t *starting_block, uint64_t *ending_block)</td></tr>
|
||
<tr class="memdesc:ab1ca1a092699df0f43ea050812f6c6b1"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the block range for a specific tape partition from an Aaru tape image. <br /></td></tr>
|
||
<tr class="memitem:a9daeeb54c74dd2707d95ab47e8ab0a00" id="r_a9daeeb54c74dd2707d95ab47e8ab0a00"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a9daeeb54c74dd2707d95ab47e8ab0a00">aaruf_set_tape_partition</a> (void *context, uint8_t partition, uint64_t starting_block, uint64_t ending_block)</td></tr>
|
||
<tr class="memdesc:a9daeeb54c74dd2707d95ab47e8ab0a00"><td class="mdescLeft"> </td><td class="mdescRight">Sets or updates the block range for a specific tape partition in an Aaru tape image. <br /></td></tr>
|
||
<tr class="memitem:a36af83897e131ba792c51ae8caec9984" id="r_a36af83897e131ba792c51ae8caec9984"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a36af83897e131ba792c51ae8caec9984">aaruf_get_dumphw</a> (void *context, uint8_t *buffer, size_t *length)</td></tr>
|
||
<tr class="memdesc:a36af83897e131ba792c51ae8caec9984"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the dump hardware block containing acquisition environment information. <br /></td></tr>
|
||
<tr class="memitem:ad98012dc12a51d9eadbd79a25aab8299" id="r_ad98012dc12a51d9eadbd79a25aab8299"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#ad98012dc12a51d9eadbd79a25aab8299">aaruf_set_dumphw</a> (void *context, uint8_t *data, size_t length)</td></tr>
|
||
<tr class="memdesc:ad98012dc12a51d9eadbd79a25aab8299"><td class="mdescLeft"> </td><td class="mdescRight">Sets the dump hardware block for the image during creation. <br /></td></tr>
|
||
<tr class="memitem:a793dac760aedda6414ba4014eb2ed0c7" id="r_a793dac760aedda6414ba4014eb2ed0c7"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="#a793dac760aedda6414ba4014eb2ed0c7">aaruf_spamsum_init</a> (void)</td></tr>
|
||
<tr class="memitem:a5a9767f3b860752b493aa7bee9d39a8d" id="r_a5a9767f3b860752b493aa7bee9d39a8d"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#a5a9767f3b860752b493aa7bee9d39a8d">aaruf_spamsum_update</a> (<a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *ctx, const uint8_t *data, uint32_t len)</td></tr>
|
||
<tr class="memdesc:a5a9767f3b860752b493aa7bee9d39a8d"><td class="mdescLeft"> </td><td class="mdescRight">Updates the spamsum context with new data. <br /></td></tr>
|
||
<tr class="memitem:ab1f4894af1962e933767248c4fb0e2e8" id="r_ab1f4894af1962e933767248c4fb0e2e8"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#ab1f4894af1962e933767248c4fb0e2e8">aaruf_spamsum_final</a> (<a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *ctx, uint8_t *result)</td></tr>
|
||
<tr class="memitem:a6fe74704e44be7adfaa2ce676f3c3de4" id="r_a6fe74704e44be7adfaa2ce676f3c3de4"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a6fe74704e44be7adfaa2ce676f3c3de4">aaruf_spamsum_free</a> (<a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *ctx)</td></tr>
|
||
<tr class="memdesc:a6fe74704e44be7adfaa2ce676f3c3de4"><td class="mdescLeft"> </td><td class="mdescRight">Frees a spamsum (fuzzy hash) context. <br /></td></tr>
|
||
<tr class="memitem:a680150d4b3df13261af758c504a1f848" id="r_a680150d4b3df13261af758c504a1f848"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a680150d4b3df13261af758c504a1f848">fuzzy_engine_step</a> (<a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *ctx, uint8_t c)</td></tr>
|
||
<tr class="memitem:a9f287da4a58c0d3ab8f0243de5fe3f8d" id="r_a9f287da4a58c0d3ab8f0243de5fe3f8d"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a9f287da4a58c0d3ab8f0243de5fe3f8d">roll_hash</a> (<a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *ctx, uint8_t c)</td></tr>
|
||
<tr class="memitem:a906ad6bd1809bf999874c848af7c648b" id="r_a906ad6bd1809bf999874c848af7c648b"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a906ad6bd1809bf999874c848af7c648b">fuzzy_try_reduce_blockhash</a> (<a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *ctx)</td></tr>
|
||
<tr class="memitem:a24c6d35239a8d1fee6e93aa12bbd5bd6" id="r_a24c6d35239a8d1fee6e93aa12bbd5bd6"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a24c6d35239a8d1fee6e93aa12bbd5bd6">fuzzy_try_fork_blockhash</a> (<a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *ctx)</td></tr>
|
||
<tr class="memitem:af0ff6ad1495d50a8fa0ce0005be69471" id="r_af0ff6ad1495d50a8fa0ce0005be69471"><td class="memItemLeft" align="right" valign="top">size_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#af0ff6ad1495d50a8fa0ce0005be69471">aaruf_flac_decode_redbook_buffer</a> (uint8_t *dst_buffer, size_t dst_size, const uint8_t *src_buffer, size_t src_size)</td></tr>
|
||
<tr class="memdesc:af0ff6ad1495d50a8fa0ce0005be69471"><td class="mdescLeft"> </td><td class="mdescRight">Decodes a FLAC-compressed Red Book audio buffer. <br /></td></tr>
|
||
<tr class="memitem:a102023fe64e4bd24cd6d4124f0d74e54" id="r_a102023fe64e4bd24cd6d4124f0d74e54"><td class="memItemLeft" align="right" valign="top">size_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a102023fe64e4bd24cd6d4124f0d74e54">aaruf_flac_encode_redbook_buffer</a> (uint8_t *dst_buffer, size_t dst_size, const uint8_t *src_buffer, size_t src_size, uint32_t blocksize, int32_t do_mid_side_stereo, int32_t loose_mid_side_stereo, const char *apodization, uint32_t max_lpc_order, uint32_t qlp_coeff_precision, int32_t do_qlp_coeff_prec_search, int32_t do_exhaustive_model_search, uint32_t min_residual_partition_order, uint32_t max_residual_partition_order, const char *application_id, uint32_t application_id_len)</td></tr>
|
||
<tr class="memdesc:a102023fe64e4bd24cd6d4124f0d74e54"><td class="mdescLeft"> </td><td class="mdescRight">Encodes a Red Book audio buffer to FLAC format. <br /></td></tr>
|
||
<tr class="memitem:a12f3cbc43c2f57a11fbba32a71ba2704" id="r_a12f3cbc43c2f57a11fbba32a71ba2704"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a12f3cbc43c2f57a11fbba32a71ba2704">aaruf_lzma_decode_buffer</a> (uint8_t *dst_buffer, size_t *dst_size, const uint8_t *src_buffer, size_t *src_size, const uint8_t *props, size_t props_size)</td></tr>
|
||
<tr class="memdesc:a12f3cbc43c2f57a11fbba32a71ba2704"><td class="mdescLeft"> </td><td class="mdescRight">Decodes an LZMA-compressed buffer. <br /></td></tr>
|
||
<tr class="memitem:a0e69fad529047d6fe9440b1fc66c3f85" id="r_a0e69fad529047d6fe9440b1fc66c3f85"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="#a0e69fad529047d6fe9440b1fc66c3f85">aaruf_lzma_encode_buffer</a> (uint8_t *dst_buffer, size_t *dst_size, const uint8_t *src_buffer, size_t src_size, uint8_t *out_props, size_t *out_props_size, int32_t level, uint32_t dict_size, int32_t lc, int32_t lp, int32_t pb, int32_t fb, int32_t num_threads)</td></tr>
|
||
<tr class="memdesc:a0e69fad529047d6fe9440b1fc66c3f85"><td class="mdescLeft"> </td><td class="mdescRight">Encodes a buffer using LZMA compression. <br /></td></tr>
|
||
<tr class="memitem:a1e614476485ba9f46e3ac79858210f63" id="r_a1e614476485ba9f46e3ac79858210f63"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a1e614476485ba9f46e3ac79858210f63">aaruf_md5_init</a> (<a class="el" href="structmd5__ctx.html">md5_ctx</a> *ctx)</td></tr>
|
||
<tr class="memitem:a6e19e853bea5db901de83fa2fa29055c" id="r_a6e19e853bea5db901de83fa2fa29055c"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a6e19e853bea5db901de83fa2fa29055c">aaruf_md5_update</a> (<a class="el" href="structmd5__ctx.html">md5_ctx</a> *ctx, const void *data, unsigned long size)</td></tr>
|
||
<tr class="memitem:a6b98055d07ba51f0daef5b03ce2fe725" id="r_a6b98055d07ba51f0daef5b03ce2fe725"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a6b98055d07ba51f0daef5b03ce2fe725">aaruf_md5_final</a> (<a class="el" href="structmd5__ctx.html">md5_ctx</a> *ctx, unsigned char *result)</td></tr>
|
||
<tr class="memitem:abe1156eceb456b48e92389d9f2a20601" id="r_abe1156eceb456b48e92389d9f2a20601"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#abe1156eceb456b48e92389d9f2a20601">aaruf_md5_buffer</a> (const void *data, unsigned long size, unsigned char *result)</td></tr>
|
||
<tr class="memitem:a9bcd5c47b9b593c95be9d4f82253739a" id="r_a9bcd5c47b9b593c95be9d4f82253739a"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a9bcd5c47b9b593c95be9d4f82253739a">aaruf_sha1_init</a> (<a class="el" href="structsha1__ctx.html">sha1_ctx</a> *ctx)</td></tr>
|
||
<tr class="memitem:abead53c8e55f1f99900fdae16d9da70f" id="r_abead53c8e55f1f99900fdae16d9da70f"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#abead53c8e55f1f99900fdae16d9da70f">aaruf_sha1_update</a> (<a class="el" href="structsha1__ctx.html">sha1_ctx</a> *ctx, const void *data, unsigned long size)</td></tr>
|
||
<tr class="memitem:a0396232d1020b16b2cb4bf0b1aa2b021" id="r_a0396232d1020b16b2cb4bf0b1aa2b021"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a0396232d1020b16b2cb4bf0b1aa2b021">aaruf_sha1_final</a> (<a class="el" href="structsha1__ctx.html">sha1_ctx</a> *ctx, unsigned char *result)</td></tr>
|
||
<tr class="memitem:a1e8667b4e2bc168a5411d9671a44a73c" id="r_a1e8667b4e2bc168a5411d9671a44a73c"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a1e8667b4e2bc168a5411d9671a44a73c">aaruf_sha1_buffer</a> (const void *data, unsigned long size, unsigned char *result)</td></tr>
|
||
<tr class="memitem:a075527f7b15b70dc7028cf91d9062a90" id="r_a075527f7b15b70dc7028cf91d9062a90"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a075527f7b15b70dc7028cf91d9062a90">aaruf_sha256_init</a> (<a class="el" href="structsha256__ctx.html">sha256_ctx</a> *ctx)</td></tr>
|
||
<tr class="memitem:ab5f178e5ec94596e44a3fdb001d4a5f8" id="r_ab5f178e5ec94596e44a3fdb001d4a5f8"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#ab5f178e5ec94596e44a3fdb001d4a5f8">aaruf_sha256_update</a> (<a class="el" href="structsha256__ctx.html">sha256_ctx</a> *ctx, const void *data, unsigned long size)</td></tr>
|
||
<tr class="memitem:a6456150dad701ca7f071940ef169c4cf" id="r_a6456150dad701ca7f071940ef169c4cf"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a6456150dad701ca7f071940ef169c4cf">aaruf_sha256_final</a> (<a class="el" href="structsha256__ctx.html">sha256_ctx</a> *ctx, unsigned char *result)</td></tr>
|
||
<tr class="memitem:a7bae173c313a0752035e6eac045326e8" id="r_a7bae173c313a0752035e6eac045326e8"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#a7bae173c313a0752035e6eac045326e8">aaruf_sha256_buffer</a> (const void *data, unsigned long size, unsigned char *result)</td></tr>
|
||
</table>
|
||
<a name="doc-define-members" id="doc-define-members"></a><h2 id="header-doc-define-members" class="groupheader">Macro Definition Documentation</h2>
|
||
<a id="a018e0da1c1f7e4f6187a982c0e40e056" name="a018e0da1c1f7e4f6187a982c0e40e056"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a018e0da1c1f7e4f6187a982c0e40e056">◆ </a></span>AARU_CALL</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">#define AARU_CALL</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="decls_8h_source.html#l00045">45</a> of file <a class="el" href="decls_8h_source.html">decls.h</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="crc64_8c_source.html#l00141">aaruf_crc64_final()</a>, <a class="el" href="crc64_8c_source.html#l00155">aaruf_crc64_free()</a>, <a class="el" href="crc64_8c_source.html#l00032">aaruf_crc64_init()</a>, <a class="el" href="crc64_8c_source.html#l00102">aaruf_crc64_slicing()</a>, <a class="el" href="crc64_8c_source.html#l00055">aaruf_crc64_update()</a>, <a class="el" href="flac_8c_source.html#l00048">aaruf_flac_decode_redbook_buffer()</a>, <a class="el" href="flac_8c_source.html#l00175">aaruf_flac_encode_redbook_buffer()</a>, <a class="el" href="lzma_8c_source.html#l00039">aaruf_lzma_decode_buffer()</a>, <a class="el" href="lzma_8c_source.html#l00065">aaruf_lzma_encode_buffer()</a>, <a class="el" href="md5_8c_source.html#l00508">aaruf_md5_buffer()</a>, <a class="el" href="md5_8c_source.html#l00475">aaruf_md5_final()</a>, <a class="el" href="md5_8c_source.html#l00425">aaruf_md5_init()</a>, <a class="el" href="md5_8c_source.html#l00436">aaruf_md5_update()</a>, <a class="el" href="sha1_8c_source.html#l00155">aaruf_sha1_buffer()</a>, <a class="el" href="sha1_8c_source.html#l00124">aaruf_sha1_final()</a>, <a class="el" href="sha1_8c_source.html#l00034">aaruf_sha1_init()</a>, <a class="el" href="sha1_8c_source.html#l00089">aaruf_sha1_update()</a>, <a class="el" href="sha256_8c_source.html#l00141">aaruf_sha256_buffer()</a>, <a class="el" href="sha256_8c_source.html#l00115">aaruf_sha256_final()</a>, <a class="el" href="sha256_8c_source.html#l00076">aaruf_sha256_init()</a>, <a class="el" href="sha256_8c_source.html#l00090">aaruf_sha256_update()</a>, <a class="el" href="spamsum_8c_source.html#l00191">aaruf_spamsum_final()</a>, <a class="el" href="spamsum_8c_source.html#l00075">aaruf_spamsum_free()</a>, <a class="el" href="spamsum_8c_source.html#l00037">aaruf_spamsum_init()</a>, and <a class="el" href="spamsum_8c_source.html#l00059">aaruf_spamsum_update()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a9001412c35f3c92d3a9320d27b0d97f9" name="a9001412c35f3c92d3a9320d27b0d97f9"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a9001412c35f3c92d3a9320d27b0d97f9">◆ </a></span>AARU_EXPORT</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">#define AARU_EXPORT   <a class="el" href="#a95e1d92b2619a326b2e86600f3d23100">EXTERNC</a></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="decls_8h_source.html#l00054">54</a> of file <a class="el" href="decls_8h_source.html">decls.h</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="crc64_8c_source.html#l00141">aaruf_crc64_final()</a>, <a class="el" href="crc64_8c_source.html#l00155">aaruf_crc64_free()</a>, <a class="el" href="crc64_8c_source.html#l00032">aaruf_crc64_init()</a>, <a class="el" href="crc64_8c_source.html#l00102">aaruf_crc64_slicing()</a>, <a class="el" href="crc64_8c_source.html#l00055">aaruf_crc64_update()</a>, <a class="el" href="flac_8c_source.html#l00048">aaruf_flac_decode_redbook_buffer()</a>, <a class="el" href="flac_8c_source.html#l00175">aaruf_flac_encode_redbook_buffer()</a>, <a class="el" href="lzma_8c_source.html#l00039">aaruf_lzma_decode_buffer()</a>, <a class="el" href="lzma_8c_source.html#l00065">aaruf_lzma_encode_buffer()</a>, <a class="el" href="md5_8c_source.html#l00508">aaruf_md5_buffer()</a>, <a class="el" href="md5_8c_source.html#l00475">aaruf_md5_final()</a>, <a class="el" href="md5_8c_source.html#l00425">aaruf_md5_init()</a>, <a class="el" href="md5_8c_source.html#l00436">aaruf_md5_update()</a>, <a class="el" href="sha1_8c_source.html#l00155">aaruf_sha1_buffer()</a>, <a class="el" href="sha1_8c_source.html#l00124">aaruf_sha1_final()</a>, <a class="el" href="sha1_8c_source.html#l00034">aaruf_sha1_init()</a>, <a class="el" href="sha1_8c_source.html#l00089">aaruf_sha1_update()</a>, <a class="el" href="sha256_8c_source.html#l00141">aaruf_sha256_buffer()</a>, <a class="el" href="sha256_8c_source.html#l00115">aaruf_sha256_final()</a>, <a class="el" href="sha256_8c_source.html#l00076">aaruf_sha256_init()</a>, <a class="el" href="sha256_8c_source.html#l00090">aaruf_sha256_update()</a>, <a class="el" href="spamsum_8c_source.html#l00191">aaruf_spamsum_final()</a>, <a class="el" href="spamsum_8c_source.html#l00075">aaruf_spamsum_free()</a>, <a class="el" href="spamsum_8c_source.html#l00037">aaruf_spamsum_init()</a>, and <a class="el" href="spamsum_8c_source.html#l00059">aaruf_spamsum_update()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a8a7eac34f7a0caaa0d4a57e9627ba173" name="a8a7eac34f7a0caaa0d4a57e9627ba173"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a8a7eac34f7a0caaa0d4a57e9627ba173">◆ </a></span>AARU_LOCAL</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">#define AARU_LOCAL</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="decls_8h_source.html#l00055">55</a> of file <a class="el" href="decls_8h_source.html">decls.h</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="spamsum_8c_source.html#l00084">fuzzy_engine_step()</a>, <a class="el" href="spamsum_8c_source.html#l00175">fuzzy_try_fork_blockhash()</a>, <a class="el" href="spamsum_8c_source.html#l00155">fuzzy_try_reduce_blockhash()</a>, <a class="el" href="spamsum_8c_source.html#l00137">roll_hash()</a>, <a class="el" href="sha1_8c_source.html#l00045">sha1_transform()</a>, and <a class="el" href="sha256_8c_source.html#l00041">sha256_transform()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a95e1d92b2619a326b2e86600f3d23100" name="a95e1d92b2619a326b2e86600f3d23100"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a95e1d92b2619a326b2e86600f3d23100">◆ </a></span>EXTERNC</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">#define EXTERNC</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="decls_8h_source.html#l00034">34</a> of file <a class="el" href="decls_8h_source.html">decls.h</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ac032d233a8ebfcd82fd49d0824eefb18" name="ac032d233a8ebfcd82fd49d0824eefb18"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ac032d233a8ebfcd82fd49d0824eefb18">◆ </a></span>FORCE_INLINE</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">#define FORCE_INLINE   static inline <a class="el" href="lru_8c.html#a8c8313d05785802938c6d8a2a7fa3e09">__attribute__</a>((always_inline))</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="decls_8h_source.html#l00063">63</a> of file <a class="el" href="decls_8h_source.html">decls.h</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="lru_8c_source.html#l00071">__attribute__()</a>, and <a class="el" href="md5_8c_source.html#l00162">md5_process_block_loaded()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
|
||
<a id="a033bfc0dd219563f45b7e5c85dd5d3fa" name="a033bfc0dd219563f45b7e5c85dd5d3fa"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a033bfc0dd219563f45b7e5c85dd5d3fa">◆ </a></span>aaruf_cd_lba_to_msf()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_cd_lba_to_msf </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const int64_t</td> <td class="paramname"><span class="paramname"><em>pos</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>minute</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>second</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>frame</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Converts a CD LBA (Logical Block Address) to MSF (Minute:Second:Frame) format. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">pos</td><td>LBA position. </td></tr>
|
||
<tr><td class="paramname">minute</td><td>Pointer to store the minute value. </td></tr>
|
||
<tr><td class="paramname">second</td><td>Pointer to store the second value. </td></tr>
|
||
<tr><td class="paramname">frame</td><td>Pointer to store the frame value. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00370">370</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="ecc__cd_8c_source.html#l00388">aaruf_ecc_cd_reconstruct_prefix()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a6823e139f81a9dfd08efcb0e9b213a49" name="a6823e139f81a9dfd08efcb0e9b213a49"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a6823e139f81a9dfd08efcb0e9b213a49">◆ </a></span>aaruf_close()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int aaruf_close </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>Close an Aaru image context, flushing pending data structures and releasing resources. </p>
|
||
<p>Public API entry point used to finalize an image being written or simply dispose of a context opened for reading. For write-mode contexts (ctx->isWriting true) the function performs the following ordered steps:</p><ol type="1">
|
||
<li>Rewrite the (possibly updated) main header at offset 0.</li>
|
||
<li>Close any open data block via <a class="el" href="internal_8h.html#a2402812f5e04ba16765208c0b70fa6c5" title="Finalizes and writes the current data block to the AaruFormat image file.">aaruf_close_current_block()</a>.</li>
|
||
<li>Flush a cached secondary DDT (multi-level) if pending.</li>
|
||
<li>Flush either the primary DDT (multi-level) or the single-level DDT table.</li>
|
||
<li>Finalize and append checksum block(s) for all enabled algorithms.</li>
|
||
<li>Write auxiliary metadata blocks: tracks, MODE 2 subheaders, sector prefix.</li>
|
||
<li>Serialize the global index and patch header.indexOffset.</li>
|
||
<li>Clear deduplication hash map if used.</li>
|
||
</ol>
|
||
<p>Afterwards (or for read-mode contexts) all dynamically allocated buffers, arrays, hash tables and mapping structures are freed/unmapped. Media tags are removed from their hash table.</p>
|
||
<p>Error Handling:</p><ul>
|
||
<li>Returns -1 with errno = EINVAL if the provided pointer is NULL or not a valid context.</li>
|
||
<li>Returns -1 with errno set to AARUF_ERROR_CANNOT_WRITE_HEADER if a header write fails.</li>
|
||
<li>If any intermediate serialization helper returns an error status, that error value is propagated (converted to -1 with errno set accordingly by the caller if desired). In the current implementation <a class="el" href="close_8c.html#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> directly returns the negative error code for helper failures to preserve detail.</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Opaque pointer returned by earlier open/create calls (must be an aaruformatContext). </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>0 on success; -1 or negative libaaruformat error code on failure. </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">0</td><td>All pending data flushed (if writing) and resources released successfully. </td></tr>
|
||
<tr><td class="paramname">-1</td><td>Invalid context pointer or initial header rewrite failure (errno = EINVAL or AARUF_ERROR_CANNOT_WRITE_HEADER). </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_WRITE_HEADER</td><td>A later write helper (e.g., index, DDT) failed and returned this code directly. </td></tr>
|
||
<tr><td class="paramname"><other</td><td>negative libaaruformat code> Propagated from a write helper if future helpers add more error codes. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>On success the context memory itself is freed; the caller must not reuse the pointer. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="close_8c_source.html#l03995">3995</a> of file <a class="el" href="close_8c_source.html">close.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="errors_8h_source.html#l00060">AARUF_ERROR_CANNOT_WRITE_HEADER</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00269">aaruformat_context::checksums</a>, <a class="el" href="context_8h_source.html#l00214">aaruformat_context::cicm_block</a>, <a class="el" href="context_8h_source.html#l00120">mediaTagEntry::data</a>, <a class="el" href="context_8h_source.html#l00298">aaruformat_context::deduplicate</a>, <a class="el" href="context_8h_source.html#l00212">aaruformat_context::dump_hardware_entries_with_data</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::dump_hardware_header</a>, <a class="el" href="context_8h_source.html#l00248">aaruformat_context::ecc_cd_context</a>, <a class="el" href="dump_8h_source.html#l00093">DumpHardwareHeader::entries</a>, <a class="el" href="context_8h_source.html#l00316">DumpHardwareEntriesWithData::extents</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00320">DumpHardwareEntriesWithData::firmware</a>, <a class="el" href="hash__map_8c_source.html#l00073">free_map()</a>, <a class="el" href="context_8h_source.html#l00175">aaruformat_context::header</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="context_8h_source.html#l00196">aaruformat_context::in_memory_ddt</a>, <a class="el" href="context_8h_source.html#l00252">aaruformat_context::index_entries</a>, <a class="el" href="context_8h_source.html#l00304">aaruformat_context::is_tape</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00317">DumpHardwareEntriesWithData::manufacturer</a>, <a class="el" href="context_8h_source.html#l00193">aaruformat_context::mapped_memory_ddt_size</a>, <a class="el" href="context_8h_source.html#l00264">aaruformat_context::mediaTags</a>, <a class="el" href="context_8h_source.html#l00213">aaruformat_context::metadata_block</a>, <a class="el" href="context_8h_source.html#l00204">aaruformat_context::mode2_subheaders</a>, <a class="el" href="context_8h_source.html#l00318">DumpHardwareEntriesWithData::model</a>, <a class="el" href="context_8h_source.html#l00263">aaruformat_context::readableSectorTags</a>, <a class="el" href="context_8h_source.html#l00319">DumpHardwareEntriesWithData::revision</a>, <a class="el" href="context_8h_source.html#l00207">aaruformat_context::sector_cpr_mai</a>, <a class="el" href="context_8h_source.html#l00208">aaruformat_context::sector_edc</a>, <a class="el" href="context_8h_source.html#l00253">aaruformat_context::sector_hash_map</a>, <a class="el" href="context_8h_source.html#l00205">aaruformat_context::sector_id</a>, <a class="el" href="context_8h_source.html#l00206">aaruformat_context::sector_ied</a>, <a class="el" href="context_8h_source.html#l00199">aaruformat_context::sector_prefix</a>, <a class="el" href="context_8h_source.html#l00200">aaruformat_context::sector_prefix_corrected</a>, <a class="el" href="context_8h_source.html#l00183">aaruformat_context::sector_prefix_ddt</a>, <a class="el" href="context_8h_source.html#l00185">aaruformat_context::sector_prefix_ddt2</a>, <a class="el" href="context_8h_source.html#l00203">aaruformat_context::sector_subchannel</a>, <a class="el" href="context_8h_source.html#l00201">aaruformat_context::sector_suffix</a>, <a class="el" href="context_8h_source.html#l00202">aaruformat_context::sector_suffix_corrected</a>, <a class="el" href="context_8h_source.html#l00184">aaruformat_context::sector_suffix_ddt</a>, <a class="el" href="context_8h_source.html#l00186">aaruformat_context::sector_suffix_ddt2</a>, <a class="el" href="context_8h_source.html#l00321">DumpHardwareEntriesWithData::serial</a>, <a class="el" href="context_8h_source.html#l00322">DumpHardwareEntriesWithData::softwareName</a>, <a class="el" href="context_8h_source.html#l00324">DumpHardwareEntriesWithData::softwareOperatingSystem</a>, <a class="el" href="context_8h_source.html#l00323">DumpHardwareEntriesWithData::softwareVersion</a>, <a class="el" href="context_8h_source.html#l00110">Checksums::spamsum</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="context_8h_source.html#l00242">aaruformat_context::track_entries</a>, <a class="el" href="context_8h_source.html#l00181">aaruformat_context::user_data_ddt</a>, <a class="el" href="close_8c_source.html#l03812">write_aaru_json_block()</a>, <a class="el" href="close_8c_source.html#l00077">write_cached_secondary_ddt()</a>, <a class="el" href="close_8c_source.html#l00654">write_checksum_block()</a>, <a class="el" href="close_8c_source.html#l03675">write_cicm_block()</a>, <a class="el" href="close_8c_source.html#l03445">write_dumphw_block()</a>, <a class="el" href="close_8c_source.html#l01808">write_dvd_long_sector_blocks()</a>, <a class="el" href="close_8c_source.html#l02245">write_dvd_title_key_decrypted_block()</a>, <a class="el" href="close_8c_source.html#l03026">write_geometry_block()</a>, <a class="el" href="close_8c_source.html#l03862">write_index_block()</a>, <a class="el" href="close_8c_source.html#l02409">write_media_tags()</a>, <a class="el" href="close_8c_source.html#l03162">write_metadata_block()</a>, <a class="el" href="close_8c_source.html#l00850">write_mode2_subheaders_block()</a>, <a class="el" href="close_8c_source.html#l00283">write_primary_ddt()</a>, <a class="el" href="close_8c_source.html#l00966">write_sector_prefix()</a>, <a class="el" href="close_8c_source.html#l01206">write_sector_prefix_ddt()</a>, <a class="el" href="close_8c_source.html#l01508">write_sector_subchannel()</a>, <a class="el" href="close_8c_source.html#l01088">write_sector_suffix()</a>, <a class="el" href="close_8c_source.html#l01350">write_sector_suffix_ddt()</a>, <a class="el" href="close_8c_source.html#l00369">write_single_level_ddt()</a>, <a class="el" href="close_8c_source.html#l00596">write_tape_ddt()</a>, <a class="el" href="close_8c_source.html#l02669">write_tape_file_block()</a>, <a class="el" href="close_8c_source.html#l02901">write_tape_partition_block()</a>, <a class="el" href="close_8c_source.html#l00798">write_tracks_block()</a>, and <a class="el" href="context_8h_source.html#l00280">aaruformat_context::writing_buffer</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="open_8c_source.html#l00125">aaruf_open()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a0fee4834bf0747bcd933c4e754aa4692" name="a0fee4834bf0747bcd933c4e754aa4692"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a0fee4834bf0747bcd933c4e754aa4692">◆ </a></span>aaruf_crc64_data()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">uint64_t aaruf_crc64_data </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">uint32_t</td> <td class="paramname"><span class="paramname"><em>len</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="crc64_8c_source.html#l00160">160</a> of file <a class="el" href="crc64_8c_source.html">crc64.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="crc64_8c_source.html#l00141">aaruf_crc64_final()</a>, <a class="el" href="crc64_8c_source.html#l00155">aaruf_crc64_free()</a>, <a class="el" href="crc64_8c_source.html#l00032">aaruf_crc64_init()</a>, and <a class="el" href="crc64_8c_source.html#l00055">aaruf_crc64_update()</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="dump_8c_source.html#l00186">aaruf_get_dumphw()</a>, <a class="el" href="dump_8c_source.html#l00531">aaruf_set_dumphw()</a>, <a class="el" href="optical_8c_source.html#l00392">aaruf_set_tracks()</a>, <a class="el" href="data_8c_source.html#l00071">process_data_block()</a>, <a class="el" href="blocks_2dump_8c_source.html#l00108">process_dumphw_block()</a>, <a class="el" href="tape_8c_source.html#l00126">process_tape_files_block()</a>, <a class="el" href="tape_8c_source.html#l00346">process_tape_partitions_block()</a>, <a class="el" href="optical_8c_source.html#l00111">process_tracks_block()</a>, <a class="el" href="ddt__v2_8c_source.html#l01092">set_ddt_multi_level_v2()</a>, <a class="el" href="index__v1_8c_source.html#l00225">verify_index_v1()</a>, <a class="el" href="close_8c_source.html#l00077">write_cached_secondary_ddt()</a>, <a class="el" href="close_8c_source.html#l03445">write_dumphw_block()</a>, <a class="el" href="close_8c_source.html#l01808">write_dvd_long_sector_blocks()</a>, <a class="el" href="close_8c_source.html#l02245">write_dvd_title_key_decrypted_block()</a>, <a class="el" href="close_8c_source.html#l02409">write_media_tags()</a>, <a class="el" href="close_8c_source.html#l00850">write_mode2_subheaders_block()</a>, <a class="el" href="close_8c_source.html#l00966">write_sector_prefix()</a>, <a class="el" href="close_8c_source.html#l01206">write_sector_prefix_ddt()</a>, <a class="el" href="close_8c_source.html#l01508">write_sector_subchannel()</a>, <a class="el" href="close_8c_source.html#l01088">write_sector_suffix()</a>, <a class="el" href="close_8c_source.html#l01350">write_sector_suffix_ddt()</a>, <a class="el" href="close_8c_source.html#l00369">write_single_level_ddt()</a>, <a class="el" href="close_8c_source.html#l02669">write_tape_file_block()</a>, and <a class="el" href="close_8c_source.html#l02901">write_tape_partition_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ae48cfb59c6585e9ffd4cd1a97044891f" name="ae48cfb59c6585e9ffd4cd1a97044891f"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ae48cfb59c6585e9ffd4cd1a97044891f">◆ </a></span>aaruf_crc64_final()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int aaruf_crc64_final </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>crc</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Computes the final CRC64 value from the context. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">ctx</td><td>Pointer to the CRC64 context. </td></tr>
|
||
<tr><td class="paramname">crc</td><td>Pointer to store the resulting CRC64 value. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="crc64_8c_source.html#l00141">141</a> of file <a class="el" href="crc64_8c_source.html">crc64.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="crc64_8h_source.html#l00057">crc64_ctx::crc</a>, and <a class="el" href="crc64_8h_source.html#l00280">CRC64_ECMA_SEED</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="verify_8c_source.html#l00130">aaruf_verify_image()</a>, <a class="el" href="ddt__v2_8c_source.html#l00724">decode_ddt_multi_level_v2()</a>, <a class="el" href="ddt__v2_8c_source.html#l00096">process_ddt_v2()</a>, <a class="el" href="ddt__v2_8c_source.html#l01092">set_ddt_multi_level_v2()</a>, <a class="el" href="index__v2_8c_source.html#l00227">verify_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00408">verify_index_v3()</a>, <a class="el" href="close_8c_source.html#l00077">write_cached_secondary_ddt()</a>, <a class="el" href="close_8c_source.html#l03862">write_index_block()</a>, and <a class="el" href="close_8c_source.html#l00283">write_primary_ddt()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a4943569a8623eb2e3e0adc276c433097" name="a4943569a8623eb2e3e0adc276c433097"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a4943569a8623eb2e3e0adc276c433097">◆ </a></span>aaruf_crc64_free()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_crc64_free </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Frees a CRC64 context. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">ctx</td><td>Pointer to the CRC64 context to free. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="crc64_8c_source.html#l00155">155</a> of file <a class="el" href="crc64_8c_source.html">crc64.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, and <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="verify_8c_source.html#l00130">aaruf_verify_image()</a>, <a class="el" href="index__v2_8c_source.html#l00227">verify_index_v2()</a>, and <a class="el" href="index__v3_8c_source.html#l00408">verify_index_v3()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a66567ca64e31a687d4982cb254b45196" name="a66567ca64e31a687d4982cb254b45196"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a66567ca64e31a687d4982cb254b45196">◆ </a></span>aaruf_crc64_init()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname"><a class="el" href="structcrc64__ctx.html">crc64_ctx</a> * aaruf_crc64_init </td>
|
||
<td>(</td>
|
||
<td class="paramtype">void</td> <td class="paramname"><span class="paramname"><em></em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Initializes a CRC64 context. </p>
|
||
<p>Allocates and initializes a CRC64 context for checksum calculations.</p>
|
||
<dl class="section return"><dt>Returns</dt><dd>Pointer to the initialized <a class="el" href="structcrc64__ctx.html" title="Minimal ECMA-182 CRC64 incremental state container (running value only).">crc64_ctx</a> structure, or NULL on failure. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="crc64_8c_source.html#l00032">32</a> of file <a class="el" href="crc64_8c_source.html">crc64.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="crc64_8h_source.html#l00057">crc64_ctx::crc</a>, <a class="el" href="crc64_8h_source.html#l00280">CRC64_ECMA_SEED</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="verify_8c_source.html#l00130">aaruf_verify_image()</a>, <a class="el" href="ddt__v2_8c_source.html#l00724">decode_ddt_multi_level_v2()</a>, <a class="el" href="ddt__v2_8c_source.html#l00096">process_ddt_v2()</a>, <a class="el" href="ddt__v2_8c_source.html#l01092">set_ddt_multi_level_v2()</a>, <a class="el" href="index__v2_8c_source.html#l00227">verify_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00408">verify_index_v3()</a>, <a class="el" href="close_8c_source.html#l00077">write_cached_secondary_ddt()</a>, <a class="el" href="close_8c_source.html#l03862">write_index_block()</a>, and <a class="el" href="close_8c_source.html#l00283">write_primary_ddt()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a83ecd1f5636915aebacfd29fc6306520" name="a83ecd1f5636915aebacfd29fc6306520"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a83ecd1f5636915aebacfd29fc6306520">◆ </a></span>aaruf_crc64_slicing()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_crc64_slicing </td>
|
||
<td>(</td>
|
||
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>previous_crc</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">uint32_t</td> <td class="paramname"><span class="paramname"><em>len</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Updates a CRC64 value using the slicing-by-8 algorithm. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">previous_crc</td><td>Pointer to the previous CRC64 value (input/output). </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the data buffer. </td></tr>
|
||
<tr><td class="paramname">len</td><td>Length of the data buffer in bytes. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="crc64_8c_source.html#l00102">102</a> of file <a class="el" href="crc64_8c_source.html">crc64.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, and <a class="el" href="crc64_8h_source.html#l00066">crc64_table</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="crc64_8c_source.html#l00055">aaruf_crc64_update()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a1fb4423a841ccd728e3ad0d028cbc9b4" name="a1fb4423a841ccd728e3ad0d028cbc9b4"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a1fb4423a841ccd728e3ad0d028cbc9b4">◆ </a></span>aaruf_crc64_update()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int aaruf_crc64_update </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</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">uint32_t</td> <td class="paramname"><span class="paramname"><em>len</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Updates the CRC64 context with new data. </p>
|
||
<p>Processes the given data buffer and updates the CRC64 value in the context.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">ctx</td><td>Pointer to the CRC64 context. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the data buffer. </td></tr>
|
||
<tr><td class="paramname">len</td><td>Length of the data buffer. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>0 on success, or -1 on error. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="crc64_8c_source.html#l00055">55</a> of file <a class="el" href="crc64_8c_source.html">crc64.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="crc64_8c_source.html#l00102">aaruf_crc64_slicing()</a>, <a class="el" href="crc64_8h_source.html#l00057">crc64_ctx::crc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="ddt__v2_8c_source.html#l00724">decode_ddt_multi_level_v2()</a>, <a class="el" href="ddt__v2_8c_source.html#l00096">process_ddt_v2()</a>, <a class="el" href="ddt__v2_8c_source.html#l01092">set_ddt_multi_level_v2()</a>, <a class="el" href="verify_8c_source.html#l00030">update_crc64_from_stream()</a>, <a class="el" href="index__v2_8c_source.html#l00227">verify_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00408">verify_index_v3()</a>, <a class="el" href="close_8c_source.html#l00077">write_cached_secondary_ddt()</a>, <a class="el" href="close_8c_source.html#l03862">write_index_block()</a>, and <a class="el" href="close_8c_source.html#l00283">write_primary_ddt()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a7065a9fefcaabfecc4184528f01ef013" name="a7065a9fefcaabfecc4184528f01ef013"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a7065a9fefcaabfecc4184528f01ef013">◆ </a></span>aaruf_create()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void * aaruf_create </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>filepath</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>media_type</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>sector_size</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>user_sectors</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>negative_sectors</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>overflow_sectors</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>options</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>application_name</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>application_name_length</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>application_major_version</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>application_minor_version</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const bool</td> <td class="paramname"><span class="paramname"><em>is_tape</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Creates a new AaruFormat image file. </p>
|
||
<p>Allocates and initializes a new aaruformat context and image file with the specified parameters. This function sets up all necessary data structures including headers, DDT (deduplication table), caches, and index entries for writing a new AaruFormat image. It also handles file creation, memory allocation, and proper initialization of the writing context. The function supports both block-based media (disks, optical media) and sequential tape media with different initialization strategies optimized for each media type.</p>
|
||
<p><b>Media Type Handling:</b> The function creates different internal structures based on the <span class="tt">is_tape</span> parameter:</p>
|
||
<p><b>Block Media (is_tape = false):</b></p><ul>
|
||
<li>Initializes full DDT (Deduplication Table) version 2 for sector-level deduplication</li>
|
||
<li>Allocates primary DDT table (userDataDdtMini or userDataDdtBig) as a preallocated array</li>
|
||
<li>Configures multi-level DDT support for large images (> 138,412,552 sectors)</li>
|
||
<li>Enables optional deduplication hash map for detecting duplicate sectors</li>
|
||
<li>Reserves space for DDT at the beginning of the file (after header, block-aligned)</li>
|
||
<li>Data blocks start after DDT table to maintain sequential layout</li>
|
||
<li>DDT size is fixed and known upfront based on sector count</li>
|
||
</ul>
|
||
<p><b>Tape Media (is_tape = true):</b></p><ul>
|
||
<li>Initializes DDT for sector-level deduplication using a different strategy</li>
|
||
<li>Uses a growing hash table (tapeDdt) instead of a preallocated array</li>
|
||
<li>Sets ctx->is_tape flag and initializes ctx->tapeDdt to NULL (populated on first write)</li>
|
||
<li>Data blocks start immediately after the header (block-aligned)</li>
|
||
<li>Hash table grows dynamically as blocks are written</li>
|
||
<li>Optimized for sequential write patterns typical of tape media</li>
|
||
<li>Tape file/partition metadata is managed separately via additional hash tables</li>
|
||
<li>More memory-efficient for tapes with unknown final size</li>
|
||
</ul>
|
||
<p><b>Initialization Flow:</b></p><ol type="1">
|
||
<li>Parse creation options (compression, alignment, deduplication, checksums)</li>
|
||
<li>Allocate and zero-initialize context structure</li>
|
||
<li>Create/open image file in binary write mode</li>
|
||
<li>Initialize AaruFormat header with application and version information</li>
|
||
<li>Set up image metadata and sector size information</li>
|
||
<li>Initialize block and header caches for performance</li>
|
||
<li>Initialize ECC context for Compact Disc support</li>
|
||
<li>Branch based on media type:<ul>
|
||
<li>Block media: Configure DDT structures and calculate offsets with preallocated array</li>
|
||
<li>Tape media: Set tape flags and initialize for dynamic hash table DDT</li>
|
||
</ul>
|
||
</li>
|
||
<li>Initialize index entries array for tracking all blocks</li>
|
||
<li>Configure compression, checksums, and deduplication based on options</li>
|
||
<li>Position file pointer at calculated data start position</li>
|
||
</ol>
|
||
<p><b>DDT Configuration (Block Media Only):</b> The function automatically selects optimal DDT parameters:</p><ul>
|
||
<li>Single-level DDT (tableShift=0): For images < 138,412,552 sectors</li>
|
||
<li>Multi-level DDT (tableShift=22): For images ≥ 138,412,552 sectors</li>
|
||
</ul>
|
||
<p>The DDT offset calculation ensures proper alignment:</p><ul>
|
||
<li>Primary DDT placed immediately after header (block-aligned)</li>
|
||
<li>Data blocks positioned after DDT table (block-aligned)</li>
|
||
<li>Alignment controlled by blockAlignmentShift from options</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">filepath</td><td>Path to the image file to create. The file will be created if it doesn't exist, or overwritten if it does. Must be a valid writable path.</td></tr>
|
||
<tr><td class="paramname">media_type</td><td>Media type identifier (e.g., CompactDisc, DVD, HardDisk, Tape formats). This affects how the image is structured and which features are enabled.</td></tr>
|
||
<tr><td class="paramname">sector_size</td><td>Size of each sector/block in bytes. Common values:<ul>
|
||
<li>512 bytes: Hard disks, floppy disks</li>
|
||
<li>2048 bytes: CD-ROM, DVD</li>
|
||
<li>Variable: Tape media (block size varies by format)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">user_sectors</td><td>Number of user data sectors/blocks in the image. This is the main data area excluding negative (lead-in) and overflow (lead-out) regions. For tape media, this may be an estimate as the final size is often unknown.</td></tr>
|
||
<tr><td class="paramname">negative_sectors</td><td>Number of negative sectors (typically lead-in area for optical media). Set to 0 for media types without lead-in areas. Not used for tape media.</td></tr>
|
||
<tr><td class="paramname">overflow_sectors</td><td>Number of overflow sectors (typically lead-out area for optical media). Set to 0 for media types without lead-out areas. Not used for tape media.</td></tr>
|
||
<tr><td class="paramname">options</td><td>String with creation options in key=value format, semicolon-separated. Supported options:<ul>
|
||
<li>"compress=true|false": Enable/disable LZMA compression</li>
|
||
<li>"deduplicate=true|false": Enable/disable sector deduplication (all media types)</li>
|
||
<li>"md5=true|false": Calculate MD5 checksum during write</li>
|
||
<li>"sha1=true|false": Calculate SHA-1 checksum during write</li>
|
||
<li>"sha256=true|false": Calculate SHA-256 checksum during write</li>
|
||
<li>"spamsum=true|false": Calculate SpamSum fuzzy hash during write</li>
|
||
<li>"blake3=true|false": Calculate BLAKE3 checksum during write</li>
|
||
<li>"block_alignment=N": Block alignment shift value (default varies)</li>
|
||
<li>"data_shift=N": Data shift value for DDT granularity</li>
|
||
<li>"table_shift=N": Table shift for multi-level DDT (-1 for auto, block media only)</li>
|
||
<li>"dictionary=N": LZMA dictionary size in bytes Example: "compress=true;deduplicate=true;md5=true;sha1=true"</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">application_name</td><td>Pointer to the application name string (UTF-8 encoded). This identifies the software that created the image. The string will be copied directly to the image header.</td></tr>
|
||
<tr><td class="paramname">application_name_length</td><td>Length of the application name string in bytes. Must be ≤ AARU_HEADER_APP_NAME_LEN (64 bytes).</td></tr>
|
||
<tr><td class="paramname">application_major_version</td><td>Major version of the creating application (0-255).</td></tr>
|
||
<tr><td class="paramname">application_minor_version</td><td>Minor version of the creating application (0-255).</td></tr>
|
||
<tr><td class="paramname">is_tape</td><td>Boolean flag indicating tape media type:<ul>
|
||
<li>true: Initialize for tape media (sequential, dynamic hash table DDT, file/partition metadata)</li>
|
||
<li>false: Initialize for block media (random access, preallocated array DDT)</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">aaruformatContext*</td><td>Successfully created and initialized context. The returned pointer contains:<ul>
|
||
<li>Properly initialized AaruFormat headers and metadata</li>
|
||
<li>For block media: Allocated and configured DDT structures with preallocated arrays</li>
|
||
<li>For tape media: Tape flags set, DDT initialized as NULL (grows on demand)</li>
|
||
<li>Initialized block and header caches for performance</li>
|
||
<li>Open file stream ready for writing operations</li>
|
||
<li>Index entries array ready for block tracking</li>
|
||
<li>ECC context initialized for Compact Disc support</li>
|
||
<li>Checksum contexts initialized based on options</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">NULL</td><td>Creation failed. The specific error can be determined by checking errno, which will be set to:<ul>
|
||
<li>AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) when memory allocation fails for:<ul>
|
||
<li>Context allocation</li>
|
||
<li>Readable sector tags array allocation</li>
|
||
<li>Application version string allocation</li>
|
||
<li>Image version string allocation</li>
|
||
<li>DDT table allocation (userDataDdtMini or userDataDdtBig, block media only)</li>
|
||
<li>Index entries array allocation</li>
|
||
</ul>
|
||
</li>
|
||
<li>AARUF_ERROR_CANNOT_CREATE_FILE (-19) when file operations fail:<ul>
|
||
<li>Unable to open the specified filepath for writing</li>
|
||
<li>File seek operations fail during initialization</li>
|
||
<li>File system errors or permission issues</li>
|
||
</ul>
|
||
</li>
|
||
<li>AARUF_ERROR_INVALID_APP_NAME_LENGTH (-20) when:<ul>
|
||
<li>application_name_length exceeds AARU_HEADER_APP_NAME_LEN (64 bytes)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Memory Management:<ul>
|
||
<li>The function performs extensive memory allocation for various context structures</li>
|
||
<li>On failure, all previously allocated memory is properly cleaned up</li>
|
||
<li>The returned context must be freed using <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> when finished</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
File Operations:<ul>
|
||
<li>Creates a new file at the specified path (overwrites existing files)</li>
|
||
<li>Opens the file in binary read/write mode ("wb+")</li>
|
||
<li>Positions the file pointer at the calculated data start position</li>
|
||
<li>File alignment is handled based on parsed options</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
DDT Initialization (Block Media Only):<ul>
|
||
<li>Uses DDT version 2 format with configurable compression and alignment</li>
|
||
<li>Calculates optimal table sizes based on sector counts and shift parameters</li>
|
||
<li>All DDT entries are initialized to zero (indicating unallocated sectors)</li>
|
||
<li>Multi-level DDT is used for images with ≥ 138,412,552 total sectors</li>
|
||
<li>Single-level DDT is used for smaller images for efficiency</li>
|
||
<li>DDT is a fixed-size preallocated array written to file at known offset</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Tape Media Initialization:<ul>
|
||
<li>Tape images use a dynamic hash table DDT for sector-level deduplication</li>
|
||
<li>File and partition metadata is managed via separate hash tables</li>
|
||
<li>ctx->is_tape is set to 1 to indicate tape mode throughout the library</li>
|
||
<li>ctx->tapeDdt is initialized to NULL and grows dynamically as blocks are written</li>
|
||
<li>Data blocks can start immediately after header for optimal sequential access</li>
|
||
<li>The hash table DDT allows for efficient deduplication without knowing final size</li>
|
||
<li>More memory-efficient for tapes with unpredictable or very large sizes</li>
|
||
<li>Deduplication hash map may still be used alongside tapeDdt if enabled in options</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Options Parsing:<ul>
|
||
<li>The options string is parsed to extract block_alignment, data_shift, and table_shift</li>
|
||
<li>These parameters affect memory usage, performance, and file organization</li>
|
||
<li>Invalid options may result in suboptimal performance but won't cause failure</li>
|
||
<li>Compression and checksums can be enabled independently via options</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Checksum Initialization:<ul>
|
||
<li>MD5, SHA-1, SHA-256, SpamSum, and BLAKE3 can be calculated during write</li>
|
||
<li>Checksum contexts are initialized only if requested in options</li>
|
||
<li><a class="el" href="structChecksums.html" title="Collected whole‑image checksums / hashes present in a checksum block.">Checksums</a> are computed incrementally as sectors/blocks are written</li>
|
||
<li>Final checksums are stored in checksum block during image finalization</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The created context is in writing mode and expects proper finalization before closing to ensure index and metadata are written correctly.</dd>
|
||
<dd>
|
||
Application name length validation is strict - exceeding the limit will cause creation failure with AARUF_ERROR_INVALID_APP_NAME_LENGTH.</dd>
|
||
<dd>
|
||
For tape media, the DDT structure is fundamentally different (hash table vs array). The is_tape flag must accurately reflect the media type being created.</dd>
|
||
<dd>
|
||
The negative_sectors and overflow_sectors parameters are used only for block media. For tape media, these parameters are ignored.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> for proper context cleanup and image finalization </dd>
|
||
<dd>
|
||
<a class="el" href="#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> for writing sectors to block media images </dd>
|
||
<dd>
|
||
<a class="el" href="#a01c915ab49a4b47fd6768a2055208c48" title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> for defining tape file metadata </dd>
|
||
<dd>
|
||
<a class="el" href="#a9daeeb54c74dd2707d95ab47e8ab0a00" title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> for defining tape partition metadata </dd></dl>
|
||
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="create_8c_source.html#l00279">279</a> of file <a class="el" href="create_8c_source.html">create.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="header_8h_source.html#l00059">AARU_HEADER_APP_NAME_LEN</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="ecc__cd_8c_source.html#l00035">aaruf_ecc_cd_init()</a>, <a class="el" href="errors_8h_source.html#l00058">AARUF_ERROR_CANNOT_CREATE_FILE</a>, <a class="el" href="errors_8h_source.html#l00059">AARUF_ERROR_INVALID_APP_NAME_LENGTH</a>, <a class="el" href="errors_8h_source.html#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="helpers_8c_source.html#l00339">aaruf_get_xml_mediatype()</a>, <a class="el" href="md5_8c_source.html#l00425">aaruf_md5_init()</a>, <a class="el" href="sha1_8c_source.html#l00034">aaruf_sha1_init()</a>, <a class="el" href="sha256_8c_source.html#l00076">aaruf_sha256_init()</a>, <a class="el" href="spamsum_8c_source.html#l00037">aaruf_spamsum_init()</a>, <a class="el" href="consts_8h_source.html#l00075">AARUF_VERSION_V2</a>, <a class="el" href="aaru_8h_source.html#l00877">ImageInfo::Application</a>, <a class="el" href="header_8h_source.html#l00109">AaruHeaderV2::application</a>, <a class="el" href="header_8h_source.html#l00112">AaruHeaderV2::applicationMajorVersion</a>, <a class="el" href="header_8h_source.html#l00113">AaruHeaderV2::applicationMinorVersion</a>, <a class="el" href="aaru_8h_source.html#l00878">ImageInfo::ApplicationVersion</a>, <a class="el" href="options_8h_source.html#l00228">aaru_options::blake3</a>, <a class="el" href="context_8h_source.html#l00268">aaruformat_context::blake3_context</a>, <a class="el" href="options_8h_source.html#l00224">aaru_options::block_alignment</a>, <a class="el" href="context_8h_source.html#l00257">aaruformat_context::block_cache</a>, <a class="el" href="context_8h_source.html#l00256">aaruformat_context::block_header_cache</a>, <a class="el" href="ddt_8h_source.html#l00154">DdtHeader2::blockAlignmentShift</a>, <a class="el" href="ddt_8h_source.html#l00150">DdtHeader2::blocks</a>, <a class="el" href="lru_8h_source.html#l00048">CacheHeader::cache</a>, <a class="el" href="context_8h_source.html#l00277">aaruformat_context::calculating_blake3</a>, <a class="el" href="context_8h_source.html#l00273">aaruformat_context::calculating_md5</a>, <a class="el" href="context_8h_source.html#l00274">aaruformat_context::calculating_sha1</a>, <a class="el" href="context_8h_source.html#l00275">aaruformat_context::calculating_sha256</a>, <a class="el" href="context_8h_source.html#l00276">aaruformat_context::calculating_spamsum</a>, <a class="el" href="create_8c_source.html#l00030">cleanup_failed_create()</a>, <a class="el" href="options_8h_source.html#l00218">aaru_options::compress</a>, <a class="el" href="ddt_8h_source.html#l00145">DdtHeader2::compression</a>, <a class="el" href="context_8h_source.html#l00299">aaruformat_context::compression_enabled</a>, <a class="el" href="hash__map_8c_source.html#l00049">create_map()</a>, <a class="el" href="aaru_8h_source.html#l00879">ImageInfo::CreationTime</a>, <a class="el" href="header_8h_source.html#l00116">AaruHeaderV2::creationTime</a>, <a class="el" href="options_8h_source.html#l00223">aaru_options::data_shift</a>, <a class="el" href="ddt_8h_source.html#l00155">DdtHeader2::dataShift</a>, <a class="el" href="options_8h_source.html#l00219">aaru_options::deduplicate</a>, <a class="el" href="context_8h_source.html#l00298">aaruformat_context::deduplicate</a>, <a class="el" href="enums_8h_source.html#l00143">DeDuplicationTable2</a>, <a class="el" href="options_8h_source.html#l00221">aaru_options::dictionary</a>, <a class="el" href="context_8h_source.html#l00248">aaruformat_context::ecc_cd_context</a>, <a class="el" href="ddt_8h_source.html#l00158">DdtHeader2::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="time_8c_source.html#l00045">get_filetime_uint64()</a>, <a class="el" href="context_8h_source.html#l00175">aaruformat_context::header</a>, <a class="el" href="header_8h_source.html#l00108">AaruHeaderV2::identifier</a>, <a class="el" href="ddt_8h_source.html#l00143">DdtHeader2::identifier</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="header_8h_source.html#l00110">AaruHeaderV2::imageMajorVersion</a>, <a class="el" href="header_8h_source.html#l00111">AaruHeaderV2::imageMinorVersion</a>, <a class="el" href="aaru_8h_source.html#l00873">ImageInfo::ImageSize</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="context_8h_source.html#l00196">aaruformat_context::in_memory_ddt</a>, <a class="el" href="context_8h_source.html#l00252">aaruformat_context::index_entries</a>, <a class="el" href="header_8h_source.html#l00115">AaruHeaderV2::indexOffset</a>, <a class="el" href="context_8h_source.html#l00304">aaruformat_context::is_tape</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00283">aaruformat_context::last_written_block</a>, <a class="el" href="aaru_8h_source.html#l00880">ImageInfo::LastModificationTime</a>, <a class="el" href="header_8h_source.html#l00117">AaruHeaderV2::lastWrittenTime</a>, <a class="el" href="ddt_8h_source.html#l00146">DdtHeader2::levels</a>, <a class="el" href="aaruformat_8h_source.html#l00022">LIBAARUFORMAT_MAJOR_VERSION</a>, <a class="el" href="aaruformat_8h_source.html#l00023">LIBAARUFORMAT_MINOR_VERSION</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::library_major_version</a>, <a class="el" href="context_8h_source.html#l00178">aaruformat_context::library_minor_version</a>, <a class="el" href="context_8h_source.html#l00297">aaruformat_context::lzma_dict_size</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="consts_8h_source.html#l00079">MAX_CACHE_SIZE</a>, <a class="el" href="lru_8h_source.html#l00047">CacheHeader::max_items</a>, <a class="el" href="aaru_8h_source.html#l00916">MaxSectorTag</a>, <a class="el" href="options_8h_source.html#l00225">aaru_options::md5</a>, <a class="el" href="context_8h_source.html#l00270">aaruformat_context::md5_context</a>, <a class="el" href="aaru_8h_source.html#l00881">ImageInfo::MediaType</a>, <a class="el" href="header_8h_source.html#l00114">AaruHeaderV2::mediaType</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="context_8h_source.html#l00282">aaruformat_context::next_block_position</a>, <a class="el" href="enums_8h_source.html#l00033">None</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="options_8c_source.html#l00038">parse_options()</a>, <a class="el" href="ddt_8h_source.html#l00148">DdtHeader2::previousLevelOffset</a>, <a class="el" href="context_8h_source.html#l00192">aaruformat_context::primary_ddt_offset</a>, <a class="el" href="context_8h_source.html#l00263">aaruformat_context::readableSectorTags</a>, <a class="el" href="context_8h_source.html#l00293">aaruformat_context::rewinded</a>, <a class="el" href="context_8h_source.html#l00253">aaruformat_context::sector_hash_map</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="aaru_8h_source.html#l00875">ImageInfo::SectorSize</a>, <a class="el" href="options_8h_source.html#l00226">aaru_options::sha1</a>, <a class="el" href="context_8h_source.html#l00271">aaruformat_context::sha1_context</a>, <a class="el" href="options_8h_source.html#l00227">aaru_options::sha256</a>, <a class="el" href="context_8h_source.html#l00272">aaruformat_context::sha256_context</a>, <a class="el" href="context_8h_source.html#l00195">aaruformat_context::shift</a>, <a class="el" href="options_8h_source.html#l00229">aaru_options::spamsum</a>, <a class="el" href="context_8h_source.html#l00267">aaruformat_context::spamsum_context</a>, <a class="el" href="ddt_8h_source.html#l00153">DdtHeader2::start</a>, <a class="el" href="options_8h_source.html#l00222">aaru_options::table_shift</a>, <a class="el" href="ddt_8h_source.html#l00147">DdtHeader2::tableLevel</a>, <a class="el" href="ddt_8h_source.html#l00156">DdtHeader2::tableShift</a>, <a class="el" href="context_8h_source.html#l00182">aaruformat_context::tape_ddt</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="ddt_8h_source.html#l00144">DdtHeader2::type</a>, <a class="el" href="context_8h_source.html#l00187">aaruformat_context::user_data_ddt2</a>, <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>, <a class="el" href="enums_8h_source.html#l00046">UserData</a>, and <a class="el" href="aaru_8h_source.html#l00876">ImageInfo::Version</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a0b29337ce6fedc79bf7d1a84d92173d6" name="a0b29337ce6fedc79bf7d1a84d92173d6"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a0b29337ce6fedc79bf7d1a84d92173d6">◆ </a></span>aaruf_cst_transform()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_cst_transform </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>interleaved</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>sequential</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const size_t</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Transforms interleaved subchannel data to sequential format. </p>
|
||
<p>Converts interleaved subchannel data into a sequential format for further processing.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">interleaved</td><td>Pointer to the interleaved data buffer. </td></tr>
|
||
<tr><td class="paramname">sequential</td><td>Pointer to the output sequential data buffer. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Length of the data buffer. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>AARUF_STATUS_OK on success, or an error code on failure. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="cst_8c_source.html#l00035">35</a> of file <a class="el" href="cst_8c_source.html">cst.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, and <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="close_8c_source.html#l01508">write_sector_subchannel()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="adee4702d830dc13b78e0a6803658c40e" name="adee4702d830dc13b78e0a6803658c40e"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#adee4702d830dc13b78e0a6803658c40e">◆ </a></span>aaruf_cst_untransform()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_cst_untransform </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const uint8_t *</td> <td class="paramname"><span class="paramname"><em>sequential</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>interleaved</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const size_t</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reverses the CST (Claunia's Subchannel Transform) transformation from sequential to interleaved data. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">sequential</td><td>Pointer to the sequential data buffer. </td></tr>
|
||
<tr><td class="paramname">interleaved</td><td>Pointer to the output buffer for interleaved data. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Length of the data in bytes. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>AARUF_STATUS_OK on success, or an error code on failure. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="cst_8c_source.html#l00193">193</a> of file <a class="el" href="cst_8c_source.html">cst.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, and <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="data_8c_source.html#l00071">process_data_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a562bb88bbf499eac272182acb5528dea" name="a562bb88bbf499eac272182acb5528dea"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a562bb88bbf499eac272182acb5528dea">◆ </a></span>aaruf_ecc_cd_check()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">bool aaruf_ecc_cd_check </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>address</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 uint32_t</td> <td class="paramname"><span class="paramname"><em>major_count</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>minor_count</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>major_mult</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>minor_inc</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>ecc</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>address_offset</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>data_offset</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>ecc_offset</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Checks the ECC of a CD sector. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the ECC context. </td></tr>
|
||
<tr><td class="paramname">address</td><td>Pointer to the address field. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the data field. </td></tr>
|
||
<tr><td class="paramname">major_count</td><td>Number of major iterations. </td></tr>
|
||
<tr><td class="paramname">minor_count</td><td>Number of minor iterations. </td></tr>
|
||
<tr><td class="paramname">major_mult</td><td>Major multiplier. </td></tr>
|
||
<tr><td class="paramname">minor_inc</td><td>Minor increment. </td></tr>
|
||
<tr><td class="paramname">ecc</td><td>Pointer to the ECC field. </td></tr>
|
||
<tr><td class="paramname">address_offset</td><td>Offset for the address field. </td></tr>
|
||
<tr><td class="paramname">data_offset</td><td>Offset for the data field. </td></tr>
|
||
<tr><td class="paramname">ecc_offset</td><td>Offset for the ECC field. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>true if ECC is correct, false otherwise. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00227">227</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="context_8h_source.html#l00088">CdEccContext::ecc_b_table</a>, <a class="el" href="context_8h_source.html#l00089">CdEccContext::ecc_f_table</a>, <a class="el" href="context_8h_source.html#l00087">CdEccContext::inited_edc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="ecc__cd_8c_source.html#l00101">aaruf_ecc_cd_is_suffix_correct()</a>, and <a class="el" href="ecc__cd_8c_source.html#l00165">aaruf_ecc_cd_is_suffix_correct_mode2()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ac1a30bb251ac148f485c51593c0740c1" name="ac1a30bb251ac148f485c51593c0740c1"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ac1a30bb251ac148f485c51593c0740c1">◆ </a></span>aaruf_ecc_cd_init()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void * aaruf_ecc_cd_init </td>
|
||
<td>(</td>
|
||
<td class="paramname"><span class="paramname"><em></em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Initializes a Compact Disc ECC context. </p>
|
||
<p>Allocates and initializes a context for Compact Disc ECC calculations.</p>
|
||
<dl class="section return"><dt>Returns</dt><dd>Pointer to the initialized <a class="el" href="structCdEccContext.html" title="Lookup tables and state for Compact Disc EDC/ECC (P/Q) regeneration / verification.">CdEccContext</a> structure, or NULL on failure. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00035">35</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="context_8h_source.html#l00088">CdEccContext::ecc_b_table</a>, <a class="el" href="context_8h_source.html#l00089">CdEccContext::ecc_f_table</a>, <a class="el" href="context_8h_source.html#l00090">CdEccContext::edc_table</a>, <a class="el" href="context_8h_source.html#l00087">CdEccContext::inited_edc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>, and <a class="el" href="open_8c_source.html#l00125">aaruf_open()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="afbc09e16b1a654de04706e07c3212ecb" name="afbc09e16b1a654de04706e07c3212ecb"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#afbc09e16b1a654de04706e07c3212ecb">◆ </a></span>aaruf_ecc_cd_is_suffix_correct()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">bool aaruf_ecc_cd_is_suffix_correct </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>sector</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 1). </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the ECC context. </td></tr>
|
||
<tr><td class="paramname">sector</td><td>Pointer to the sector data. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>true if the suffix is correct, false otherwise. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00101">101</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="ecc__cd_8c_source.html#l00227">aaruf_ecc_cd_check()</a>, <a class="el" href="ecc__cd_8c_source.html#l00543">aaruf_edc_cd_compute()</a>, <a class="el" href="context_8h_source.html#l00087">CdEccContext::inited_edc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ab77ca170a2e8d2f0a2a7ea1a8a51690a" name="ab77ca170a2e8d2f0a2a7ea1a8a51690a"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ab77ca170a2e8d2f0a2a7ea1a8a51690a">◆ </a></span>aaruf_ecc_cd_is_suffix_correct_mode2()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">bool aaruf_ecc_cd_is_suffix_correct_mode2 </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>sector</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 2). </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the ECC context. </td></tr>
|
||
<tr><td class="paramname">sector</td><td>Pointer to the sector data. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>true if the suffix is correct, false otherwise. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00165">165</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="ecc__cd_8c_source.html#l00227">aaruf_ecc_cd_check()</a>, <a class="el" href="ecc__cd_8c_source.html#l00543">aaruf_edc_cd_compute()</a>, <a class="el" href="context_8h_source.html#l00087">CdEccContext::inited_edc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a9c9e2440119b8d7e67cb2c40125bf295" name="a9c9e2440119b8d7e67cb2c40125bf295"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a9c9e2440119b8d7e67cb2c40125bf295">◆ </a></span>aaruf_ecc_cd_reconstruct()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_ecc_cd_reconstruct </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>sector</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>type</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reconstructs the EDC and ECC fields of a CD sector. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the ECC context. </td></tr>
|
||
<tr><td class="paramname">sector</td><td>Pointer to the sector data (must be 2352 bytes). </td></tr>
|
||
<tr><td class="paramname">type</td><td>Track type (mode). </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00455">455</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="ecc__cd_8c_source.html#l00349">aaruf_ecc_cd_write_sector()</a>, <a class="el" href="ecc__cd_8c_source.html#l00543">aaruf_edc_cd_compute()</a>, <a class="el" href="enums_8h_source.html#l00197">CdMode1</a>, <a class="el" href="enums_8h_source.html#l00199">CdMode2Form1</a>, <a class="el" href="enums_8h_source.html#l00200">CdMode2Form2</a>, <a class="el" href="context_8h_source.html#l00087">CdEccContext::inited_edc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="read_8c_source.html#l00815">aaruf_read_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a73c3788f7376196abd596d6d846466b1" name="a73c3788f7376196abd596d6d846466b1"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a73c3788f7376196abd596d6d846466b1">◆ </a></span>aaruf_ecc_cd_reconstruct_prefix()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_ecc_cd_reconstruct_prefix </td>
|
||
<td>(</td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>sector</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>type</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const int64_t</td> <td class="paramname"><span class="paramname"><em>lba</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reconstructs the prefix (sync, address, mode) of a CD sector. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">sector</td><td>Pointer to the sector data (must be 2352 bytes). </td></tr>
|
||
<tr><td class="paramname">type</td><td>Track type (mode). </td></tr>
|
||
<tr><td class="paramname">lba</td><td>Logical Block Address. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00388">388</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="ecc__cd_8c_source.html#l00370">aaruf_cd_lba_to_msf()</a>, <a class="el" href="enums_8h_source.html#l00197">CdMode1</a>, <a class="el" href="enums_8h_source.html#l00199">CdMode2Form1</a>, <a class="el" href="enums_8h_source.html#l00200">CdMode2Form2</a>, <a class="el" href="enums_8h_source.html#l00198">CdMode2Formless</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="read_8c_source.html#l00815">aaruf_read_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a892f09f0b28f1183064eef6eb4d46f42" name="a892f09f0b28f1183064eef6eb4d46f42"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a892f09f0b28f1183064eef6eb4d46f42">◆ </a></span>aaruf_ecc_cd_write()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_ecc_cd_write </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>address</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 uint32_t</td> <td class="paramname"><span class="paramname"><em>major_count</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>minor_count</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>major_mult</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>minor_inc</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>ecc</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>address_offset</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>data_offset</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>ecc_offset</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Writes ECC for a CD sector. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the ECC context. </td></tr>
|
||
<tr><td class="paramname">address</td><td>Pointer to the address field. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the data field. </td></tr>
|
||
<tr><td class="paramname">major_count</td><td>Number of major iterations. </td></tr>
|
||
<tr><td class="paramname">minor_count</td><td>Number of minor iterations. </td></tr>
|
||
<tr><td class="paramname">major_mult</td><td>Major multiplier. </td></tr>
|
||
<tr><td class="paramname">minor_inc</td><td>Minor increment. </td></tr>
|
||
<tr><td class="paramname">ecc</td><td>Pointer to the ECC field to write. </td></tr>
|
||
<tr><td class="paramname">address_offset</td><td>Offset for the address field. </td></tr>
|
||
<tr><td class="paramname">data_offset</td><td>Offset for the data field. </td></tr>
|
||
<tr><td class="paramname">ecc_offset</td><td>Offset for the ECC field. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00292">292</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="context_8h_source.html#l00088">CdEccContext::ecc_b_table</a>, <a class="el" href="context_8h_source.html#l00089">CdEccContext::ecc_f_table</a>, <a class="el" href="context_8h_source.html#l00087">CdEccContext::inited_edc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="ecc__cd_8c_source.html#l00349">aaruf_ecc_cd_write_sector()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a322819729519cc5e0fcd625510158e18" name="a322819729519cc5e0fcd625510158e18"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a322819729519cc5e0fcd625510158e18">◆ </a></span>aaruf_ecc_cd_write_sector()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_ecc_cd_write_sector </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>address</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">uint8_t *</td> <td class="paramname"><span class="paramname"><em>ecc</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>address_offset</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>data_offset</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>ecc_offset</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Writes ECC for a full CD sector (both P and Q ECC). </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the ECC context. </td></tr>
|
||
<tr><td class="paramname">address</td><td>Pointer to the address field. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the data field. </td></tr>
|
||
<tr><td class="paramname">ecc</td><td>Pointer to the ECC field to write. </td></tr>
|
||
<tr><td class="paramname">address_offset</td><td>Offset for the address field. </td></tr>
|
||
<tr><td class="paramname">data_offset</td><td>Offset for the data field. </td></tr>
|
||
<tr><td class="paramname">ecc_offset</td><td>Offset for the ECC field. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00349">349</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="ecc__cd_8c_source.html#l00292">aaruf_ecc_cd_write()</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="ecc__cd_8c_source.html#l00455">aaruf_ecc_cd_reconstruct()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a67c65c3f2ca5cdf1596c16fa35558df1" name="a67c65c3f2ca5cdf1596c16fa35558df1"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a67c65c3f2ca5cdf1596c16fa35558df1">◆ </a></span>aaruf_edc_cd_compute()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">uint32_t aaruf_edc_cd_compute </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">uint32_t</td> <td class="paramname"><span class="paramname"><em>edc</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>src</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>size</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>pos</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Computes the EDC (Error Detection Code) for a CD sector. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the ECC context. </td></tr>
|
||
<tr><td class="paramname">edc</td><td>Initial EDC value. </td></tr>
|
||
<tr><td class="paramname">src</td><td>Pointer to the data to compute EDC over. </td></tr>
|
||
<tr><td class="paramname">size</td><td>Number of bytes to process. </td></tr>
|
||
<tr><td class="paramname">pos</td><td>Starting position in the data. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Computed EDC value. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="ecc__cd_8c_source.html#l00543">543</a> of file <a class="el" href="ecc__cd_8c_source.html">ecc_cd.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="context_8h_source.html#l00090">CdEccContext::edc_table</a>, <a class="el" href="context_8h_source.html#l00087">CdEccContext::inited_edc</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="ecc__cd_8c_source.html#l00101">aaruf_ecc_cd_is_suffix_correct()</a>, <a class="el" href="ecc__cd_8c_source.html#l00165">aaruf_ecc_cd_is_suffix_correct_mode2()</a>, <a class="el" href="ecc__cd_8c_source.html#l00455">aaruf_ecc_cd_reconstruct()</a>, and <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="af0ff6ad1495d50a8fa0ce0005be69471" name="af0ff6ad1495d50a8fa0ce0005be69471"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#af0ff6ad1495d50a8fa0ce0005be69471">◆ </a></span>aaruf_flac_decode_redbook_buffer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">size_t aaruf_flac_decode_redbook_buffer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>dst_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>dst_size</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>src_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>src_size</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Decodes a FLAC-compressed Red Book audio buffer. </p>
|
||
<p>Decompresses FLAC-compressed Red Book audio data into the destination buffer.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">dst_buffer</td><td>Pointer to the destination buffer. </td></tr>
|
||
<tr><td class="paramname">dst_size</td><td>Size of the destination buffer. </td></tr>
|
||
<tr><td class="paramname">src_buffer</td><td>Pointer to the source (compressed) buffer. </td></tr>
|
||
<tr><td class="paramname">src_size</td><td>Size of the source buffer. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Number of bytes written to the destination buffer. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="flac_8c_source.html#l00048">48</a> of file <a class="el" href="flac_8c_source.html">flac.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="flac_8h_source.html#l00027">aaru_flac_ctx::dst_buffer</a>, <a class="el" href="flac_8h_source.html#l00028">aaru_flac_ctx::dst_len</a>, <a class="el" href="flac_8h_source.html#l00029">aaru_flac_ctx::dst_pos</a>, <a class="el" href="flac_8h_source.html#l00030">aaru_flac_ctx::error</a>, <a class="el" href="flac_8c_source.html#l00141">error_callback()</a>, <a class="el" href="flac_8c_source.html#l00097">read_callback()</a>, <a class="el" href="flac_8h_source.html#l00024">aaru_flac_ctx::src_buffer</a>, <a class="el" href="flac_8h_source.html#l00025">aaru_flac_ctx::src_len</a>, <a class="el" href="flac_8h_source.html#l00026">aaru_flac_ctx::src_pos</a>, and <a class="el" href="flac_8c_source.html#l00112">write_callback()</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="read_8c_source.html#l00250">aaruf_read_sector()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a102023fe64e4bd24cd6d4124f0d74e54" name="a102023fe64e4bd24cd6d4124f0d74e54"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a102023fe64e4bd24cd6d4124f0d74e54">◆ </a></span>aaruf_flac_encode_redbook_buffer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">size_t aaruf_flac_encode_redbook_buffer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>dst_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>dst_size</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>src_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>src_size</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>blocksize</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t</td> <td class="paramname"><span class="paramname"><em>do_mid_side_stereo</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t</td> <td class="paramname"><span class="paramname"><em>loose_mid_side_stereo</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>apodization</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>max_lpc_order</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>qlp_coeff_precision</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t</td> <td class="paramname"><span class="paramname"><em>do_qlp_coeff_prec_search</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t</td> <td class="paramname"><span class="paramname"><em>do_exhaustive_model_search</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>min_residual_partition_order</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>max_residual_partition_order</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>application_id</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>application_id_len</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Encodes a Red Book audio buffer to FLAC format. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">dst_buffer</td><td>Pointer to the destination buffer for FLAC data. </td></tr>
|
||
<tr><td class="paramname">dst_size</td><td>Size of the destination buffer in bytes. </td></tr>
|
||
<tr><td class="paramname">src_buffer</td><td>Pointer to the source Red Book audio buffer. </td></tr>
|
||
<tr><td class="paramname">src_size</td><td>Size of the source buffer in bytes. </td></tr>
|
||
<tr><td class="paramname">blocksize</td><td>FLAC block size. </td></tr>
|
||
<tr><td class="paramname">do_mid_side_stereo</td><td>Enable mid-side stereo encoding. </td></tr>
|
||
<tr><td class="paramname">loose_mid_side_stereo</td><td>Enable loose mid-side stereo encoding. </td></tr>
|
||
<tr><td class="paramname">apodization</td><td>Apodization string for FLAC encoder. </td></tr>
|
||
<tr><td class="paramname">max_lpc_order</td><td>Maximum LPC order. </td></tr>
|
||
<tr><td class="paramname">qlp_coeff_precision</td><td>QLP coefficient precision. </td></tr>
|
||
<tr><td class="paramname">do_qlp_coeff_prec_search</td><td>Enable QLP coefficient precision search. </td></tr>
|
||
<tr><td class="paramname">do_exhaustive_model_search</td><td>Enable exhaustive model search. </td></tr>
|
||
<tr><td class="paramname">min_residual_partition_order</td><td>Minimum residual partition order. </td></tr>
|
||
<tr><td class="paramname">max_residual_partition_order</td><td>Maximum residual partition order. </td></tr>
|
||
<tr><td class="paramname">application_id</td><td>Application ID string for FLAC encoder. </td></tr>
|
||
<tr><td class="paramname">application_id_len</td><td>Length of the application ID string. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Number of bytes written to the destination buffer. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="flac_8c_source.html#l00175">175</a> of file <a class="el" href="flac_8c_source.html">flac.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="flac_8h_source.html#l00027">aaru_flac_ctx::dst_buffer</a>, <a class="el" href="flac_8h_source.html#l00028">aaru_flac_ctx::dst_len</a>, <a class="el" href="flac_8h_source.html#l00029">aaru_flac_ctx::dst_pos</a>, <a class="el" href="flac_8c_source.html#l00275">encoder_write_callback()</a>, <a class="el" href="flac_8h_source.html#l00030">aaru_flac_ctx::error</a>, <a class="el" href="flac_8h_source.html#l00024">aaru_flac_ctx::src_buffer</a>, <a class="el" href="flac_8h_source.html#l00025">aaru_flac_ctx::src_len</a>, and <a class="el" href="flac_8h_source.html#l00026">aaru_flac_ctx::src_pos</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a01cf0abe0b137236d4be0b91a29d4818" name="a01cf0abe0b137236d4be0b91a29d4818"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a01cf0abe0b137236d4be0b91a29d4818">◆ </a></span>aaruf_get_aaru_json_metadata()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_aaru_json_metadata </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the embedded Aaru metadata JSON from the image. </p>
|
||
<p>Aaru metadata JSON is a structured metadata format that provides machine-readable, comprehensive information about the image, media, imaging session details, hardware configuration, optical disc tracks and sessions, checksums, and preservation metadata. This function extracts the raw JSON payload that was embedded in the AaruFormat image during creation. The JSON data is preserved in its original form without parsing or interpretation by the library, allowing callers to process the structured metadata using standard JSON parsing libraries.</p>
|
||
<p>This function supports a two-call pattern for buffer size determination:</p><ol type="1">
|
||
<li>First call with a buffer that may be too small returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size</li>
|
||
<li>Second call with a properly sized buffer retrieves the actual data</li>
|
||
</ol>
|
||
<p>Alternatively, if the caller already knows the buffer is large enough, a single call will succeed and populate the buffer with the Aaru JSON data.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Pointer to a buffer that will receive the Aaru metadata JSON. Must be large enough to hold the entire JSON payload (at least *length bytes on input). The buffer will contain raw UTF-8 encoded JSON data on success. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to a size_t that serves dual purpose:<ul>
|
||
<li>On input: size of the provided buffer in bytes</li>
|
||
<li>On output: actual size of the Aaru metadata JSON in bytes If the function returns AARUF_ERROR_BUFFER_TOO_SMALL, this will be updated to contain the required buffer size for a subsequent successful call.</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved Aaru metadata JSON. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The Aaru JSON block is present in the image (identifier == AaruMetadataJsonBlock)</li>
|
||
<li>The provided buffer is large enough (>= required length)</li>
|
||
<li>The Aaru JSON data is successfully copied to the buffer</li>
|
||
<li>The *length parameter is set to the actual size of the JSON data</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-6) The Aaru JSON block is not present. This occurs when:<ul>
|
||
<li>The image was created without Aaru metadata JSON</li>
|
||
<li>ctx->jsonBlock is NULL (no data loaded)</li>
|
||
<li>ctx->jsonBlockHeader.length is 0 (empty metadata)</li>
|
||
<li>ctx->jsonBlockHeader.identifier doesn't equal AaruMetadataJsonBlock</li>
|
||
<li>The Aaru JSON block was not found during image opening</li>
|
||
<li>The *length output parameter is set to 0 to indicate no data available</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer is insufficient. This occurs when:<ul>
|
||
<li>The input *length is less than ctx->jsonBlockHeader.length</li>
|
||
<li>The *length parameter is updated to contain the required buffer size</li>
|
||
<li>No data is copied to the buffer</li>
|
||
<li>The caller should allocate a larger buffer and call again</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Aaru JSON Format and Encoding:<ul>
|
||
<li>The JSON payload is stored in UTF-8 encoding</li>
|
||
<li>The payload may or may not be null-terminated</li>
|
||
<li>The library treats the JSON as opaque binary data</li>
|
||
<li>No JSON parsing, interpretation, or validation is performed by libaaruformat</li>
|
||
<li>JSON schema validation and parsing are the caller's responsibility</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Aaru Metadata JSON Purpose:<ul>
|
||
<li>Provides machine-readable structured metadata using modern JSON format</li>
|
||
<li>Includes comprehensive information about media, sessions, tracks, and checksums</li>
|
||
<li>Enables programmatic access to metadata without XML parsing overhead</li>
|
||
<li>Documents imaging session details, hardware configuration, and preservation data</li>
|
||
<li>Used by Aaru and compatible tools for metadata exchange and analysis</li>
|
||
<li>Complements or serves as alternative to CICM XML metadata</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Buffer Size Handling:<ul>
|
||
<li>First call with insufficient buffer returns required size in *length</li>
|
||
<li>Caller allocates properly sized buffer based on returned length</li>
|
||
<li>Second call with adequate buffer retrieves the actual JSON data</li>
|
||
<li>Single call succeeds if buffer is already large enough</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Data Availability:<ul>
|
||
<li>Aaru JSON blocks are optional in AaruFormat images</li>
|
||
<li>Not all images will contain Aaru metadata JSON</li>
|
||
<li>The presence of JSON data depends on how the image was created</li>
|
||
<li>Check return value to handle missing metadata gracefully</li>
|
||
<li>Images may contain CICM XML, Aaru JSON, both, or neither</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Distinction from CICM XML:<ul>
|
||
<li>CICM XML follows the Canary Islands Computer Museum schema (older format)</li>
|
||
<li>Aaru JSON follows the Aaru-specific metadata schema (newer format)</li>
|
||
<li>Both can coexist in the same image file</li>
|
||
<li>Aaru JSON may provide more detailed or different metadata than CICM XML</li>
|
||
<li>Different tools and workflows may prefer one format over the other</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>This function reads from the in-memory Aaru JSON block loaded during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations. The entire JSON is kept in memory for the lifetime of the context.</dd>
|
||
<dd>
|
||
The buffer parameter must be valid and large enough to hold the JSON data. Passing a buffer smaller than the required size will result in AARUF_ERROR_BUFFER_TOO_SMALL with no partial data copied.</dd>
|
||
<dd>
|
||
This function does not validate JSON syntax or schema. Corrupted JSON data will be retrieved successfully and errors will only be detected when attempting to parse.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="structAaruMetadataJsonBlockHeader.html" title="Header for an Aaru metadata JSON block (identifier == BlockType::AaruMetadataJsonBlock).">AaruMetadataJsonBlockHeader</a> for the on-disk structure definition. </dd>
|
||
<dd>
|
||
<a class="el" href="metadata_8c.html#a42f191c2ea4c70c9d7b373c19b59c812" title="Retrieves the embedded CICM XML metadata sidecar from the image.">aaruf_get_cicm_metadata()</a> for retrieving CICM XML metadata. </dd>
|
||
<dd>
|
||
<a class="el" href="blocks_2metadata_8c.html#a84003ec881425a7b28ec24cb48d19f02" title="Processes an Aaru metadata JSON block from the image stream during image opening.">process_aaru_metadata_json_block()</a> for the loading process during image opening. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02099">2099</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="enums_8h_source.html#l00159">AaruMetadataJsonBlock</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00121">AaruMetadataJsonBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00215">aaruformat_context::json_block</a>, <a class="el" href="context_8h_source.html#l00233">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#l00174">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a42f191c2ea4c70c9d7b373c19b59c812" name="a42f191c2ea4c70c9d7b373c19b59c812"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a42f191c2ea4c70c9d7b373c19b59c812">◆ </a></span>aaruf_get_cicm_metadata()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_cicm_metadata </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the embedded CICM XML metadata sidecar from the image. </p>
|
||
<p>CICM (Canary Islands Computer Museum) XML is a standardized metadata format used for documenting preservation and archival information about media and disk images. This function extracts the raw CICM XML payload that was embedded in the AaruFormat image during creation. The XML data is preserved in its original form without parsing, interpretation, or validation by the library. The metadata typically includes detailed information about the physical media, imaging process, checksums, device information, and preservation metadata following the CICM schema.</p>
|
||
<p>This function supports a two-call pattern for buffer size determination:</p><ol type="1">
|
||
<li>First call with a buffer that may be too small returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size</li>
|
||
<li>Second call with a properly sized buffer retrieves the actual data</li>
|
||
</ol>
|
||
<p>Alternatively, if the caller already knows the buffer is large enough, a single call will succeed and populate the buffer with the CICM XML data.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Pointer to a buffer that will receive the CICM XML metadata. Must be large enough to hold the entire XML payload (at least *length bytes on input). The buffer will contain raw UTF-8 encoded XML data on success. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to a size_t that serves dual purpose:<ul>
|
||
<li>On input: size of the provided buffer in bytes</li>
|
||
<li>On output: actual size of the CICM XML metadata in bytes If the function returns AARUF_ERROR_BUFFER_TOO_SMALL, this will be updated to contain the required buffer size for a subsequent successful call.</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved CICM XML metadata. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The CICM block is present in the image (identifier == CicmBlock)</li>
|
||
<li>The provided buffer is large enough (>= required length)</li>
|
||
<li>The CICM XML data is successfully copied to the buffer</li>
|
||
<li>The *length parameter is set to the actual size of the XML data</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-6) The CICM block is not present. This occurs when:<ul>
|
||
<li>The image was created without CICM XML metadata</li>
|
||
<li>ctx->cicmBlock is NULL (no data loaded)</li>
|
||
<li>ctx->cicmBlockHeader.length is 0 (empty metadata)</li>
|
||
<li>ctx->cicmBlockHeader.identifier doesn't equal CicmBlock</li>
|
||
<li>The CICM block was not found during image opening</li>
|
||
<li>The *length output parameter is set to 0 to indicate no data available</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer is insufficient. This occurs when:<ul>
|
||
<li>The input *length is less than ctx->cicmBlockHeader.length</li>
|
||
<li>The *length parameter is updated to contain the required buffer size</li>
|
||
<li>No data is copied to the buffer</li>
|
||
<li>The caller should allocate a larger buffer and call again</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>CICM XML Format:<ul>
|
||
<li>The XML is stored in UTF-8 encoding</li>
|
||
<li>The payload may or may not be null-terminated</li>
|
||
<li>The library treats the XML as opaque binary data</li>
|
||
<li>No XML parsing, interpretation, or validation is performed by libaaruformat</li>
|
||
<li>Schema validation and XML processing are the caller's responsibility</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
CICM Metadata Purpose:<ul>
|
||
<li>Developed by the Canary Islands Computer Museum for digital preservation</li>
|
||
<li>Documents comprehensive preservation metadata</li>
|
||
<li>Includes checksums for data integrity verification</li>
|
||
<li>Records detailed device and media information</li>
|
||
<li>Supports archival and long-term preservation requirements</li>
|
||
<li>Provides standardized metadata for digital preservation workflows</li>
|
||
<li>Used by cultural heritage institutions and archives</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Buffer Size Handling:<ul>
|
||
<li>First call with insufficient buffer returns required size in *length</li>
|
||
<li>Caller allocates properly sized buffer based on returned length</li>
|
||
<li>Second call with adequate buffer retrieves the actual XML data</li>
|
||
<li>Single call succeeds if buffer is already large enough</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Data Availability:<ul>
|
||
<li>CICM blocks are optional in AaruFormat images</li>
|
||
<li>Not all images will contain CICM metadata</li>
|
||
<li>The presence of CICM data depends on how the image was created</li>
|
||
<li>Check return value to handle missing metadata gracefully</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The XML data may contain sensitive information about the imaging environment, personnel, locations, or media content. Handle appropriately for your use case.</dd>
|
||
<dd>
|
||
This function reads from the in-memory CICM block loaded during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations. The entire CICM XML is kept in memory for the lifetime of the context.</dd>
|
||
<dd>
|
||
The buffer parameter must be valid and large enough to hold the XML data. Passing a buffer smaller than the required size will result in AARUF_ERROR_BUFFER_TOO_SMALL with no partial data copied.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="structCicmMetadataBlock.html" title="Header for a CICM XML metadata block (identifier == BlockType::CicmBlock).">CicmMetadataBlock</a> for the on-disk structure definition. </dd>
|
||
<dd>
|
||
aaruf_set_cicm_metadata() for embedding CICM XML during image creation. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l01944">1944</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00214">aaruformat_context::cicm_block</a>, <a class="el" href="context_8h_source.html#l00231">aaruformat_context::cicm_block_header</a>, <a class="el" href="enums_8h_source.html#l00151">CicmBlock</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00109">CicmMetadataBlock::identifier</a>, <a class="el" href="metadata_8h_source.html#l00110">CicmMetadataBlock::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a9628bcfd2642649a6bcbf1f46d6b6705" name="a9628bcfd2642649a6bcbf1f46d6b6705"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a9628bcfd2642649a6bcbf1f46d6b6705">◆ </a></span>aaruf_get_comments()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_comments </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the user comments or notes stored in the MetadataBlock. </p>
|
||
<p>Provides access to the UTF-16LE encoded comments associated with the image. Comments are often used for provenance notes, imaging details, or curator remarks. The function follows the same two-call buffer sizing pattern used by other metadata retrieval APIs: the caller may probe the required size before allocating memory.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer that receives the comments data. May be NULL when probing size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t. On input it contains the size of <code class="param">buffer</code> in bytes; on output it is updated with the actual comments length.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Comments were available and copied successfully. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid or not a libaaruformat context. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No comments metadata exists in the image. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The supplied buffer was too small. *length is updated with the required size and no data is copied.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Comments are stored exactly as provided during image creation and may include multi-line text or other control characters. No validation or normalization is applied by the library. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02476">2476</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00218">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a38d72be7e7854d6cb0bba89172e27b03" name="a38d72be7e7854d6cb0bba89172e27b03"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a38d72be7e7854d6cb0bba89172e27b03">◆ </a></span>aaruf_get_creator()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_creator </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the recorded creator (operator) name from the MetadataBlock. </p>
|
||
<p>Copies the UTF-16LE encoded creator string that identifies the person or operator who created the image. The function supports the common two-call pattern: the caller first determines the required buffer size by passing a buffer that may be NULL or too small, then allocates sufficient memory and calls again to obtain the actual data. On success the buffer contains an opaque UTF-16LE string of length *length bytes (not null-terminated).</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context opened for reading or writing. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Pointer to the destination buffer that will receive the creator string. May be NULL to query the required size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input specifies the size of <code class="param">buffer</code> in bytes and on output receives the actual length of the creator metadata.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) The creator string was copied successfully. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is NULL or not an aaruformat context. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) Creator metadata has not been recorded in the image. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer was insufficient; *length contains the required size and no data was copied.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>The returned data is UTF-16LE encoded and may contain embedded null characters. Callers should treat it as an opaque byte array unless they explicitly handle UTF-16LE strings.</dd>
|
||
<dd>
|
||
The function does not allocate memory. Callers are responsible for ensuring <code class="param">buffer</code> is large enough before requesting the data. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02404">2404</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00216">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a8d042b26980b56b5dd872f21fa33de70" name="a8d042b26980b56b5dd872f21fa33de70"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a8d042b26980b56b5dd872f21fa33de70">◆ </a></span>aaruf_get_datatype_for_media_tag_type()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_datatype_for_media_tag_type </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>tag_type</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Converts an Aaru media tag type to an image data type. </p>
|
||
<p>Maps the given Aaru media tag type to the corresponding image data type. This is the inverse function of aaruf_get_media_tag_type_for_datatype.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">tag_type</td><td>Aaru media tag type identifier. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Corresponding image data type, or -1 if not found. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="helpers_8c_source.html#l00189">189</a> of file <a class="el" href="helpers_8c_source.html">helpers.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="aaru_8h_source.html#l00974">AACS_CPRM_MKB</a>, <a class="el" href="aaru_8h_source.html#l00972">AACS_DataKeys</a>, <a class="el" href="aaru_8h_source.html#l00973">AACS_LBAExtents</a>, <a class="el" href="aaru_8h_source.html#l00970">AACS_MediaIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00971">AACS_MKB</a>, <a class="el" href="aaru_8h_source.html#l00969">AACS_SerialNumber</a>, <a class="el" href="aaru_8h_source.html#l00968">AACS_VolumeIdentifier</a>, <a class="el" href="enums_8h_source.html#l00083">AacsDataKeys</a>, <a class="el" href="enums_8h_source.html#l00084">AacsLbaExtents</a>, <a class="el" href="enums_8h_source.html#l00081">AacsMediaIdentifier</a>, <a class="el" href="enums_8h_source.html#l00082">AacsMediaKeyBlock</a>, <a class="el" href="enums_8h_source.html#l00080">AacsSerialNumber</a>, <a class="el" href="enums_8h_source.html#l00079">AacsVolumeIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00982">ATA_IDENTIFY</a>, <a class="el" href="enums_8h_source.html#l00093">AtaIdentify</a>, <a class="el" href="aaru_8h_source.html#l00983">ATAPI_IDENTIFY</a>, <a class="el" href="enums_8h_source.html#l00094">AtapiIdentify</a>, <a class="el" href="aaru_8h_source.html#l00964">BD_BCA</a>, <a class="el" href="aaru_8h_source.html#l00966">BD_CartridgeStatus</a>, <a class="el" href="aaru_8h_source.html#l00965">BD_DDS</a>, <a class="el" href="aaru_8h_source.html#l00963">BD_DI</a>, <a class="el" href="aaru_8h_source.html#l00967">BD_SpareArea</a>, <a class="el" href="enums_8h_source.html#l00075">BlurayBca</a>, <a class="el" href="enums_8h_source.html#l00077">BlurayCartridgeStatus</a>, <a class="el" href="enums_8h_source.html#l00076">BlurayDds</a>, <a class="el" href="enums_8h_source.html#l00074">BlurayDi</a>, <a class="el" href="enums_8h_source.html#l00078">BluraySpareArea</a>, <a class="el" href="aaru_8h_source.html#l00939">CD_ATIP</a>, <a class="el" href="aaru_8h_source.html#l00996">CD_FirstTrackPregap</a>, <a class="el" href="aaru_8h_source.html#l00937">CD_FullTOC</a>, <a class="el" href="aaru_8h_source.html#l01003">CD_LeadIn</a>, <a class="el" href="aaru_8h_source.html#l00997">CD_LeadOut</a>, <a class="el" href="aaru_8h_source.html#l00941">CD_MCN</a>, <a class="el" href="aaru_8h_source.html#l00938">CD_PMA</a>, <a class="el" href="aaru_8h_source.html#l00936">CD_SessionInfo</a>, <a class="el" href="aaru_8h_source.html#l00940">CD_TEXT</a>, <a class="el" href="aaru_8h_source.html#l00935">CD_TOC</a>, <a class="el" href="enums_8h_source.html#l00051">CompactDiscAtip</a>, <a class="el" href="enums_8h_source.html#l00107">CompactDiscFirstTrackPregap</a>, <a class="el" href="enums_8h_source.html#l00124">CompactDiscLeadIn</a>, <a class="el" href="enums_8h_source.html#l00052">CompactDiscLeadInCdText</a>, <a class="el" href="enums_8h_source.html#l00108">CompactDiscLeadOut</a>, <a class="el" href="enums_8h_source.html#l00120">CompactDiscMediaCatalogueNumber</a>, <a class="el" href="enums_8h_source.html#l00047">CompactDiscPartialToc</a>, <a class="el" href="enums_8h_source.html#l00050">CompactDiscPma</a>, <a class="el" href="enums_8h_source.html#l00048">CompactDiscSessionInfo</a>, <a class="el" href="enums_8h_source.html#l00049">CompactDiscToc</a>, <a class="el" href="enums_8h_source.html#l00085">CprmMediaKeyBlock</a>, <a class="el" href="aaru_8h_source.html#l00995">DCB</a>, <a class="el" href="aaru_8h_source.html#l00956">DVD_ADIP</a>, <a class="el" href="aaru_8h_source.html#l00945">DVD_BCA</a>, <a class="el" href="aaru_8h_source.html#l00943">DVD_CMI</a>, <a class="el" href="aaru_8h_source.html#l00944">DVD_DiscKey</a>, <a class="el" href="aaru_8h_source.html#l01008">DVD_DiscKey_Decrypted</a>, <a class="el" href="aaru_8h_source.html#l00946">DVD_DMI</a>, <a class="el" href="aaru_8h_source.html#l00947">DVD_MediaIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00948">DVD_MKB</a>, <a class="el" href="aaru_8h_source.html#l00942">DVD_PFI</a>, <a class="el" href="enums_8h_source.html#l00067">DvdAdip</a>, <a class="el" href="enums_8h_source.html#l00056">DvdBca</a>, <a class="el" href="enums_8h_source.html#l00106">DvdDiscControlBlock</a>, <a class="el" href="enums_8h_source.html#l00055">DvdDiscKey</a>, <a class="el" href="enums_8h_source.html#l00125">DvdDiscKeyDecrypted</a>, <a class="el" href="aaru_8h_source.html#l00961">DVDDL_JumpIntervalSize</a>, <a class="el" href="aaru_8h_source.html#l00959">DVDDL_LayerCapacity</a>, <a class="el" href="aaru_8h_source.html#l00962">DVDDL_ManualLayerJumpLBA</a>, <a class="el" href="aaru_8h_source.html#l00960">DVDDL_MiddleZoneAddress</a>, <a class="el" href="enums_8h_source.html#l00072">DvdDlJumpIntervalSize</a>, <a class="el" href="enums_8h_source.html#l00070">DvdDlLayerCapacity</a>, <a class="el" href="enums_8h_source.html#l00073">DvdDlManualLayerJumpLba</a>, <a class="el" href="enums_8h_source.html#l00071">DvdDlMiddleZoneAddress</a>, <a class="el" href="enums_8h_source.html#l00057">DvdDmi</a>, <a class="el" href="enums_8h_source.html#l00054">DvdLeadInCmi</a>, <a class="el" href="enums_8h_source.html#l00058">DvdMediaIdentifier</a>, <a class="el" href="enums_8h_source.html#l00059">DvdMediaKeyBlock</a>, <a class="el" href="enums_8h_source.html#l00053">DvdPfi</a>, <a class="el" href="aaru_8h_source.html#l00954">DVDR_MediaIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00955">DVDR_PFI</a>, <a class="el" href="aaru_8h_source.html#l00953">DVDR_PreRecordedInfo</a>, <a class="el" href="aaru_8h_source.html#l00952">DVDR_RMD</a>, <a class="el" href="aaru_8h_source.html#l00949">DVDRAM_DDS</a>, <a class="el" href="aaru_8h_source.html#l00950">DVDRAM_MediumStatus</a>, <a class="el" href="aaru_8h_source.html#l00951">DVDRAM_SpareArea</a>, <a class="el" href="enums_8h_source.html#l00060">DvdRamDds</a>, <a class="el" href="enums_8h_source.html#l00061">DvdRamMediumStatus</a>, <a class="el" href="enums_8h_source.html#l00062">DvdRamSpareArea</a>, <a class="el" href="enums_8h_source.html#l00065">DvdRMediaIdentifier</a>, <a class="el" href="enums_8h_source.html#l00066">DvdRPfi</a>, <a class="el" href="enums_8h_source.html#l00064">DvdRPrerecordedInfo</a>, <a class="el" href="enums_8h_source.html#l00063">DvdRRmd</a>, <a class="el" href="aaru_8h_source.html#l00994">Floppy_LeadOut</a>, <a class="el" href="enums_8h_source.html#l00105">FloppyLeadOut</a>, <a class="el" href="aaru_8h_source.html#l00957">HDDVD_CPI</a>, <a class="el" href="aaru_8h_source.html#l00958">HDDVD_MediumStatus</a>, <a class="el" href="enums_8h_source.html#l00068">HdDvdCpi</a>, <a class="el" href="enums_8h_source.html#l00069">HdDvdMediumStatus</a>, <a class="el" href="aaru_8h_source.html#l00975">Hybrid_RecognizedLayers</a>, <a class="el" href="enums_8h_source.html#l00086">HybridRecognizedLayers</a>, <a class="el" href="aaru_8h_source.html#l00989">MMC_CID</a>, <a class="el" href="aaru_8h_source.html#l00990">MMC_CSD</a>, <a class="el" href="aaru_8h_source.html#l00977">MMC_DiscInformation</a>, <a class="el" href="aaru_8h_source.html#l00992">MMC_ExtendedCSD</a>, <a class="el" href="aaru_8h_source.html#l00991">MMC_OCR</a>, <a class="el" href="aaru_8h_source.html#l00979">MMC_POWResourcesInformation</a>, <a class="el" href="aaru_8h_source.html#l00978">MMC_TrackResourcesInformation</a>, <a class="el" href="aaru_8h_source.html#l00976">MMC_WriteProtection</a>, <a class="el" href="enums_8h_source.html#l00100">MultiMediaCardCid</a>, <a class="el" href="enums_8h_source.html#l00101">MultiMediaCardCsd</a>, <a class="el" href="enums_8h_source.html#l00103">MultiMediaCardExtendedCsd</a>, <a class="el" href="enums_8h_source.html#l00102">MultiMediaCardOcr</a>, <a class="el" href="aaru_8h_source.html#l00984">PCMCIA_CIS</a>, <a class="el" href="enums_8h_source.html#l00095">PcmciaCis</a>, <a class="el" href="aaru_8h_source.html#l00980">SCSI_INQUIRY</a>, <a class="el" href="aaru_8h_source.html#l00981">SCSI_MODEPAGE_2A</a>, <a class="el" href="aaru_8h_source.html#l00999">SCSI_MODESENSE_10</a>, <a class="el" href="aaru_8h_source.html#l00998">SCSI_MODESENSE_6</a>, <a class="el" href="enums_8h_source.html#l00091">ScsiInquiry</a>, <a class="el" href="enums_8h_source.html#l00088">ScsiMmcDiscInformation</a>, <a class="el" href="enums_8h_source.html#l00090">ScsiMmcPowResourcesInformation</a>, <a class="el" href="enums_8h_source.html#l00089">ScsiMmcTrackResourcesInformation</a>, <a class="el" href="enums_8h_source.html#l00087">ScsiMmcWriteProtection</a>, <a class="el" href="enums_8h_source.html#l00092">ScsiModePage2A</a>, <a class="el" href="enums_8h_source.html#l00110">ScsiModeSense10</a>, <a class="el" href="enums_8h_source.html#l00109">ScsiModeSense6</a>, <a class="el" href="aaru_8h_source.html#l00985">SD_CID</a>, <a class="el" href="aaru_8h_source.html#l00986">SD_CSD</a>, <a class="el" href="aaru_8h_source.html#l00988">SD_OCR</a>, <a class="el" href="aaru_8h_source.html#l00987">SD_SCR</a>, <a class="el" href="enums_8h_source.html#l00096">SecureDigitalCid</a>, <a class="el" href="enums_8h_source.html#l00097">SecureDigitalCsd</a>, <a class="el" href="enums_8h_source.html#l00099">SecureDigitalOcr</a>, <a class="el" href="enums_8h_source.html#l00098">SecureDigitalScr</a>, <a class="el" href="aaru_8h_source.html#l01000">USB_Descriptors</a>, <a class="el" href="enums_8h_source.html#l00111">UsbDescriptors</a>, <a class="el" href="aaru_8h_source.html#l01001">Xbox_DMI</a>, <a class="el" href="aaru_8h_source.html#l01002">Xbox_PFI</a>, <a class="el" href="aaru_8h_source.html#l00993">Xbox_SecuritySector</a>, <a class="el" href="enums_8h_source.html#l00112">XboxDmi</a>, <a class="el" href="enums_8h_source.html#l00113">XboxPfi</a>, and <a class="el" href="enums_8h_source.html#l00104">XboxSecuritySector</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="close_8c_source.html#l02409">write_media_tags()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a3db92f6bebf60195d6ab327e17988cee" name="a3db92f6bebf60195d6ab327e17988cee"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a3db92f6bebf60195d6ab327e17988cee">◆ </a></span>aaruf_get_drive_firmware_revision()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_drive_firmware_revision </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the firmware revision metadata for the imaging drive. </p>
|
||
<p>Returns the UTF-16LE encoded firmware revision string that was captured when the image was created. Firmware information is critical for reproducing imaging environments and diagnosing drive-specific behavior or bugs.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for the firmware revision string. May be NULL when probing size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t that specifies the buffer capacity in bytes on input and is updated with the actual metadata length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Firmware revision metadata was present and copied successfully. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No firmware metadata exists in the image. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The supplied buffer was too small; *length is updated.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Firmware revision formats vary between manufacturers (e.g., numeric, alphanumeric, dot-separated). The library stores the data verbatim without attempting normalization. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l03178">3178</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00228">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a5d487a858c48838bcc9f3bba4b5944a1" name="a5d487a858c48838bcc9f3bba4b5944a1"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a5d487a858c48838bcc9f3bba4b5944a1">◆ </a></span>aaruf_get_drive_manufacturer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_drive_manufacturer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the drive manufacturer metadata captured during imaging. </p>
|
||
<p>Copies the UTF-16LE encoded manufacturer name of the device used to read or write the medium. This information documents the hardware involved in the imaging process, which is crucial for forensic reporting and reproducibility studies.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for the manufacturer string. May be NULL when querying required length. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t specifying the buffer size on input and receiving the actual metadata length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Drive manufacturer metadata was copied successfully. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) The image lacks drive manufacturer metadata. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer is too small; *length holds the required size for a subsequent call.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>The returned manufacturer string corresponds to the value recorded by <a class="el" href="metadata_8c.html#a223856fa226b26c466997800183c97c4" title="Sets the drive manufacturer information for the image.">aaruf_set_drive_manufacturer()</a> and may include branding or OEM designations. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02968">2968</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00224">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a54d724659818ea4486f9981672f6d01e" name="a54d724659818ea4486f9981672f6d01e"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a54d724659818ea4486f9981672f6d01e">◆ </a></span>aaruf_get_drive_model()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_drive_model </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the device model information for the imaging drive. </p>
|
||
<p>Returns the UTF-16LE encoded model identifier for the drive used during acquisition. The model metadata provides finer granularity than the manufacturer name, enabling detailed documentation of imaging hardware capabilities and behavior.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Buffer that receives the model string; may be NULL while probing required capacity. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t indicating buffer size on input and receiving the metadata length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Drive model metadata was available and copied. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No drive model metadata exists in the image. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The supplied buffer was insufficient; *length is updated.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Model strings can include firmware suffixes, interface hints, or OEM variations. Consume the data verbatim to maintain accurate provenance records. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l03038">3038</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00225">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a1892cc8395305d7e85d04544ded62131" name="a1892cc8395305d7e85d04544ded62131"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a1892cc8395305d7e85d04544ded62131">◆ </a></span>aaruf_get_drive_serial_number()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_drive_serial_number </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the imaging drive's serial number metadata. </p>
|
||
<p>Copies the UTF-16LE encoded serial number reported for the drive used during the imaging session. This metadata enables correlation between images and specific hardware units for forensic chain of custody or quality assurance workflows.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for the serial number; may be NULL when querying size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t carrying the buffer size on input and receiving the actual serial number length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Drive serial number metadata was copied to <code class="param">buffer</code>. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No drive serial number metadata is available. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer was insufficient.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Serial numbers are stored exactly as returned by the imaging hardware and may include leading zeros or spacing that should be preserved. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l03108">3108</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00226">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a36af83897e131ba792c51ae8caec9984" name="a36af83897e131ba792c51ae8caec9984"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a36af83897e131ba792c51ae8caec9984">◆ </a></span>aaruf_get_dumphw()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_dumphw </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>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the dump hardware block containing acquisition environment information. </p>
|
||
<p>Extracts the complete DumpHardwareBlock from the image, which documents the hardware and software environments used to create the image. A dump hardware block records one or more "dump environments" – typically combinations of physical devices (drives, controllers, adapters) and the software stacks that performed the read operations. This metadata is essential for understanding the imaging context, validating acquisition integrity, reproducing imaging conditions, and supporting forensic or archival documentation requirements.</p>
|
||
<p>Each environment entry includes hardware identification (manufacturer, model, revision, firmware, serial number), software identification (name, version, operating system), and optional extent ranges that specify which logical sectors or units were contributed by that particular environment. This structure supports complex imaging scenarios where multiple devices or software configurations were used to create a composite image.</p>
|
||
<p>The function reconstructs the complete on-disk binary representation of the dump hardware block, including the <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> followed by all entries with their variable-length UTF-8 strings and extent arrays. The reconstructed block includes a calculated CRC64 checksum over the payload data for integrity verification.</p>
|
||
<p>This function supports a two-call pattern for buffer size determination:</p><ol type="1">
|
||
<li>First call with insufficient buffer (or NULL) returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size (sizeof(DumpHardwareHeader) + total payload length)</li>
|
||
<li>Second call with properly sized buffer retrieves the complete block data</li>
|
||
</ol>
|
||
<p>Alternatively, if the caller already knows the buffer is large enough, a single call will succeed and populate the buffer with the complete dump hardware block.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Pointer to a buffer that will receive the dump hardware block data. Must be large enough to hold the complete block (at least *length bytes on input). May be NULL to query the required buffer size. The buffer will contain the <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> followed by serialized entries, strings, and extent arrays on success. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to a size_t that serves dual purpose:<ul>
|
||
<li>On input: size of the provided buffer in bytes (ignored if buffer is NULL)</li>
|
||
<li>On output: actual size required/used for the dump hardware block in bytes If the function returns AARUF_ERROR_BUFFER_TOO_SMALL, this will be updated to contain the required buffer size for a subsequent successful call.</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved dump hardware block. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The dump hardware block is present (identifier == DumpHardwareBlock)</li>
|
||
<li>The provided buffer is large enough (>= required length)</li>
|
||
<li>All hardware entries with their strings and extents are copied to the buffer</li>
|
||
<li>The <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> is written with calculated CRC64 at buffer offset 0</li>
|
||
<li>The *length parameter is set to the actual block size</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-6) The dump hardware block is not present. This occurs when:<ul>
|
||
<li>The image was created without dump hardware information</li>
|
||
<li>ctx->dumpHardwareEntriesWithData is NULL (no data loaded)</li>
|
||
<li>ctx->dumpHardwareHeader.entries == 0 (no hardware entries)</li>
|
||
<li>ctx->dumpHardwareHeader.identifier doesn't equal DumpHardwareBlock</li>
|
||
<li>The dump hardware block was not found during image opening</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-12) The provided buffer is insufficient. This occurs when:<ul>
|
||
<li>buffer is NULL (size query mode)</li>
|
||
<li>The input *length is less than sizeof(DumpHardwareHeader) + payload length</li>
|
||
<li>The *length parameter is updated to contain the required buffer size</li>
|
||
<li>No data is copied to the buffer</li>
|
||
<li>The caller should allocate a larger buffer and call again</li>
|
||
<li>Also returned if calculated entry size exceeds buffer during iteration (sanity check)</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Dump Hardware Block Structure:<ul>
|
||
<li><a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> (16 bytes): identifier, entries count, payload length, CRC64</li>
|
||
<li>For each entry (variable size):<ul>
|
||
<li><a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> (36 bytes): length fields for all strings and extent count</li>
|
||
<li>Variable-length UTF-8 strings (in order): manufacturer, model, revision, firmware, serial, software name, software version, software operating system</li>
|
||
<li>Array of <a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> structures (16 bytes each) if extent count > 0</li>
|
||
</ul>
|
||
</li>
|
||
<li>All strings are UTF-8 encoded and NOT null-terminated in the serialized block</li>
|
||
<li>String lengths are in bytes, not character counts</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Dump Hardware Environments:<ul>
|
||
<li>Each entry represents one hardware/software combination used during imaging</li>
|
||
<li>Multiple entries support scenarios where different devices contributed different sectors</li>
|
||
<li>Extent arrays specify which logical sector ranges each environment contributed</li>
|
||
<li>Empty extent arrays (extents == 0) indicate the environment dumped the entire medium</li>
|
||
<li>Overlapping extents between entries may indicate verification passes or redundancy</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Hardware Identification Fields:<ul>
|
||
<li>manufacturer: Device manufacturer (e.g., "Plextor", "Sony", "Samsung")</li>
|
||
<li>model: Device model number (e.g., "PX-716A", "DRU-820A")</li>
|
||
<li>revision: Hardware revision identifier</li>
|
||
<li>firmware: Firmware version (e.g., "1.11", "KY08")</li>
|
||
<li>serial: Device serial number for unique identification</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Software Identification Fields:<ul>
|
||
<li>softwareName: Dumping software name (e.g., "Aaru", "ddrescue", "IsoBuster")</li>
|
||
<li>softwareVersion: Software version (e.g., "5.3.0", "1.25")</li>
|
||
<li>softwareOperatingSystem: Host OS (e.g., "Linux 5.10.0", "Windows 10", "macOS 12.0")</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
CRC64 Calculation:<ul>
|
||
<li>The function calculates CRC64-ECMA over the payload (everything after the header)</li>
|
||
<li>The calculated CRC64 is stored in the returned <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a></li>
|
||
<li>This allows verification of the serialized block integrity</li>
|
||
<li>The CRC64 is computed from buffer data, not from the original context</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Buffer Layout After Successful Call:<ul>
|
||
<li>Offset 0: <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> with calculated CRC64</li>
|
||
<li>Offset 16: First <a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a></li>
|
||
<li>Followed by: First entry's UTF-8 strings (in documented order)</li>
|
||
<li>Followed by: First entry's <a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> array (if extents > 0)</li>
|
||
<li>Repeated for all remaining entries</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Use Cases:<ul>
|
||
<li>Forensic documentation requiring complete equipment chain of custody</li>
|
||
<li>Archival metadata for long-term preservation requirements</li>
|
||
<li>Reproducing imaging conditions for verification or re-imaging</li>
|
||
<li>Identifying firmware-specific issues or drive-specific behaviors</li>
|
||
<li>Multi-device imaging scenario documentation</li>
|
||
<li>Correlating imaging artifacts with specific hardware/software combinations</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>This function reads from the in-memory dump hardware data loaded during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations. The data is reconstructed from the parsed context structures into the on-disk binary format.</dd>
|
||
<dd>
|
||
The buffer must be valid and large enough to hold the entire dump hardware block. Passing a buffer smaller than required will result in AARUF_ERROR_BUFFER_TOO_SMALL.</dd>
|
||
<dd>
|
||
String data in the serialized block is NOT null-terminated. Applications parsing the buffer must use the length fields in <a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> to determine string boundaries. The library adds null terminators only for in-memory convenience.</dd>
|
||
<dd>
|
||
The function performs bounds checking during serialization. If calculated entry sizes exceed the buffer length, AARUF_ERROR_BUFFER_TOO_SMALL is returned even after the initial size check. This should not occur with properly sized buffers but protects against data corruption.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> for the block header structure definition. </dd>
|
||
<dd>
|
||
<a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> for the per-environment entry structure definition. </dd>
|
||
<dd>
|
||
<a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> for the extent range structure definition. </dd>
|
||
<dd>
|
||
<a class="el" href="blocks_2dump_8c.html#a0e2cfc858c0551bc9bef11d5bdb85aac" title="Processes a dump hardware block from the image stream.">process_dumphw_block()</a> for the loading process during image opening. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="dump_8c_source.html#l00186">186</a> of file <a class="el" href="dump_8c_source.html">dump.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="dump_8h_source.html#l00095">DumpHardwareHeader::crc64</a>, <a class="el" href="context_8h_source.html#l00212">aaruformat_context::dump_hardware_entries_with_data</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::dump_hardware_header</a>, <a class="el" href="enums_8h_source.html#l00156">DumpHardwareBlock</a>, <a class="el" href="dump_8h_source.html#l00093">DumpHardwareHeader::entries</a>, <a class="el" href="context_8h_source.html#l00315">DumpHardwareEntriesWithData::entry</a>, <a class="el" href="context_8h_source.html#l00316">DumpHardwareEntriesWithData::extents</a>, <a class="el" href="dump_8h_source.html#l00122">DumpHardwareEntry::extents</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00320">DumpHardwareEntriesWithData::firmware</a>, <a class="el" href="dump_8h_source.html#l00117">DumpHardwareEntry::firmwareLength</a>, <a class="el" href="dump_8h_source.html#l00092">DumpHardwareHeader::identifier</a>, <a class="el" href="dump_8h_source.html#l00094">DumpHardwareHeader::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00317">DumpHardwareEntriesWithData::manufacturer</a>, <a class="el" href="dump_8h_source.html#l00114">DumpHardwareEntry::manufacturerLength</a>, <a class="el" href="context_8h_source.html#l00318">DumpHardwareEntriesWithData::model</a>, <a class="el" href="dump_8h_source.html#l00115">DumpHardwareEntry::modelLength</a>, <a class="el" href="context_8h_source.html#l00319">DumpHardwareEntriesWithData::revision</a>, <a class="el" href="dump_8h_source.html#l00116">DumpHardwareEntry::revisionLength</a>, <a class="el" href="context_8h_source.html#l00321">DumpHardwareEntriesWithData::serial</a>, <a class="el" href="dump_8h_source.html#l00118">DumpHardwareEntry::serialLength</a>, <a class="el" href="context_8h_source.html#l00322">DumpHardwareEntriesWithData::softwareName</a>, <a class="el" href="dump_8h_source.html#l00119">DumpHardwareEntry::softwareNameLength</a>, <a class="el" href="context_8h_source.html#l00324">DumpHardwareEntriesWithData::softwareOperatingSystem</a>, <a class="el" href="dump_8h_source.html#l00121">DumpHardwareEntry::softwareOperatingSystemLength</a>, <a class="el" href="context_8h_source.html#l00323">DumpHardwareEntriesWithData::softwareVersion</a>, <a class="el" href="dump_8h_source.html#l00120">DumpHardwareEntry::softwareVersionLength</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="abbcf276c3518b3e666885ab250fd374e" name="abbcf276c3518b3e666885ab250fd374e"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#abbcf276c3518b3e666885ab250fd374e">◆ </a></span>aaruf_get_geometry()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_geometry </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>cylinders</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>heads</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>sectors_per_track</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the logical CHS geometry from the AaruFormat image. </p>
|
||
<p>Reads the Cylinder-Head-Sector (CHS) geometry information from the image's geometry block and returns the values through output parameters. The geometry block contains legacy-style logical addressing parameters that describe how the storage medium was originally organized in terms of cylinders, heads (tracks per cylinder), and sectors per track. This information is essential for software that requires CHS addressing or for accurately representing the original medium's logical structure.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
|
||
<tr><td class="paramname">cylinders</td><td>Pointer to store the number of cylinders. Updated on success. </td></tr>
|
||
<tr><td class="paramname">heads</td><td>Pointer to store the number of heads (tracks per cylinder). Updated on success. </td></tr>
|
||
<tr><td class="paramname">sectors_per_track</td><td>Pointer to store the number of sectors per track. Updated on success.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved geometry information. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The geometry block is present in the image (identifier == GeometryBlock)</li>
|
||
<li>All three output parameters are successfully populated with geometry values</li>
|
||
<li>The cylinders parameter contains the total number of cylinders</li>
|
||
<li>The heads parameter contains the number of heads per cylinder</li>
|
||
<li>The sectors_per_track parameter contains the number of sectors per track</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-6) The geometry block is not present. This occurs when:<ul>
|
||
<li>The image was created without geometry information</li>
|
||
<li>The geometryBlock.identifier field doesn't equal GeometryBlock</li>
|
||
<li>The geometry block was not found during image opening</li>
|
||
<li>The image format doesn't support or require CHS geometry</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Geometry Interpretation:<ul>
|
||
<li>Total logical sectors = cylinders × heads × sectors_per_track</li>
|
||
<li>Sector size is not included in the geometry block and must be obtained separately (typically 512 bytes for most block devices, but can vary)</li>
|
||
<li>The geometry represents logical addressing, not necessarily physical medium geometry</li>
|
||
<li>Modern storage devices often report translated or synthetic geometry values</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
CHS Addressing Context:<ul>
|
||
<li>CHS addressing was historically used for hard disk drives and floppy disks</li>
|
||
<li>Legacy BIOS and older operating systems relied on CHS parameters</li>
|
||
<li>LBA (Logical Block Addressing) has largely replaced CHS for modern devices</li>
|
||
<li>Some disk image formats and emulators still require CHS information</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Geometry Block Availability:<ul>
|
||
<li>Not all image types contain geometry blocks</li>
|
||
<li>Optical media (CDs, DVDs) typically don't have CHS geometry</li>
|
||
<li>Modern large-capacity drives may not have meaningful CHS values</li>
|
||
<li>Check the return value to determine if geometry is available</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Parameter Validation:<ul>
|
||
<li>All output parameters must be non-NULL valid pointers</li>
|
||
<li>The function does not validate the geometry values themselves</li>
|
||
<li>Geometry values of zero or unusually large values may indicate issues</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The output parameters are only modified on success (AARUF_STATUS_OK). On error, their values remain unchanged. Initialize them before calling if default values are needed on failure.</dd>
|
||
<dd>
|
||
This function reads from the in-memory geometry block loaded during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations.</dd>
|
||
<dd>
|
||
Geometry values may not accurately represent physical device geometry, especially for modern drives with zone-based recording or flash storage. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l00094">94</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="data_8h_source.html#l00093">GeometryBlockHeader::cylinders</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00229">aaruformat_context::geometry_block</a>, <a class="el" href="enums_8h_source.html#l00148">GeometryBlock</a>, <a class="el" href="data_8h_source.html#l00094">GeometryBlockHeader::heads</a>, <a class="el" href="data_8h_source.html#l00092">GeometryBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="data_8h_source.html#l00095">GeometryBlockHeader::sectorsPerTrack</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a65c73217edb9661accbbe3de4f555b62" name="a65c73217edb9661accbbe3de4f555b62"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a65c73217edb9661accbbe3de4f555b62">◆ </a></span>aaruf_get_image_info()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_image_info </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype"><a class="el" href="structImageInfo.html">ImageInfo</a> *</td> <td class="paramname"><span class="paramname"><em>image_info</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves a deep copy of the <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure from the AaruFormat image. </p>
|
||
<p>Returns a complete copy of the high-level image information summary containing metadata such as image size, sector count, sector size, version information, creation timestamps, and media type. This function performs a deep copy of all fields including string buffers, ensuring the caller receives a complete, independent copy of the image information.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened image context). </td></tr>
|
||
<tr><td class="paramname">image_info</td><td>Pointer to an <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure to receive the copied data. Must be a valid pointer to allocated memory.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully copied image info. The image_info parameter contains a complete copy of all fields including:<ul>
|
||
<li>HasPartitions: Whether image contains partitions/tracks</li>
|
||
<li>HasSessions: Whether image contains multiple sessions</li>
|
||
<li>ImageSize: Size of image payload in bytes</li>
|
||
<li>Sectors: Total count of addressable sectors/blocks</li>
|
||
<li>SectorSize: Size of each logical sector in bytes</li>
|
||
<li>Version: Image format version string (NUL-terminated)</li>
|
||
<li>Application: Creating application name (NUL-terminated)</li>
|
||
<li>ApplicationVersion: Application version string (NUL-terminated)</li>
|
||
<li>CreationTime: Image creation timestamp (Windows FILETIME)</li>
|
||
<li>LastModificationTime: Last modification timestamp (Windows FILETIME)</li>
|
||
<li><a class="el" href="group__MediaTypes.html#ga1499e9f8a76cb81b43b7a4b0dbe7e44a" title="Enumerates every recognized media / cartridge / optical / tape / card / disk format.">MediaType</a>: Media type identifier</li>
|
||
<li>MetadataMediaType: Media type for sidecar generation</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC</li>
|
||
<li>The context was not properly initialized</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>The <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure contains fixed-size character arrays that are properly NUL-terminated, making it safe to use as C strings.</dd>
|
||
<dd>
|
||
This function performs a complete deep copy using memcpy, copying all fields including strings, integers, and timestamps.</dd>
|
||
<dd>
|
||
The caller is responsible for allocating the <a class="el" href="structImageInfo.html" title="High-level summary of an opened Aaru image containing metadata and media characteristics.">ImageInfo</a> structure before calling this function. The structure is not dynamically allocated by this function.</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The image_info parameter must point to valid, allocated memory of at least sizeof(ImageInfo) bytes. Passing NULL or invalid pointers will result in undefined behavior.</dd>
|
||
<dd>
|
||
This function reads from the in-memory image_info loaded during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or populated during <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. It does not perform file I/O operations. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l03634">3634</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a580c8bf133cf3481deca14779b8b5419" name="a580c8bf133cf3481deca14779b8b5419"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a580c8bf133cf3481deca14779b8b5419">◆ </a></span>aaruf_get_media_barcode()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_barcode </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the barcode assigned to the physical media or its packaging. </p>
|
||
<p>Returns the UTF-16LE encoded barcode string that was captured when the image was created. Barcodes are commonly used in institutional workflows for inventory tracking and automated retrieval.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Buffer that receives the barcode string; may be NULL when probing size requirements. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t specifying the buffer size on input and receiving the actual barcode length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Barcode metadata was present and copied successfully. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No barcode metadata exists in the image. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The supplied buffer was too small.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Barcode values can be strict alphanumeric codes (e.g., LTO cartridge IDs) or full strings from custom labeling systems. Preserve the returned string exactly for catalog interoperability. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02825">2825</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00222">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a515c264f726f8b0a5104778b383ad1d4" name="a515c264f726f8b0a5104778b383ad1d4"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a515c264f726f8b0a5104778b383ad1d4">◆ </a></span>aaruf_get_media_manufacturer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_manufacturer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the recorded media manufacturer name. </p>
|
||
<p>Provides access to the UTF-16LE encoded manufacturer metadata that identifies the company which produced the physical medium. This information is taken from the MetadataBlock and mirrors the value previously stored via <a class="el" href="metadata_8c.html#add92b8c91ede6a62dfda5f8980c3ce6d" title="Sets the media manufacturer information for the image.">aaruf_set_media_manufacturer()</a>.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Buffer that receives the manufacturer string. May be NULL when probing size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t specifying the buffer size on input and receiving the actual manufacturer string length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Manufacturer metadata was available and copied. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) The image lacks manufacturer metadata. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer was too small; *length indicates size.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Values may include trailing spaces or vendor-specific capitalization. Treat the returned data as authoritative and avoid trimming unless required by the consuming application. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02616">2616</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00219">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a509892f76c9a03a030693740d043adfc" name="a509892f76c9a03a030693740d043adfc"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a509892f76c9a03a030693740d043adfc">◆ </a></span>aaruf_get_media_model()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_model </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the media model or product designation metadata. </p>
|
||
<p>Returns the UTF-16LE encoded model name that specifies the exact product variant of the physical medium. The function mirrors the set counterpart and is useful for accurately documenting media specifications during preservation workflows.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for the model string; may be NULL when querying required size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input contains the buffer capacity in bytes and on output is updated with the actual metadata length.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Model metadata was successfully copied. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No media model metadata is present in the image. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The caller-provided buffer is too small.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Model strings often contain performance ratings (e.g., "16x", "LTO-7"). The data is opaque and should be handled without modification unless necessary. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02686">2686</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00220">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a4cdfb46f5630fcf1fe6447b37ad18ae2" name="a4cdfb46f5630fcf1fe6447b37ad18ae2"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a4cdfb46f5630fcf1fe6447b37ad18ae2">◆ </a></span>aaruf_get_media_part_number()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_part_number </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the media part number recorded in the MetadataBlock. </p>
|
||
<p>Provides access to the UTF-16LE encoded part number identifying the precise catalog or ordering code for the physical medium. Part numbers help archivists procure exact replacements and document specific media variants used during acquisition.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for the part number string. May be NULL while querying size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t that supplies the buffer size on input and is updated with the actual part number length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Part number metadata was returned successfully. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No part number metadata exists. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer was insufficient; *length contains the required size.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Part numbers may include manufacturer-specific formatting such as hyphens or suffix letters. The library stores and returns the data verbatim. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02896">2896</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00223">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="aa683ff7387ba3f505b1756da1b408f7e" name="aa683ff7387ba3f505b1756da1b408f7e"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#aa683ff7387ba3f505b1756da1b408f7e">◆ </a></span>aaruf_get_media_sequence()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_sequence </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>sequence</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>last_sequence</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the media sequence metadata for multi-volume image sets. </p>
|
||
<p>Reads the media sequence fields stored in the MetadataBlock header and returns the current media number together with the final media number for the complete set. This information indicates the position of the imaged medium within a multi-volume collection (for example, "disc 2 of 5"). The function operates entirely on in-memory structures populated during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a>; no additional disk I/O is performed.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to an initialized aaruformat context opened for reading or writing. </td></tr>
|
||
<tr><td class="paramname">sequence</td><td>Pointer that receives the current media sequence number (typically 1-based). </td></tr>
|
||
<tr><td class="paramname">last_sequence</td><td>Pointer that receives the total number of media in the set.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Metadata was present and the output parameters were populated. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The provided context pointer is NULL or not an aaruformat context (magic mismatch). </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) The MetadataBlock was not present in the image, making sequence data unavailable.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>For standalone media, both sequence and last_sequence are commonly set to 1. Some creators may also set them to 0 to indicate the absence of sequence semantics; callers should handle either pattern gracefully.</dd>
|
||
<dd>
|
||
The function does not validate logical consistency (e.g., whether sequence <= last_sequence); it simply returns the values stored in the image header. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02337">2337</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00070">MetadataBlockHeader::identifier</a>, <a class="el" href="metadata_8h_source.html#l00074">MetadataBlockHeader::lastMediaSequence</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a4cb7b7200e36efb4983cf2c5c5543313" name="a4cb7b7200e36efb4983cf2c5c5543313"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a4cb7b7200e36efb4983cf2c5c5543313">◆ </a></span>aaruf_get_media_serial_number()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_serial_number </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the media serial number recorded in the image metadata. </p>
|
||
<p>Copies the UTF-16LE encoded serial number identifying the specific physical medium. Serial numbers are particularly important for forensic tracking and archival provenance, enabling correlation between the physical item and its digital representation.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for the serial number. May be NULL to determine required size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input holds the buffer size and on output receives the actual serial number length.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Serial number metadata was copied into <code class="param">buffer</code>. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No serial number metadata was stored in the image. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer was too small.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Serial numbers may contain spaces, hyphens, or alphanumeric characters. The library does not normalize or validate these strings. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02756">2756</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00221">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a554f1cbd4c013c46788b2276c3244c32" name="a554f1cbd4c013c46788b2276c3244c32"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a554f1cbd4c013c46788b2276c3244c32">◆ </a></span>aaruf_get_media_tag_type_for_datatype()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_tag_type_for_datatype </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const int32_t</td> <td class="paramname"><span class="paramname"><em>type</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Converts an image data type to an Aaru media tag type. </p>
|
||
<p>Maps the given image data type to the corresponding Aaru media tag type.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">type</td><td>Image data type identifier. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Corresponding Aaru media tag type, or -1 if not found. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="helpers_8c_source.html#l00031">31</a> of file <a class="el" href="helpers_8c_source.html">helpers.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="aaru_8h_source.html#l00974">AACS_CPRM_MKB</a>, <a class="el" href="aaru_8h_source.html#l00972">AACS_DataKeys</a>, <a class="el" href="aaru_8h_source.html#l00973">AACS_LBAExtents</a>, <a class="el" href="aaru_8h_source.html#l00970">AACS_MediaIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00971">AACS_MKB</a>, <a class="el" href="aaru_8h_source.html#l00969">AACS_SerialNumber</a>, <a class="el" href="aaru_8h_source.html#l00968">AACS_VolumeIdentifier</a>, <a class="el" href="enums_8h_source.html#l00083">AacsDataKeys</a>, <a class="el" href="enums_8h_source.html#l00084">AacsLbaExtents</a>, <a class="el" href="enums_8h_source.html#l00081">AacsMediaIdentifier</a>, <a class="el" href="enums_8h_source.html#l00082">AacsMediaKeyBlock</a>, <a class="el" href="enums_8h_source.html#l00080">AacsSerialNumber</a>, <a class="el" href="enums_8h_source.html#l00079">AacsVolumeIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00982">ATA_IDENTIFY</a>, <a class="el" href="enums_8h_source.html#l00093">AtaIdentify</a>, <a class="el" href="aaru_8h_source.html#l00983">ATAPI_IDENTIFY</a>, <a class="el" href="enums_8h_source.html#l00094">AtapiIdentify</a>, <a class="el" href="aaru_8h_source.html#l00964">BD_BCA</a>, <a class="el" href="aaru_8h_source.html#l00966">BD_CartridgeStatus</a>, <a class="el" href="aaru_8h_source.html#l00965">BD_DDS</a>, <a class="el" href="aaru_8h_source.html#l00963">BD_DI</a>, <a class="el" href="aaru_8h_source.html#l00967">BD_SpareArea</a>, <a class="el" href="enums_8h_source.html#l00075">BlurayBca</a>, <a class="el" href="enums_8h_source.html#l00077">BlurayCartridgeStatus</a>, <a class="el" href="enums_8h_source.html#l00076">BlurayDds</a>, <a class="el" href="enums_8h_source.html#l00074">BlurayDi</a>, <a class="el" href="enums_8h_source.html#l00078">BluraySpareArea</a>, <a class="el" href="aaru_8h_source.html#l00939">CD_ATIP</a>, <a class="el" href="aaru_8h_source.html#l00996">CD_FirstTrackPregap</a>, <a class="el" href="aaru_8h_source.html#l00937">CD_FullTOC</a>, <a class="el" href="aaru_8h_source.html#l01003">CD_LeadIn</a>, <a class="el" href="aaru_8h_source.html#l00997">CD_LeadOut</a>, <a class="el" href="aaru_8h_source.html#l00941">CD_MCN</a>, <a class="el" href="aaru_8h_source.html#l00938">CD_PMA</a>, <a class="el" href="aaru_8h_source.html#l00936">CD_SessionInfo</a>, <a class="el" href="aaru_8h_source.html#l00940">CD_TEXT</a>, <a class="el" href="aaru_8h_source.html#l00935">CD_TOC</a>, <a class="el" href="enums_8h_source.html#l00051">CompactDiscAtip</a>, <a class="el" href="enums_8h_source.html#l00107">CompactDiscFirstTrackPregap</a>, <a class="el" href="enums_8h_source.html#l00124">CompactDiscLeadIn</a>, <a class="el" href="enums_8h_source.html#l00052">CompactDiscLeadInCdText</a>, <a class="el" href="enums_8h_source.html#l00108">CompactDiscLeadOut</a>, <a class="el" href="enums_8h_source.html#l00120">CompactDiscMediaCatalogueNumber</a>, <a class="el" href="enums_8h_source.html#l00047">CompactDiscPartialToc</a>, <a class="el" href="enums_8h_source.html#l00050">CompactDiscPma</a>, <a class="el" href="enums_8h_source.html#l00048">CompactDiscSessionInfo</a>, <a class="el" href="enums_8h_source.html#l00049">CompactDiscToc</a>, <a class="el" href="enums_8h_source.html#l00085">CprmMediaKeyBlock</a>, <a class="el" href="aaru_8h_source.html#l00995">DCB</a>, <a class="el" href="aaru_8h_source.html#l00956">DVD_ADIP</a>, <a class="el" href="aaru_8h_source.html#l00945">DVD_BCA</a>, <a class="el" href="aaru_8h_source.html#l00943">DVD_CMI</a>, <a class="el" href="aaru_8h_source.html#l00944">DVD_DiscKey</a>, <a class="el" href="aaru_8h_source.html#l01008">DVD_DiscKey_Decrypted</a>, <a class="el" href="aaru_8h_source.html#l00946">DVD_DMI</a>, <a class="el" href="aaru_8h_source.html#l00947">DVD_MediaIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00948">DVD_MKB</a>, <a class="el" href="aaru_8h_source.html#l00942">DVD_PFI</a>, <a class="el" href="enums_8h_source.html#l00067">DvdAdip</a>, <a class="el" href="enums_8h_source.html#l00056">DvdBca</a>, <a class="el" href="enums_8h_source.html#l00106">DvdDiscControlBlock</a>, <a class="el" href="enums_8h_source.html#l00055">DvdDiscKey</a>, <a class="el" href="enums_8h_source.html#l00125">DvdDiscKeyDecrypted</a>, <a class="el" href="aaru_8h_source.html#l00961">DVDDL_JumpIntervalSize</a>, <a class="el" href="aaru_8h_source.html#l00959">DVDDL_LayerCapacity</a>, <a class="el" href="aaru_8h_source.html#l00962">DVDDL_ManualLayerJumpLBA</a>, <a class="el" href="aaru_8h_source.html#l00960">DVDDL_MiddleZoneAddress</a>, <a class="el" href="enums_8h_source.html#l00072">DvdDlJumpIntervalSize</a>, <a class="el" href="enums_8h_source.html#l00070">DvdDlLayerCapacity</a>, <a class="el" href="enums_8h_source.html#l00073">DvdDlManualLayerJumpLba</a>, <a class="el" href="enums_8h_source.html#l00071">DvdDlMiddleZoneAddress</a>, <a class="el" href="enums_8h_source.html#l00057">DvdDmi</a>, <a class="el" href="enums_8h_source.html#l00054">DvdLeadInCmi</a>, <a class="el" href="enums_8h_source.html#l00058">DvdMediaIdentifier</a>, <a class="el" href="enums_8h_source.html#l00059">DvdMediaKeyBlock</a>, <a class="el" href="enums_8h_source.html#l00053">DvdPfi</a>, <a class="el" href="aaru_8h_source.html#l00954">DVDR_MediaIdentifier</a>, <a class="el" href="aaru_8h_source.html#l00955">DVDR_PFI</a>, <a class="el" href="aaru_8h_source.html#l00953">DVDR_PreRecordedInfo</a>, <a class="el" href="aaru_8h_source.html#l00952">DVDR_RMD</a>, <a class="el" href="aaru_8h_source.html#l00949">DVDRAM_DDS</a>, <a class="el" href="aaru_8h_source.html#l00950">DVDRAM_MediumStatus</a>, <a class="el" href="aaru_8h_source.html#l00951">DVDRAM_SpareArea</a>, <a class="el" href="enums_8h_source.html#l00060">DvdRamDds</a>, <a class="el" href="enums_8h_source.html#l00061">DvdRamMediumStatus</a>, <a class="el" href="enums_8h_source.html#l00062">DvdRamSpareArea</a>, <a class="el" href="enums_8h_source.html#l00065">DvdRMediaIdentifier</a>, <a class="el" href="enums_8h_source.html#l00066">DvdRPfi</a>, <a class="el" href="enums_8h_source.html#l00064">DvdRPrerecordedInfo</a>, <a class="el" href="enums_8h_source.html#l00063">DvdRRmd</a>, <a class="el" href="aaru_8h_source.html#l00994">Floppy_LeadOut</a>, <a class="el" href="enums_8h_source.html#l00105">FloppyLeadOut</a>, <a class="el" href="aaru_8h_source.html#l00957">HDDVD_CPI</a>, <a class="el" href="aaru_8h_source.html#l00958">HDDVD_MediumStatus</a>, <a class="el" href="enums_8h_source.html#l00068">HdDvdCpi</a>, <a class="el" href="enums_8h_source.html#l00069">HdDvdMediumStatus</a>, <a class="el" href="aaru_8h_source.html#l00975">Hybrid_RecognizedLayers</a>, <a class="el" href="enums_8h_source.html#l00086">HybridRecognizedLayers</a>, <a class="el" href="aaru_8h_source.html#l00989">MMC_CID</a>, <a class="el" href="aaru_8h_source.html#l00990">MMC_CSD</a>, <a class="el" href="aaru_8h_source.html#l00977">MMC_DiscInformation</a>, <a class="el" href="aaru_8h_source.html#l00992">MMC_ExtendedCSD</a>, <a class="el" href="aaru_8h_source.html#l00991">MMC_OCR</a>, <a class="el" href="aaru_8h_source.html#l00979">MMC_POWResourcesInformation</a>, <a class="el" href="aaru_8h_source.html#l00978">MMC_TrackResourcesInformation</a>, <a class="el" href="aaru_8h_source.html#l00976">MMC_WriteProtection</a>, <a class="el" href="enums_8h_source.html#l00100">MultiMediaCardCid</a>, <a class="el" href="enums_8h_source.html#l00101">MultiMediaCardCsd</a>, <a class="el" href="enums_8h_source.html#l00103">MultiMediaCardExtendedCsd</a>, <a class="el" href="enums_8h_source.html#l00102">MultiMediaCardOcr</a>, <a class="el" href="aaru_8h_source.html#l00984">PCMCIA_CIS</a>, <a class="el" href="enums_8h_source.html#l00095">PcmciaCis</a>, <a class="el" href="aaru_8h_source.html#l00980">SCSI_INQUIRY</a>, <a class="el" href="aaru_8h_source.html#l00981">SCSI_MODEPAGE_2A</a>, <a class="el" href="aaru_8h_source.html#l00999">SCSI_MODESENSE_10</a>, <a class="el" href="aaru_8h_source.html#l00998">SCSI_MODESENSE_6</a>, <a class="el" href="enums_8h_source.html#l00091">ScsiInquiry</a>, <a class="el" href="enums_8h_source.html#l00088">ScsiMmcDiscInformation</a>, <a class="el" href="enums_8h_source.html#l00090">ScsiMmcPowResourcesInformation</a>, <a class="el" href="enums_8h_source.html#l00089">ScsiMmcTrackResourcesInformation</a>, <a class="el" href="enums_8h_source.html#l00087">ScsiMmcWriteProtection</a>, <a class="el" href="enums_8h_source.html#l00092">ScsiModePage2A</a>, <a class="el" href="enums_8h_source.html#l00110">ScsiModeSense10</a>, <a class="el" href="enums_8h_source.html#l00109">ScsiModeSense6</a>, <a class="el" href="aaru_8h_source.html#l00985">SD_CID</a>, <a class="el" href="aaru_8h_source.html#l00986">SD_CSD</a>, <a class="el" href="aaru_8h_source.html#l00988">SD_OCR</a>, <a class="el" href="aaru_8h_source.html#l00987">SD_SCR</a>, <a class="el" href="enums_8h_source.html#l00096">SecureDigitalCid</a>, <a class="el" href="enums_8h_source.html#l00097">SecureDigitalCsd</a>, <a class="el" href="enums_8h_source.html#l00099">SecureDigitalOcr</a>, <a class="el" href="enums_8h_source.html#l00098">SecureDigitalScr</a>, <a class="el" href="aaru_8h_source.html#l01000">USB_Descriptors</a>, <a class="el" href="enums_8h_source.html#l00111">UsbDescriptors</a>, <a class="el" href="aaru_8h_source.html#l01001">Xbox_DMI</a>, <a class="el" href="aaru_8h_source.html#l01002">Xbox_PFI</a>, <a class="el" href="aaru_8h_source.html#l00993">Xbox_SecuritySector</a>, <a class="el" href="enums_8h_source.html#l00112">XboxDmi</a>, <a class="el" href="enums_8h_source.html#l00113">XboxPfi</a>, and <a class="el" href="enums_8h_source.html#l00104">XboxSecuritySector</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="data_8c_source.html#l00071">process_data_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="af1ca27c052c6cde38a8d6d71e10936db" name="af1ca27c052c6cde38a8d6d71e10936db"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#af1ca27c052c6cde38a8d6d71e10936db">◆ </a></span>aaruf_get_media_title()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_media_title </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">int32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the media title or label captured during image creation. </p>
|
||
<p>Returns the UTF-16LE encoded media title string, representing markings or labels present on the original physical media. This function allows applications to present or archive the media title alongside the image, preserving contextual information from the physical artifact.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for the UTF-16LE title string. May be NULL when querying size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to an int32_t that on input holds the buffer capacity in bytes and on output receives the actual title length.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) The media title was available and copied to <code class="param">buffer</code>. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context pointer is invalid. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_METADATA_NOT_PRESENT</td><td>(-30) No media title metadata exists. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The supplied buffer was insufficient.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Titles may contain international characters, control codes, or mixed casing. The library does not attempt to sanitize or interpret the string. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l02546">2546</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00069">AARUF_ERROR_METADATA_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">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#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00217">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a8e00d26a8e751fbd412868ac4f92a3c0" name="a8e00d26a8e751fbd412868ac4f92a3c0"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a8e00d26a8e751fbd412868ac4f92a3c0">◆ </a></span>aaruf_get_negative_sectors()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_negative_sectors </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint16_t *</td> <td class="paramname"><span class="paramname"><em>sectors</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the number of negative (pre-gap) sectors in the AaruFormat image. </p>
|
||
<p>Returns the count of negative sectors that precede the standard user data area. Negative sectors are used to capture pre-gap data, lead-in areas, and other metadata that exists before the main user-accessible storage region. This is particularly important for optical media (CD, DVD, BD) where the lead-in contains the Table of Contents (TOC) and other essential disc structures, and for audio CDs where pre-gap sectors contain silence or hidden tracks. For most hard disk and floppy disk images, this value is typically zero.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context (must be properly initialized). </td></tr>
|
||
<tr><td class="paramname">sectors</td><td>Pointer to a uint16_t that receives the negative sector count on success.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved the negative sector count. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The context magic number matches AARU_MAGIC</li>
|
||
<li>The sectors parameter is successfully populated with the negative sector count</li>
|
||
<li>The value is taken from ctx->user_data_ddt_header.negative</li>
|
||
<li>For optical media with lead-in data: sectors may be non-zero</li>
|
||
<li>For standard hard disk/floppy images: sectors is typically 0</li>
|
||
<li>Maximum value is 65,535 (uint16_t limit)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Negative Sector Addressing:<ul>
|
||
<li>Negative sectors are addressed with the 'negative' flag set to true</li>
|
||
<li>Sector addresses range from 0 to (negative_sectors - 1)</li>
|
||
<li>When calling <a class="el" href="#a53397980f6b05e3ad0145f2941de16d2" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> or <a class="el" href="#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>:<ul>
|
||
<li>Use negative=true</li>
|
||
<li>Use sector_address in range [0, negative_sectors - 1]</li>
|
||
<li>The actual logical position is before the user data area</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Optical Media Context:<ul>
|
||
<li><b>CD-ROM/CD-DA</b>: Negative sectors contain lead-in area with TOC (Table of Contents). The lead-in typically spans LBA -450000 to -1, though only a portion may be captured. Pre-gap sectors (usually 150 sectors/2 seconds before each track) may also be stored as negative sectors for the first track.</li>
|
||
<li><b>DVD</b>: May contain lead-in with disc structure information, copyright data, and region codes. The lead-in area varies by format (DVD-ROM, DVD-R, DVD+R, etc.).</li>
|
||
<li><b>Blu-ray</b>: Lead-in contains disc information, burst cutting area (BCA), and other metadata. The structure differs between BD-ROM, BD-R, and BD-RE.</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Hard Disk and Floppy Context:<ul>
|
||
<li>Hard disk drives: Negative sectors are typically zero unless capturing special manufacturer reserved areas (HPA, DCO) that precede the standard user area.</li>
|
||
<li>Floppy disks: Negative sectors are typically zero as floppies have a simple linear sector layout without lead-in areas.</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Audio CD Hidden Tracks:<ul>
|
||
<li>Some audio CDs contain hidden tracks in the pre-gap of the first track</li>
|
||
<li>These pre-gap sectors can extend up to several minutes before track 1</li>
|
||
<li>Negative sectors can capture this "hidden" audio data</li>
|
||
<li>The pre-gap for track 1 typically starts at LBA -150 (2 seconds)</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
DDT Header Source:<ul>
|
||
<li>The value is retrieved from ctx->user_data_ddt_header.negative</li>
|
||
<li>The DDT (Deduplication and Data Table) header tracks all sector allocation</li>
|
||
<li>This field is populated during image creation with <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>The value is fixed for read-only images opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
|
||
<li>Maximum representable value is 65,535 (uint16_t)</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Total Addressable Space:<ul>
|
||
<li>Total sectors = negative_sectors + user_sectors + overflow_sectors</li>
|
||
<li>The negative region comes first in logical order</li>
|
||
<li>Followed by the user region [0, user_sectors - 1]</li>
|
||
<li>Followed by the overflow region if present</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Relationship to Image Creation:<ul>
|
||
<li>The negative_sectors value is specified when calling <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>It should be set based on the medium type and imaging requirements:<ul>
|
||
<li>Optical discs: Set to the number of lead-in sectors captured</li>
|
||
<li>Hard disks: Typically 0, unless capturing HPA/DCO areas</li>
|
||
<li>Floppy disks: Typically 0</li>
|
||
<li>Audio CDs: May be non-zero to capture pre-gap hidden tracks</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The sectors parameter is only modified on success (AARUF_STATUS_OK). On error, its value remains unchanged. Initialize it before calling if a default value is needed on failure.</dd>
|
||
<dd>
|
||
This function reads from the in-memory DDT header loaded during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or set during <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. It does not perform file I/O operations and executes quickly.</dd>
|
||
<dd>
|
||
The maximum negative sector count is 65,535 due to the uint16_t storage type. If imaging optical media with larger lead-in areas, some data may not be representable. This limit is generally sufficient for most practical cases.</dd>
|
||
<dd>
|
||
Negative sector data may contain copy-protected or encrypted content (e.g., CSS on DVDs, AACS on Blu-rays). Handle this data according to applicable laws and licensing agreements. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l03417">3417</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="aeeae64b120a10bac5e3d757a07a9691a" name="aeeae64b120a10bac5e3d757a07a9691a"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#aeeae64b120a10bac5e3d757a07a9691a">◆ </a></span>aaruf_get_overflow_sectors()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_overflow_sectors </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint16_t *</td> <td class="paramname"><span class="paramname"><em>sectors</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the number of overflow (post-gap) sectors in the AaruFormat image. </p>
|
||
<p>Returns the count of overflow sectors that follow the standard user data area. Overflow sectors are used to capture post-gap data, lead-out areas, and other metadata that exists after the main user-accessible storage region. This is particularly important for optical media (CD, DVD, BD) where the lead-out marks the physical end of the recorded data and contains disc finalization information, and for multi-session discs where gaps between sessions need to be preserved. For most hard disk and floppy disk images, this value is typically zero.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context (must be properly initialized). </td></tr>
|
||
<tr><td class="paramname">sectors</td><td>Pointer to a uint16_t that receives the overflow sector count on success.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved the overflow sector count. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The context magic number matches AARU_MAGIC</li>
|
||
<li>The sectors parameter is successfully populated with the overflow sector count</li>
|
||
<li>The value is taken from ctx->user_data_ddt_header.overflow</li>
|
||
<li>For optical media with lead-out data: sectors may be non-zero</li>
|
||
<li>For standard hard disk/floppy images: sectors is typically 0</li>
|
||
<li>Maximum value is 65,535 (uint16_t limit)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Overflow Sector Addressing:<ul>
|
||
<li>Overflow sectors are addressed with the 'negative' flag set to false</li>
|
||
<li>Sector addresses range from user_sectors to (user_sectors + overflow_sectors - 1)</li>
|
||
<li>When calling <a class="el" href="#a53397980f6b05e3ad0145f2941de16d2" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> or <a class="el" href="#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>:<ul>
|
||
<li>Use negative=false</li>
|
||
<li>Use sector_address in range [user_sectors, user_sectors + overflow_sectors - 1]</li>
|
||
<li>The actual logical position is after the user data area</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Optical Media Context:<ul>
|
||
<li><b>CD-ROM/CD-DA</b>: Overflow sectors contain the lead-out area, which marks the physical end of the disc's recorded data. The lead-out consists of unreadable sectors filled with specific patterns.</li>
|
||
<li><b>DVD</b>: May contain lead-out with disc finalization data, middle area (for dual-layer), and outer zone. DVD+R/RW discs may have substantial lead-out areas.</li>
|
||
<li><b>Blu-ray</b>: Lead-out contains disc finalization markers and padding. For multi-layer discs, may include middle zones and outer areas.</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Multi-Session and Track Context:<ul>
|
||
<li>Multi-session optical discs have gaps between sessions</li>
|
||
<li>Audio CDs with post-gap after the last track may use overflow sectors</li>
|
||
<li>Track post-gaps (silence after audio tracks) typically 2 seconds/150 sectors</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Hard Disk and Floppy Context:<ul>
|
||
<li>Hard disk drives: Overflow sectors are typically zero unless capturing special manufacturer reserved areas (like DCO or HPA) that follow the standard user area.</li>
|
||
<li>Floppy disks: Overflow sectors are typically zero as floppies have a simple linear sector layout without lead-out areas. They may contain mastering information.</li>
|
||
<li>Some proprietary copy protection schemes may place data beyond the normal capacity, which could be captured as overflow sectors.</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
DDT Header Source:<ul>
|
||
<li>The value is retrieved from ctx->user_data_ddt_header.overflow</li>
|
||
<li>The DDT (Deduplication and Data Table) header tracks all sector allocation</li>
|
||
<li>This field is populated during image creation with <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>The value is fixed for read-only images opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
|
||
<li>Maximum representable value is 65,535 (uint16_t)</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Total Addressable Space:<ul>
|
||
<li>Total sectors = negative_sectors + user_sectors + overflow_sectors</li>
|
||
<li>The negative region comes first in logical order</li>
|
||
<li>Followed by the user region [0, user_sectors - 1]</li>
|
||
<li>Followed by the overflow region at the end</li>
|
||
<li>Overflow represents the final addressable range in the image</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Relationship to Image Creation:<ul>
|
||
<li>The overflow_sectors value is specified when calling <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>It should be set based on the medium type and imaging requirements:<ul>
|
||
<li>Optical discs: Set to the number of lead-out sectors captured</li>
|
||
<li>Multi-session discs: May include inter-session gaps</li>
|
||
<li>Hard disks: Typically 0, unless capturing post-user reserved areas</li>
|
||
<li>Floppy disks: Typically 0</li>
|
||
<li>Copy-protected media: May be non-zero to capture protection schemes</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Forensic Imaging Considerations:<ul>
|
||
<li>Some copy protection schemes intentionally place data in overflow regions</li>
|
||
<li>These "overburn" areas extend beyond the disc's rated capacity</li>
|
||
<li>Overflow sectors ensure complete forensic capture of all readable data</li>
|
||
<li>Important for authenticity verification and copy protection analysis</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The sectors parameter is only modified on success (AARUF_STATUS_OK). On error, its value remains unchanged. Initialize it before calling if a default value is needed on failure.</dd>
|
||
<dd>
|
||
This function reads from the in-memory DDT header loaded during <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or set during <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>. It does not perform file I/O operations and executes quickly.</dd>
|
||
<dd>
|
||
The maximum overflow sector count is 65,535 due to the uint16_t storage type. If imaging optical media with larger lead-out areas or extensive overburn regions, some data may not be representable. This limit is generally sufficient for most practical cases.</dd>
|
||
<dd>
|
||
Overflow sector data may be difficult or impossible to read on some drives, as it often resides in lead-out areas or beyond rated capacity. The presence of overflow sectors in an image indicates the imaging drive was capable of reading these extended areas, but other drives may not be able to access them. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l03552">3552</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a1c8d4faf14212a4c46c1fb47bf25ac1e" name="a1c8d4faf14212a4c46c1fb47bf25ac1e"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a1c8d4faf14212a4c46c1fb47bf25ac1e">◆ </a></span>aaruf_get_tape_file()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_tape_file </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint8_t</td> <td class="paramname"><span class="paramname"><em>partition</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>file</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>starting_block</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>ending_block</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the block range for a specific tape file from an Aaru tape image. </p>
|
||
<p>Queries the tape file hash table to locate a file by its partition and file number, returning the first and last block addresses that define the file's extent on the tape medium. This function provides the core lookup mechanism for accessing logical files stored in tape images.</p>
|
||
<p><b>Tape File Identification:</b> Each tape file is uniquely identified by a combination of:</p><ul>
|
||
<li><b>Partition number</b> (8-bit): The tape partition containing the file</li>
|
||
<li><b>File number</b> (32-bit): The sequential file number within that partition</li>
|
||
</ul>
|
||
<p>These two values are combined into a 64-bit composite key: key = (partition << 32) | file_number</p>
|
||
<p>This composite key is used to perform a hash table lookup in the context's tapeFiles table, which was previously populated by <a class="el" href="tape_8c.html#a829bbac3c17b60efd8f93188a8de8278" title="Processes a tape file metadata block from the image stream.">process_tape_files_block()</a> during image initialization.</p>
|
||
<p><b>Block Range Semantics:</b> The returned block range [FirstBlock, LastBlock] is inclusive on both ends:</p><ul>
|
||
<li>FirstBlock: The first block address where the file begins</li>
|
||
<li>LastBlock: The final block address where the file ends (inclusive)</li>
|
||
<li>Block count: (LastBlock - FirstBlock + 1)</li>
|
||
</ul>
|
||
<p>Block addresses are absolute positions within the tape image's logical block space, not relative to the partition or file.</p>
|
||
<p><b>Typical Usage Flow:</b></p><ol type="1">
|
||
<li>Open an Aaru tape image with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
|
||
<li>Call <a class="el" href="tape_8c.html#a6221f89b294ca55944944a04edb964e3" title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> to get the block range for a specific file</li>
|
||
<li>Use the returned block range to read the file's data blocks</li>
|
||
<li>Repeat for other files as needed</li>
|
||
</ol>
|
||
<p><b>Error Handling:</b> The function performs validation in the following order:</p><ol type="1">
|
||
<li>Context pointer validation (NULL check)</li>
|
||
<li>Magic number verification (ensures valid aaruformat context)</li>
|
||
<li>Hash table lookup for the specified partition/file combination</li>
|
||
</ol>
|
||
<p>If any validation fails, an appropriate error code is returned and the output parameters (starting_block, ending_block) are left unmodified.</p>
|
||
<p><b>Thread Safety:</b> This function performs read-only operations on the context and is safe to call from multiple threads concurrently, provided the context is not being modified by other operations (e.g., during image opening/closing).</p>
|
||
<p><b>Performance Characteristics:</b></p><ul>
|
||
<li>Hash table lookup: O(1) average case</li>
|
||
<li>No I/O operations performed</li>
|
||
<li>Minimal stack usage</li>
|
||
<li>Suitable for high-frequency queries</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramdir"></td><td class="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been successfully opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> and contain a valid tape file hash table. The context is treated as const and is not modified by this operation.</td></tr>
|
||
<tr><td class="paramdir"></td><td class="paramname">partition</td><td>The partition number (0-255) containing the requested file. For single-partition tapes, this is typically 0. Multi-partition tapes may have files in different partitions with potentially overlapping file numbers.</td></tr>
|
||
<tr><td class="paramdir"></td><td class="paramname">file</td><td>The file number within the specified partition. File numbers are typically sequential starting from 0 or 1, but gaps may exist if files were deleted or the tape was written non-sequentially.</td></tr>
|
||
<tr><td class="paramdir">[out]</td><td class="paramname">starting_block</td><td>Pointer to receive the first block address of the file. Must not be NULL. Only modified on success. The value written represents the inclusive start of the file's block range.</td></tr>
|
||
<tr><td class="paramdir">[out]</td><td class="paramname">ending_block</td><td>Pointer to receive the last block address of the file. Must not be NULL. Only modified on success. The value written represents the inclusive end of the file's block range.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved tape file information. Both output parameters have been populated with valid block addresses. The requested partition/file combination exists in the image's file table.</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
|
||
<li>The context pointer is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) The output parameters are not modified.</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_TAPE_FILE_NOT_FOUND</td><td>(-28) The requested partition/file combination does not exist in the image's tape file table. This is returned when:<ul>
|
||
<li>The specified partition number has no files</li>
|
||
<li>The specified file number doesn't exist in the given partition</li>
|
||
<li>The tape file block was not present or failed to load during image open The output parameters are not modified.</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
|
||
<dd>
|
||
The tape file hash table (ctx->tapeFiles) must have been populated during image initialization. If the image doesn't contain a TapeFileBlock, or if that block failed to load, all queries will return AARUF_ERROR_TAPE_FILE_NOT_FOUND.</dd>
|
||
<dd>
|
||
For images without tape file metadata, applications should fall back to direct block-based access or partition-level operations.</dd>
|
||
<dd>
|
||
The returned block addresses are logical block numbers. To read actual data, these must be translated through the appropriate read functions that handle the image's block encoding, compression, and DDT mapping.</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The output parameter pointers must be valid. Passing NULL for either starting_block or ending_block will cause undefined behavior (likely a crash when the function attempts to dereference them on success).</dd>
|
||
<dd>
|
||
If the same partition/file combination appears multiple times in the TapeFileBlock, only the last occurrence is retained (due to HASH_REPLACE behavior in process_tape_files_block). This should not occur in valid images but may happen with corrupted or malformed tape file metadata.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="tape_8c.html#a829bbac3c17b60efd8f93188a8de8278" title="Processes a tape file metadata block from the image stream.">process_tape_files_block()</a> for tape file table initialization </dd>
|
||
<dd>
|
||
<a class="el" href="structTapeFileEntry.html" title="Describes a single logical file on a tape medium.">TapeFileEntry</a> for the structure defining file block ranges </dd>
|
||
<dd>
|
||
<a class="el" href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a> for the hash table entry structure </dd>
|
||
<dd>
|
||
<a class="el" href="tape_8c.html#a91c40d91fdeb98193d6eeb95f16d8973" title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> for partition-level queries (if available) </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="tape_8c_source.html#l00569">569</a> of file <a class="el" href="tape_8c_source.html">tape.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00067">AARUF_ERROR_TAPE_FILE_NOT_FOUND</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00129">TapeFileHashEntry::fileEntry</a>, <a class="el" href="tape_8h_source.html#l00139">TapeFileEntry::FirstBlock</a>, <a class="el" href="tape_8h_source.html#l00142">TapeFileEntry::LastBlock</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00302">aaruformat_context::tape_files</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ab1ca1a092699df0f43ea050812f6c6b1" name="ab1ca1a092699df0f43ea050812f6c6b1"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ab1ca1a092699df0f43ea050812f6c6b1">◆ </a></span>aaruf_get_tape_partition()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_tape_partition </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint8_t</td> <td class="paramname"><span class="paramname"><em>partition</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>starting_block</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>ending_block</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the block range for a specific tape partition from an Aaru tape image. </p>
|
||
<p>Queries the tape partition hash table to locate a partition by its partition number, returning the first and last block addresses that define the partition's extent on the tape medium. This function provides the core lookup mechanism for accessing partition layout information in tape images.</p>
|
||
<p><b>Tape Partition Identification:</b> Each tape partition is uniquely identified by its partition number (0-255). Most tapes have a single partition (partition 0), but multi-partition formats like LTO, DLT, and AIT support multiple partitions with independent block address spaces.</p>
|
||
<p>The partition number is used as the hash table key to perform a lookup in the context's tapePartitions table, which was previously populated by <a class="el" href="tape_8c.html#aa76718b0402b1a28be3d563d5e62028e" title="Processes a tape partition metadata block from the image stream.">process_tape_partitions_block()</a> during image initialization.</p>
|
||
<p><b>Block Range Semantics:</b> The returned block range [FirstBlock, LastBlock] is inclusive on both ends:</p><ul>
|
||
<li>FirstBlock: The first block address in the partition (often 0, but format-dependent)</li>
|
||
<li>LastBlock: The final block address in the partition (inclusive)</li>
|
||
<li>Block count: (LastBlock - FirstBlock + 1)</li>
|
||
</ul>
|
||
<p>Block addresses are local to each partition. Different partitions may have overlapping logical block numbers (e.g., both partition 0 and partition 1 can have blocks 0-1000). When accessing blocks, both the partition number and block number are required for unique identification.</p>
|
||
<p><b>Typical Usage Flow:</b></p><ol type="1">
|
||
<li>Open an Aaru tape image with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
|
||
<li>Call <a class="el" href="tape_8c.html#a91c40d91fdeb98193d6eeb95f16d8973" title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> to get the block range for a specific partition</li>
|
||
<li>Use the returned block range to understand partition boundaries</li>
|
||
<li>Access files within the partition using <a class="el" href="tape_8c.html#a6221f89b294ca55944944a04edb964e3" title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a></li>
|
||
<li>Repeat for other partitions as needed</li>
|
||
</ol>
|
||
<p><b>Error Handling:</b> The function performs validation in the following order:</p><ol type="1">
|
||
<li>Context pointer validation (NULL check)</li>
|
||
<li>Magic number verification (ensures valid aaruformat context)</li>
|
||
<li>Hash table lookup for the specified partition number</li>
|
||
</ol>
|
||
<p>If any validation fails, an appropriate error code is returned and the output parameters (starting_block, ending_block) are left unmodified.</p>
|
||
<p><b>Thread Safety:</b> This function performs read-only operations on the context and is safe to call from multiple threads concurrently, provided the context is not being modified by other operations (e.g., during image opening/closing).</p>
|
||
<p><b>Performance Characteristics:</b></p><ul>
|
||
<li>Hash table lookup: O(1) average case</li>
|
||
<li>No I/O operations performed</li>
|
||
<li>Minimal stack usage</li>
|
||
<li>Suitable for high-frequency queries</li>
|
||
</ul>
|
||
<p><b>Partition Layout Information:</b> The partition metadata is essential for:</p><ul>
|
||
<li>Understanding the physical organization of the tape</li>
|
||
<li>Determining partition boundaries for file access</li>
|
||
<li>Validating that file block ranges fall within partition limits</li>
|
||
<li>Supporting multi-partition tape formats correctly</li>
|
||
<li>Preserving original tape partitioning schemes</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramdir"></td><td class="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been successfully opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> and contain a valid tape partition hash table. The context is treated as const and is not modified by this operation.</td></tr>
|
||
<tr><td class="paramdir"></td><td class="paramname">partition</td><td>The partition number (0-255) to query. For single-partition tapes, this is typically 0. Multi-partition tapes may have multiple partitions numbered sequentially from 0.</td></tr>
|
||
<tr><td class="paramdir">[out]</td><td class="paramname">starting_block</td><td>Pointer to receive the first block address of the partition. Must not be NULL. Only modified on success. The value written represents the inclusive start of the partition's block range (often 0, but format-dependent).</td></tr>
|
||
<tr><td class="paramdir">[out]</td><td class="paramname">ending_block</td><td>Pointer to receive the last block address of the partition. Must not be NULL. Only modified on success. The value written represents the inclusive end of the partition's block range.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved tape partition information. Both output parameters have been populated with valid block addresses. The requested partition exists in the image's partition table.</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
|
||
<li>The context pointer is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) The output parameters are not modified.</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_TAPE_PARTITION_NOT_FOUND</td><td>(-29) The requested partition number does not exist in the image's tape partition table. This is returned when:<ul>
|
||
<li>The specified partition number was not defined in the TapePartitionBlock</li>
|
||
<li>The tape partition block was not present or failed to load during image open</li>
|
||
<li>The partition number is out of range for this tape The output parameters are not modified.</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
|
||
<dd>
|
||
The tape partition hash table (ctx->tapePartitions) must have been populated during image initialization. If the image doesn't contain a TapePartitionBlock, or if that block failed to load, all queries will return AARUF_ERROR_TAPE_PARTITION_NOT_FOUND.</dd>
|
||
<dd>
|
||
For images without tape partition metadata, the entire tape may be treated as a single implicit partition, and applications should handle the absence of partition information gracefully.</dd>
|
||
<dd>
|
||
The returned block addresses are logical block numbers within the partition's address space. To read actual data, these must be combined with the partition number and translated through the appropriate read functions.</dd>
|
||
<dd>
|
||
Partition metadata is primarily informational and used for validation. File access is primarily driven by file metadata (TapeFileBlock), which references partition numbers to establish context.</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The output parameter pointers must be valid. Passing NULL for either starting_block or ending_block will cause undefined behavior (likely a crash when the function attempts to dereference them on success).</dd>
|
||
<dd>
|
||
If the same partition number appears multiple times in the TapePartitionBlock, only the last occurrence is retained (due to HASH_REPLACE behavior in process_tape_partitions_block). This should not occur in valid images but may happen with corrupted or malformed partition metadata.</dd>
|
||
<dd>
|
||
Single-partition tapes may not include a TapePartitionBlock at all, in which case this function will always return AARUF_ERROR_TAPE_PARTITION_NOT_FOUND. Applications should handle this case and assume a default partition 0 spanning the entire tape.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="tape_8c.html#aa76718b0402b1a28be3d563d5e62028e" title="Processes a tape partition metadata block from the image stream.">process_tape_partitions_block()</a> for partition table initialization </dd>
|
||
<dd>
|
||
<a class="el" href="structTapePartitionEntry.html" title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> for the structure defining partition block ranges </dd>
|
||
<dd>
|
||
<a class="el" href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a> for the hash table entry structure </dd>
|
||
<dd>
|
||
<a class="el" href="tape_8c.html#a6221f89b294ca55944944a04edb964e3" title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> for file-level queries within partitions </dd>
|
||
<dd>
|
||
<a class="el" href="tape_8c.html#aa16d4457093df66246ce5622c3565a17" title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> for setting partition information during write </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="tape_8c_source.html#l00982">982</a> of file <a class="el" href="tape_8c_source.html">tape.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00068">AARUF_ERROR_TAPE_PARTITION_NOT_FOUND</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="tape_8h_source.html#l00323">TapePartitionEntry::FirstBlock</a>, <a class="el" href="tape_8h_source.html#l00325">TapePartitionEntry::LastBlock</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00136">TapePartitionHashEntry::partitionEntry</a>, <a class="el" href="context_8h_source.html#l00303">aaruformat_context::tape_partitions</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a2ce65757ca5209f17d467c51ba7d445d" name="a2ce65757ca5209f17d467c51ba7d445d"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a2ce65757ca5209f17d467c51ba7d445d">◆ </a></span>aaruf_get_tracks()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_tracks </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieve the array of track descriptors contained in an opened AaruFormat image. </p>
|
||
<p>Provides the caller with a contiguous array of all track entries found in the image. The function follows a two-step usage pattern allowing callers to query the required buffer size before performing the actual copy.</p>
|
||
<p>Usage pattern:</p><ul>
|
||
<li>First call with buffer == NULL (or *length smaller than required). The function sets *length to the required size and returns AARUF_ERROR_BUFFER_TOO_SMALL.</li>
|
||
<li>Allocate a buffer of at least *length bytes and call again. On success, the function copies all <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures and returns AARUF_STATUS_OK with *length set to the bytes copied.</li>
|
||
</ul>
|
||
<p>The returned data is a raw copy of internal <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures (host endianness). The caller does not assume ownership of internal memory; only the caller-provided buffer should be freed by the caller.</p>
|
||
<p>Preconditions (</p><dl class="section pre"><dt>Precondition</dt><dd>):<ul>
|
||
<li></li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
context is a valid pointer to an aaruformatContext previously returned by an open function.<ul>
|
||
<li></li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
context->magic == AARU_MAGIC.<ul>
|
||
<li></li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
<a class="el" href="optical_8c.html#a375a516fdf6f81e997365d93b21f6708" title="Parse and integrate a Tracks block from the image stream into the context.">process_tracks_block()</a> has run (implicitly done during image open) populating trackEntries.</dd></dl>
|
||
<p>Thread safety:</p><ul>
|
||
<li>Read-only access; safe for concurrent calls on different contexts.</li>
|
||
<li>Concurrent calls on the same context are safe only if no other thread is modifying/destroying it.</li>
|
||
</ul>
|
||
<p>Buffer sizing logic:</p><ul>
|
||
<li>required_length = ctx->tracksHeader.entries * sizeof(TrackEntry)</li>
|
||
<li>If buffer == NULL OR *length < required_length => *length updated, return AARUF_ERROR_BUFFER_TOO_SMALL.</li>
|
||
<li>On success *length == required_length.</li>
|
||
</ul>
|
||
<p>Error strategy:</p><ul>
|
||
<li>Validation failures: return specific error codes and log through <a class="el" href="log_8h.html#a053d6037d543b84ce59308ce71d15cd1">FATAL()</a>/TRACE().</li>
|
||
<li>No partial copies are performed.</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Opaque pointer that MUST point to a valid aaruformatContext. </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Destination buffer for a copy of all <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures, or NULL to query size. </td></tr>
|
||
<tr><td class="paramname">length</td><td>In/Out: On entry capacity of buffer (ignored if buffer == NULL). On return required or copied size in bytes. Must not be NULL.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>int32_t API status code. </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>Success; buffer filled. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>context is NULL or not a valid libaaruformat context. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_TRACK_NOT_FOUND</td><td>No tracks present (entries == 0 or internal array NULL). </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>Sizing query / provided buffer insufficient; *length updated.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>Passing an invalid context yields an error; no data is written to buffer. </dd>
|
||
<dd>
|
||
The function never performs partial copies.</dd></dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Order of <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> elements matches on-disk order. </dd>
|
||
<dd>
|
||
Caller may further filter (e.g., data vs audio) after retrieval.</dd></dl>
|
||
<dl class="section since"><dt>Since</dt><dd>1.0</dd></dl>
|
||
<p>Usage example (conceptual):</p><ol type="1">
|
||
<li>Open an image obtaining a valid aaruformatContext pointer.</li>
|
||
<li>Invoke aaruf_get_tracks(ctx, NULL, &size) to query required buffer size (expect AARUF_ERROR_BUFFER_TOO_SMALL).</li>
|
||
<li>Allocate a buffer of "size" bytes.</li>
|
||
<li>Invoke aaruf_get_tracks(ctx, buffer, &size) again; on AARUF_STATUS_OK iterate over (size / sizeof(TrackEntry)) entries.</li>
|
||
<li>Free the buffer and close the image when done. </li>
|
||
</ol>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="optical_8c_source.html#l00281">281</a> of file <a class="el" href="optical_8c_source.html">optical.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00052">AARUF_ERROR_TRACK_NOT_FOUND</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="context_8h_source.html#l00242">aaruformat_context::track_entries</a>, and <a class="el" href="context_8h_source.html#l00244">aaruformat_context::tracks_header</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a7e63f10ff3ea353c8c3944cd836a85ee" name="a7e63f10ff3ea353c8c3944cd836a85ee"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a7e63f10ff3ea353c8c3944cd836a85ee">◆ </a></span>aaruf_get_user_sectors()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_user_sectors </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>sectors</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Retrieves the total number of user-accessible sectors in the AaruFormat image. </p>
|
||
<p>Returns the count of standard user data sectors in the image, excluding any negative (pre-gap) or overflow (post-gap) sectors. This represents the primary addressable sector range that contains the main user data, typically corresponding to the logical capacity of the storage medium as it would be seen by an operating system or file system. For optical media, this excludes lead-in and lead-out areas. For hard disks, this represents the standard LBA-addressable range.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformat context (must be properly initialized). </td></tr>
|
||
<tr><td class="paramname">sectors</td><td>Pointer to a uint64_t that receives the total user sector count on success.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved the user sector count. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The context magic number matches AARU_MAGIC</li>
|
||
<li>The sectors parameter is successfully populated with the user sector count</li>
|
||
<li>The value is taken from ctx->user_data_ddt_header.blocks</li>
|
||
<li>For block devices: sectors typically equals the total capacity in sectors</li>
|
||
<li>For optical media: sectors represents the user data area excluding lead-in/lead-out</li>
|
||
<li>For tape media: sectors may represent the total block count across all files</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Sector Range Context:<ul>
|
||
<li>User sectors represent the standard addressable range: 0 to (user_sectors - 1)</li>
|
||
<li>Total addressable sectors = negative_sectors + user_sectors + overflow_sectors</li>
|
||
<li>Negative sectors precede user sectors (pre-gap, lead-in)</li>
|
||
<li>Overflow sectors follow user sectors (post-gap, lead-out)</li>
|
||
<li>Use <a class="el" href="metadata_8c.html#a8e00d26a8e751fbd412868ac4f92a3c0" title="Retrieves the number of negative (pre-gap) sectors in the AaruFormat image.">aaruf_get_negative_sectors()</a> to get the negative sector count</li>
|
||
<li>Use <a class="el" href="metadata_8c.html#aeeae64b120a10bac5e3d757a07a9691a" title="Retrieves the number of overflow (post-gap) sectors in the AaruFormat image.">aaruf_get_overflow_sectors()</a> to get the overflow sector count</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Media Type Considerations:<ul>
|
||
<li><b>Optical Media (CD/DVD/BD)</b>: User sectors exclude lead-in and lead-out areas. Negative sectors may contain TOC and pre-gap data. Overflow sectors may contain post-gap and lead-out data.</li>
|
||
<li><b>Hard Disk Drives</b>: User sectors represent the full LBA range. Negative and overflow sectors are typically zero unless capturing special areas.</li>
|
||
<li><b>Floppy Disks</b>: User sectors represent the standard formatted capacity.</li>
|
||
<li><b>Tape Media</b>: User sectors may represent the total block count. Negative and overflow sectors are typically not used for tape.</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
DDT Header Source:<ul>
|
||
<li>The value is retrieved from ctx->user_data_ddt_header.blocks</li>
|
||
<li>The DDT (Deduplication and Data Table) header tracks sector allocation</li>
|
||
<li>This field is populated during image creation with <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>The value is fixed for read-only images opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
|
||
<li>For write-enabled images, this represents the allocated capacity</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Addressing and I/O Operations:<ul>
|
||
<li>When reading/writing sectors with <a class="el" href="#a53397980f6b05e3ad0145f2941de16d2" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> or <a class="el" href="#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>:<ul>
|
||
<li>Set negative=false and use sector_address in range [0, user_sectors - 1]</li>
|
||
<li>For negative sectors: set negative=true, sector_address in [0, negative_sectors - 1]</li>
|
||
<li>For overflow sectors: set negative=false, sector_address in [user_sectors, user_sectors + overflow_sectors</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<ul>
|
||
<li>1]</li>
|
||
</ul>
|
||
<dl class="section note"><dt>Note</dt><dd>Relationship to Image Creation:<ul>
|
||
<li>The user_sectors value is specified when calling <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>It should match the logical capacity of the medium being imaged</li>
|
||
<li>For forensic images, ensure it matches the source medium exactly</li>
|
||
<li>For virtual disks, set it to the desired capacity </li>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="metadata_8c_source.html#l03292">3292</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="ddt_8h_source.html#l00150">DdtHeader2::blocks</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ac5f5334a51424028574a5433a0e24b20" name="ac5f5334a51424028574a5433a0e24b20"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ac5f5334a51424028574a5433a0e24b20">◆ </a></span>aaruf_get_xml_mediatype()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_get_xml_mediatype </td>
|
||
<td>(</td>
|
||
<td class="paramtype">int32_t</td> <td class="paramname"><span class="paramname"><em>type</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="helpers_8c_source.html#l00339">339</a> of file <a class="el" href="helpers_8c_source.html">helpers.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="aaru_8h_source.html#l00160">BDR</a>, <a class="el" href="aaru_8h_source.html#l00161">BDRE</a>, <a class="el" href="aaru_8h_source.html#l00163">BDREXL</a>, <a class="el" href="aaru_8h_source.html#l00159">BDROM</a>, <a class="el" href="aaru_8h_source.html#l00162">BDRXL</a>, <a class="el" href="enums_8h_source.html#l00219">BlockMedia</a>, <a class="el" href="aaru_8h_source.html#l00170">CBHD</a>, <a class="el" href="aaru_8h_source.html#l00106">CD</a>, <a class="el" href="aaru_8h_source.html#l00237">CD32</a>, <a class="el" href="aaru_8h_source.html#l00107">CDDA</a>, <a class="el" href="aaru_8h_source.html#l00109">CDEG</a>, <a class="el" href="aaru_8h_source.html#l00108">CDG</a>, <a class="el" href="aaru_8h_source.html#l00110">CDI</a>, <a class="el" href="aaru_8h_source.html#l00130">CDIREADY</a>, <a class="el" href="aaru_8h_source.html#l00126">CDMIDI</a>, <a class="el" href="aaru_8h_source.html#l00114">CDMO</a>, <a class="el" href="aaru_8h_source.html#l00117">CDMRW</a>, <a class="el" href="aaru_8h_source.html#l00113">CDPLUS</a>, <a class="el" href="aaru_8h_source.html#l00115">CDR</a>, <a class="el" href="aaru_8h_source.html#l00111">CDROM</a>, <a class="el" href="aaru_8h_source.html#l00112">CDROMXA</a>, <a class="el" href="aaru_8h_source.html#l00116">CDRW</a>, <a class="el" href="aaru_8h_source.html#l00236">CDTV</a>, <a class="el" href="aaru_8h_source.html#l00127">CDV</a>, <a class="el" href="aaru_8h_source.html#l00122">DDCD</a>, <a class="el" href="aaru_8h_source.html#l00123">DDCDR</a>, <a class="el" href="aaru_8h_source.html#l00124">DDCDRW</a>, <a class="el" href="aaru_8h_source.html#l00125">DTSCD</a>, <a class="el" href="aaru_8h_source.html#l00146">DVDDownload</a>, <a class="el" href="aaru_8h_source.html#l00139">DVDPR</a>, <a class="el" href="aaru_8h_source.html#l00143">DVDPRDL</a>, <a class="el" href="aaru_8h_source.html#l00140">DVDPRW</a>, <a class="el" href="aaru_8h_source.html#l00141">DVDPRWDL</a>, <a class="el" href="aaru_8h_source.html#l00137">DVDR</a>, <a class="el" href="aaru_8h_source.html#l00144">DVDRAM</a>, <a class="el" href="aaru_8h_source.html#l00142">DVDRDL</a>, <a class="el" href="aaru_8h_source.html#l00136">DVDROM</a>, <a class="el" href="aaru_8h_source.html#l00138">DVDRW</a>, <a class="el" href="aaru_8h_source.html#l00145">DVDRWDL</a>, <a class="el" href="aaru_8h_source.html#l00167">EVD</a>, <a class="el" href="aaru_8h_source.html#l00174">FDDVD</a>, <a class="el" href="aaru_8h_source.html#l00132">FMTOWNS</a>, <a class="el" href="aaru_8h_source.html#l00168">FVD</a>, <a class="el" href="aaru_8h_source.html#l00224">GDR</a>, <a class="el" href="aaru_8h_source.html#l00223">GDROM</a>, <a class="el" href="aaru_8h_source.html#l00502">GOD</a>, <a class="el" href="aaru_8h_source.html#l00152">HDDVDR</a>, <a class="el" href="aaru_8h_source.html#l00151">HDDVDRAM</a>, <a class="el" href="aaru_8h_source.html#l00154">HDDVDRDL</a>, <a class="el" href="aaru_8h_source.html#l00150">HDDVDROM</a>, <a class="el" href="aaru_8h_source.html#l00153">HDDVDRW</a>, <a class="el" href="aaru_8h_source.html#l00155">HDDVDRWDL</a>, <a class="el" href="aaru_8h_source.html#l00171">HDVMD</a>, <a class="el" href="aaru_8h_source.html#l00169">HVD</a>, <a class="el" href="aaru_8h_source.html#l00232">JaguarCD</a>, <a class="el" href="aaru_8h_source.html#l00178">LD</a>, <a class="el" href="aaru_8h_source.html#l00179">LDROM</a>, <a class="el" href="aaru_8h_source.html#l00180">LDROM2</a>, <a class="el" href="aaru_8h_source.html#l00181">LVROM</a>, <a class="el" href="aaru_8h_source.html#l00221">MEGACD</a>, <a class="el" href="aaru_8h_source.html#l00182">MegaLD</a>, <a class="el" href="aaru_8h_source.html#l00226">MilCD</a>, <a class="el" href="aaru_8h_source.html#l00235">NeoGeoCD</a>, <a class="el" href="aaru_8h_source.html#l00238">Nuon</a>, <a class="el" href="enums_8h_source.html#l00218">OpticalDisc</a>, <a class="el" href="aaru_8h_source.html#l00120">PCD</a>, <a class="el" href="aaru_8h_source.html#l00234">PCFX</a>, <a class="el" href="aaru_8h_source.html#l00702">Pippin</a>, <a class="el" href="aaru_8h_source.html#l00239">Playdia</a>, <a class="el" href="aaru_8h_source.html#l00203">PS1CD</a>, <a class="el" href="aaru_8h_source.html#l00204">PS2CD</a>, <a class="el" href="aaru_8h_source.html#l00205">PS2DVD</a>, <a class="el" href="aaru_8h_source.html#l00207">PS3BD</a>, <a class="el" href="aaru_8h_source.html#l00206">PS3DVD</a>, <a class="el" href="aaru_8h_source.html#l00208">PS4BD</a>, <a class="el" href="aaru_8h_source.html#l00121">SACD</a>, <a class="el" href="aaru_8h_source.html#l00222">SATURNCD</a>, <a class="el" href="aaru_8h_source.html#l00231">SuperCDROM2</a>, <a class="el" href="aaru_8h_source.html#l00119">SVCD</a>, <a class="el" href="aaru_8h_source.html#l00173">SVOD</a>, <a class="el" href="aaru_8h_source.html#l00233">ThreeDO</a>, <a class="el" href="aaru_8h_source.html#l00209">UMD</a>, <a class="el" href="aaru_8h_source.html#l00118">VCD</a>, <a class="el" href="aaru_8h_source.html#l00172">VCDHD</a>, <a class="el" href="aaru_8h_source.html#l00771">VideoNow</a>, <a class="el" href="aaru_8h_source.html#l00772">VideoNowColor</a>, <a class="el" href="aaru_8h_source.html#l00773">VideoNowXp</a>, <a class="el" href="aaru_8h_source.html#l00512">WOD</a>, <a class="el" href="aaru_8h_source.html#l00513">WUOD</a>, <a class="el" href="aaru_8h_source.html#l00214">XGD</a>, <a class="el" href="aaru_8h_source.html#l00215">XGD2</a>, <a class="el" href="aaru_8h_source.html#l00216">XGD3</a>, and <a class="el" href="aaru_8h_source.html#l00217">XGD4</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>, and <a class="el" href="open_8c_source.html#l00125">aaruf_open()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a74c444fbd394f58aefd2fabff221231b" name="a74c444fbd394f58aefd2fabff221231b"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a74c444fbd394f58aefd2fabff221231b">◆ </a></span>aaruf_identify()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int aaruf_identify </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>filename</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Identifies a file as an AaruFormat image using a file path. </p>
|
||
<p>Opens the file at the given path and determines if it is an AaruFormat image by examining the file header for valid AaruFormat signatures and version information. This function provides a simple file-based interface that handles file opening, identification, and cleanup automatically. It delegates the actual identification logic to <a class="el" href="identify_8c.html#a6f30353aff3ece1e889542c26f7146e2" title="Identifies a file as an AaruFormat image using an open stream.">aaruf_identify_stream()</a>.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">filename</td><td>Path to the file to identify (must be accessible and readable).</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following values: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">100</td><td>Maximum confidence - Definitive AaruFormat image. This is returned when:<ul>
|
||
<li>The file header contains a valid AaruFormat signature (DIC_MAGIC or AARU_MAGIC)</li>
|
||
<li>The image major version is less than or equal to the supported version (AARUF_VERSION)</li>
|
||
<li>The file structure passes all header validation checks</li>
|
||
<li>This indicates the file is definitely a supported AaruFormat image</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">0</td><td>Not recognized - File is not an AaruFormat image. This is returned when:<ul>
|
||
<li>The file header doesn't contain a recognized AaruFormat signature</li>
|
||
<li>The image major version exceeds the maximum supported version</li>
|
||
<li>The file header cannot be read completely (file too small or corrupted)</li>
|
||
<li>The file format doesn't match AaruFormat specifications</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">Positive</td><td>errno values - File access errors from system calls. Common values include:<ul>
|
||
<li>ENOENT (2) - File not found or path doesn't exist</li>
|
||
<li>EACCES (13) - Permission denied, file not readable</li>
|
||
<li>EISDIR (21) - Path refers to a directory, not a file</li>
|
||
<li>EMFILE (24) - Too many open files (process limit reached)</li>
|
||
<li>ENFILE (23) - System limit on open files reached</li>
|
||
<li>ENOMEM (12) - Insufficient memory to open file</li>
|
||
<li>EIO (5) - I/O error occurred during file access</li>
|
||
<li>Other platform-specific errno values from fopen()</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Identification Process:<ul>
|
||
<li>Opens the file in binary read mode ("rb")</li>
|
||
<li>Delegates identification to <a class="el" href="identify_8c.html#a6f30353aff3ece1e889542c26f7146e2" title="Identifies a file as an AaruFormat image using an open stream.">aaruf_identify_stream()</a> for actual header analysis</li>
|
||
<li>Automatically closes the file stream regardless of identification result</li>
|
||
<li>Returns system errno values directly if file opening fails</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Confidence Scoring:<ul>
|
||
<li>Uses binary scoring: 100 (definitive match) or 0 (no match)</li>
|
||
<li>No intermediate confidence levels are returned</li>
|
||
<li>Designed for simple yes/no identification rather than probabilistic matching</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Version Compatibility:<ul>
|
||
<li>Only recognizes AaruFormat versions up to AARUF_VERSION</li>
|
||
<li>Future versions beyond library support are treated as unrecognized</li>
|
||
<li>Backwards compatible with older DIC_MAGIC identifiers</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The function opens and closes the file for each identification. For repeated operations on the same file, consider using <a class="el" href="identify_8c.html#a6f30353aff3ece1e889542c26f7146e2" title="Identifies a file as an AaruFormat image using an open stream.">aaruf_identify_stream()</a> with a pre-opened stream for better performance.</dd>
|
||
<dd>
|
||
File access permissions and availability are checked at runtime. Network files or files on removable media may cause variable access times.</dd>
|
||
<dd>
|
||
The function performs minimal file content validation. A positive result indicates the file appears to be AaruFormat but doesn't guarantee the entire file is valid or uncorrupted. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="identify_8c_source.html#l00084">84</a> of file <a class="el" href="identify_8c_source.html">identify.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="identify_8c_source.html#l00163">aaruf_identify_stream()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a6f30353aff3ece1e889542c26f7146e2" name="a6f30353aff3ece1e889542c26f7146e2"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a6f30353aff3ece1e889542c26f7146e2">◆ </a></span>aaruf_identify_stream()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int aaruf_identify_stream </td>
|
||
<td>(</td>
|
||
<td class="paramtype">FILE *</td> <td class="paramname"><span class="paramname"><em>image_stream</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Identifies a file as an AaruFormat image using an open stream. </p>
|
||
<p>Determines if the provided stream is an AaruFormat image by reading and validating the file header at the beginning of the stream. This function performs the core identification logic by checking for valid AaruFormat signatures and version compatibility. It's designed to work with any FILE stream, making it suitable for integration with existing file handling code.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">image_stream</td><td>Open FILE stream positioned at any location (will be repositioned to start).</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following values: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">100</td><td>Maximum confidence - Definitive AaruFormat image. This is returned when:<ul>
|
||
<li>The stream is successfully repositioned to the beginning</li>
|
||
<li>The AaruFormat header is successfully read (<a class="el" href="structAaruHeader.html" title="Version 1 container header placed at offset 0 for legacy / initial format.">AaruHeader</a> structure)</li>
|
||
<li>The header identifier matches either DIC_MAGIC or AARU_MAGIC (valid signatures)</li>
|
||
<li>The image major version is less than or equal to AARUF_VERSION (supported version)</li>
|
||
<li>All validation checks pass indicating a compatible AaruFormat image</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">0</td><td>Not recognized - Stream is not an AaruFormat image. This is returned when:<ul>
|
||
<li>The stream parameter is NULL</li>
|
||
<li>Cannot read a complete <a class="el" href="structAaruHeader.html" title="Version 1 container header placed at offset 0 for legacy / initial format.">AaruHeader</a> structure from the stream (file too small)</li>
|
||
<li>The header identifier doesn't match DIC_MAGIC or AARU_MAGIC (wrong format)</li>
|
||
<li>The image major version exceeds AARUF_VERSION (unsupported future version)</li>
|
||
<li>Any validation check fails indicating the stream is not a valid AaruFormat image</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Stream Handling:<ul>
|
||
<li>Always seeks to position 0 at the beginning of the function</li>
|
||
<li>Reads exactly one <a class="el" href="structAaruHeader.html" title="Version 1 container header placed at offset 0 for legacy / initial format.">AaruHeader</a> structure (size depends on format version)</li>
|
||
<li>Does not restore the original stream position after identification</li>
|
||
<li>Stream remains open and positioned after the header on function return</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Signature Recognition:<ul>
|
||
<li>DIC_MAGIC: Legacy identifier from original DiscImageChef format</li>
|
||
<li>AARU_MAGIC: Current AaruFormat identifier</li>
|
||
<li>Both signatures are accepted for backwards compatibility</li>
|
||
<li>Signature validation is performed using exact byte matching</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Version Validation:<ul>
|
||
<li>Only checks the major version number for compatibility</li>
|
||
<li>Minor version differences are ignored (assumed backwards compatible)</li>
|
||
<li>Future major versions are rejected to prevent compatibility issues</li>
|
||
<li>Version check prevents attempting to read unsupported format variants</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Confidence Scoring:<ul>
|
||
<li>Binary result: 100 (definitive) or 0 (not recognized)</li>
|
||
<li>No probabilistic or partial matching</li>
|
||
<li>Designed for definitive identification rather than format detection</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The function modifies the stream position by seeking to the beginning and reading the header. The stream position is not restored.</dd>
|
||
<dd>
|
||
This function performs only header-level validation. A positive result indicates the file appears to have a valid AaruFormat header but doesn't guarantee the entire image structure is valid or uncorrupted.</dd>
|
||
<dd>
|
||
The stream must support seeking operations. Non-seekable streams (like pipes or network streams) may cause undefined behavior.</dd>
|
||
<dd>
|
||
No error codes are returned for I/O failures during header reading. Such failures result in a return value of 0 (not recognized). </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="identify_8c_source.html#l00163">163</a> of file <a class="el" href="identify_8c_source.html">identify.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="consts_8h_source.html#l00068">AARUF_VERSION</a>, <a class="el" href="consts_8h_source.html#l00061">DIC_MAGIC</a>, <a class="el" href="header_8h_source.html#l00078">AaruHeader::identifier</a>, and <a class="el" href="header_8h_source.html#l00080">AaruHeader::imageMajorVersion</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="identify_8c_source.html#l00084">aaruf_identify()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a12f3cbc43c2f57a11fbba32a71ba2704" name="a12f3cbc43c2f57a11fbba32a71ba2704"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a12f3cbc43c2f57a11fbba32a71ba2704">◆ </a></span>aaruf_lzma_decode_buffer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_lzma_decode_buffer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>dst_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>dst_size</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>src_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>src_len</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>props</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const size_t</td> <td class="paramname"><span class="paramname"><em>props_size</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Decodes an LZMA-compressed buffer. </p>
|
||
<p>Decompresses data from the source buffer into the destination buffer using LZMA.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">dst_buffer</td><td>Pointer to the destination buffer. </td></tr>
|
||
<tr><td class="paramname">dst_size</td><td>Pointer to the size of the destination buffer; updated with the actual size. </td></tr>
|
||
<tr><td class="paramname">src_buffer</td><td>Pointer to the source (compressed) buffer. </td></tr>
|
||
<tr><td class="paramname">src_len</td><td>Pointer to the size of the source buffer; updated with the actual size read. </td></tr>
|
||
<tr><td class="paramname">props</td><td>Pointer to the LZMA properties. </td></tr>
|
||
<tr><td class="paramname">props_size</td><td>Size of the LZMA properties. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>0 on success, or an error code on failure. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="lzma_8c_source.html#l00039">39</a> of file <a class="el" href="lzma_8c_source.html">lzma.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, and <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="read_8c_source.html#l00250">aaruf_read_sector()</a>, <a class="el" href="ddt__v2_8c_source.html#l00724">decode_ddt_multi_level_v2()</a>, <a class="el" href="data_8c_source.html#l00071">process_data_block()</a>, <a class="el" href="ddt__v1_8c_source.html#l00085">process_ddt_v1()</a>, and <a class="el" href="ddt__v2_8c_source.html#l00096">process_ddt_v2()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a0e69fad529047d6fe9440b1fc66c3f85" name="a0e69fad529047d6fe9440b1fc66c3f85"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a0e69fad529047d6fe9440b1fc66c3f85">◆ </a></span>aaruf_lzma_encode_buffer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_lzma_encode_buffer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>dst_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>dst_size</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>src_buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const size_t</td> <td class="paramname"><span class="paramname"><em>src_len</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>out_props</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">size_t *</td> <td class="paramname"><span class="paramname"><em>out_props_size</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>level</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>dict_size</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>lc</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>lp</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>pb</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>fb</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>num_threads</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Encodes a buffer using LZMA compression. </p>
|
||
<p>Compresses data from the source buffer into the destination buffer using LZMA.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">dst_buffer</td><td>Pointer to the destination buffer. </td></tr>
|
||
<tr><td class="paramname">dst_size</td><td>Pointer to the size of the destination buffer; updated with the actual size. </td></tr>
|
||
<tr><td class="paramname">src_buffer</td><td>Pointer to the source (uncompressed) buffer. </td></tr>
|
||
<tr><td class="paramname">src_len</td><td>Size of the source buffer. </td></tr>
|
||
<tr><td class="paramname">out_props</td><td>Pointer to the output LZMA properties. </td></tr>
|
||
<tr><td class="paramname">out_props_size</td><td>Pointer to the size of the output LZMA properties. </td></tr>
|
||
<tr><td class="paramname">level</td><td>Compression level. </td></tr>
|
||
<tr><td class="paramname">dict_size</td><td>Dictionary size. </td></tr>
|
||
<tr><td class="paramname">lc</td><td>LZMA literal context bits. </td></tr>
|
||
<tr><td class="paramname">lp</td><td>LZMA literal position bits. </td></tr>
|
||
<tr><td class="paramname">pb</td><td>LZMA position bits. </td></tr>
|
||
<tr><td class="paramname">fb</td><td>Number of fast bytes. </td></tr>
|
||
<tr><td class="paramname">num_threads</td><td>Number of threads to use. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>0 on success, or an error code on failure. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="lzma_8c_source.html#l00065">65</a> of file <a class="el" href="lzma_8c_source.html">lzma.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, and <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="ddt__v2_8c_source.html#l01092">set_ddt_multi_level_v2()</a>, <a class="el" href="close_8c_source.html#l00077">write_cached_secondary_ddt()</a>, <a class="el" href="close_8c_source.html#l01808">write_dvd_long_sector_blocks()</a>, <a class="el" href="close_8c_source.html#l02245">write_dvd_title_key_decrypted_block()</a>, <a class="el" href="close_8c_source.html#l02409">write_media_tags()</a>, <a class="el" href="close_8c_source.html#l00850">write_mode2_subheaders_block()</a>, <a class="el" href="close_8c_source.html#l00966">write_sector_prefix()</a>, <a class="el" href="close_8c_source.html#l01206">write_sector_prefix_ddt()</a>, <a class="el" href="close_8c_source.html#l01508">write_sector_subchannel()</a>, <a class="el" href="close_8c_source.html#l01088">write_sector_suffix()</a>, <a class="el" href="close_8c_source.html#l01350">write_sector_suffix_ddt()</a>, and <a class="el" href="close_8c_source.html#l00369">write_single_level_ddt()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="abe1156eceb456b48e92389d9f2a20601" name="abe1156eceb456b48e92389d9f2a20601"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#abe1156eceb456b48e92389d9f2a20601">◆ </a></span>aaruf_md5_buffer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_md5_buffer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>size</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned char *</td> <td class="paramname"><span class="paramname"><em>result</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="md5_8c_source.html#l00508">508</a> of file <a class="el" href="md5_8c_source.html">md5.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="md5_8c_source.html#l00475">aaruf_md5_final()</a>, <a class="el" href="md5_8c_source.html#l00425">aaruf_md5_init()</a>, and <a class="el" href="md5_8c_source.html#l00436">aaruf_md5_update()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a6b98055d07ba51f0daef5b03ce2fe725" name="a6b98055d07ba51f0daef5b03ce2fe725"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a6b98055d07ba51f0daef5b03ce2fe725">◆ </a></span>aaruf_md5_final()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_md5_final </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structmd5__ctx.html">md5_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned char *</td> <td class="paramname"><span class="paramname"><em>result</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="md5_8c_source.html#l00475">475</a> of file <a class="el" href="md5_8c_source.html">md5.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="md5_8h_source.html#l00034">md5_ctx::a</a>, <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="md5_8h_source.html#l00034">md5_ctx::b</a>, <a class="el" href="md5_8c_source.html#l00268">body()</a>, <a class="el" href="md5_8h_source.html#l00035">md5_ctx::buffer</a>, <a class="el" href="md5_8h_source.html#l00034">md5_ctx::c</a>, <a class="el" href="md5_8h_source.html#l00034">md5_ctx::d</a>, <a class="el" href="md5_8h_source.html#l00033">md5_ctx::hi</a>, <a class="el" href="md5_8h_source.html#l00033">md5_ctx::lo</a>, and <a class="el" href="md5_8c_source.html#l00469">OUT</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="md5_8c_source.html#l00508">aaruf_md5_buffer()</a>, and <a class="el" href="close_8c_source.html#l00654">write_checksum_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a1e614476485ba9f46e3ac79858210f63" name="a1e614476485ba9f46e3ac79858210f63"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a1e614476485ba9f46e3ac79858210f63">◆ </a></span>aaruf_md5_init()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_md5_init </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structmd5__ctx.html">md5_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="md5_8c_source.html#l00425">425</a> of file <a class="el" href="md5_8c_source.html">md5.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="md5_8h_source.html#l00034">md5_ctx::a</a>, <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="md5_8h_source.html#l00034">md5_ctx::b</a>, <a class="el" href="md5_8h_source.html#l00034">md5_ctx::c</a>, <a class="el" href="md5_8h_source.html#l00034">md5_ctx::d</a>, <a class="el" href="md5_8h_source.html#l00033">md5_ctx::hi</a>, and <a class="el" href="md5_8h_source.html#l00033">md5_ctx::lo</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>, and <a class="el" href="md5_8c_source.html#l00508">aaruf_md5_buffer()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a6e19e853bea5db901de83fa2fa29055c" name="a6e19e853bea5db901de83fa2fa29055c"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a6e19e853bea5db901de83fa2fa29055c">◆ </a></span>aaruf_md5_update()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_md5_update </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structmd5__ctx.html">md5_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>size</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="md5_8c_source.html#l00436">436</a> of file <a class="el" href="md5_8c_source.html">md5.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="md5_8c_source.html#l00049">AARU_RESTRICT</a>, <a class="el" href="md5_8c_source.html#l00268">body()</a>, <a class="el" href="md5_8h_source.html#l00035">md5_ctx::buffer</a>, <a class="el" href="md5_8h_source.html#l00033">md5_ctx::hi</a>, <a class="el" href="md5_8c_source.html#l00057">LIKELY</a>, <a class="el" href="md5_8h_source.html#l00033">md5_ctx::lo</a>, and <a class="el" href="md5_8c_source.html#l00058">UNLIKELY</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="md5_8c_source.html#l00508">aaruf_md5_buffer()</a>, <a class="el" href="write_8c_source.html#l00098">aaruf_write_sector()</a>, and <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="afc4932cdc795ffb2ef3a33d5b8c57656" name="afc4932cdc795ffb2ef3a33d5b8c57656"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#afc4932cdc795ffb2ef3a33d5b8c57656">◆ </a></span>aaruf_open()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void * aaruf_open </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>filepath</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Opens an existing AaruFormat image file. </p>
|
||
<p>Opens the specified image file and returns a pointer to the initialized aaruformat context. This function performs comprehensive validation of the image file format, reads and processes all index entries, initializes data structures for reading operations, and sets up caches for optimal performance. It supports multiple AaruFormat versions and handles various block types including data blocks, deduplication tables, metadata, and checksums.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">filepath</td><td>Path to the image file to open.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">aaruformatContext*</td><td>Successfully opened and initialized context. The returned pointer contains:<ul>
|
||
<li>Validated AaruFormat headers and metadata</li>
|
||
<li>Processed index entries with all discoverable blocks</li>
|
||
<li>Loaded deduplication tables (DDT) for efficient sector access</li>
|
||
<li>Initialized block and header caches for performance</li>
|
||
<li>Open file stream ready for reading operations</li>
|
||
<li>Populated image information and geometry data</li>
|
||
<li>ECC context initialized for error correction support</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">NULL</td><td>Opening failed. The specific error can be determined by checking errno, which will be set to:<ul>
|
||
<li>AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) when memory allocation fails for:<ul>
|
||
<li>Context allocation</li>
|
||
<li>Readable sector tags bitmap allocation</li>
|
||
<li>Application version string allocation</li>
|
||
<li>Image version string allocation</li>
|
||
</ul>
|
||
</li>
|
||
<li>AARUF_ERROR_FILE_TOO_SMALL (-2) when file reading fails:<ul>
|
||
<li>Cannot read the AaruFormat header (file too small or corrupted)</li>
|
||
<li>Cannot read the extended header for version 2+ formats</li>
|
||
</ul>
|
||
</li>
|
||
<li>AARUF_ERROR_NOT_AARUFORMAT (-1) when format validation fails:<ul>
|
||
<li>File identifier doesn't match DIC_MAGIC or AARU_MAGIC</li>
|
||
<li>File is not a valid AaruFormat image</li>
|
||
</ul>
|
||
</li>
|
||
<li>AARUF_ERROR_INCOMPATIBLE_VERSION (-3) when:<ul>
|
||
<li>Image major version exceeds the maximum supported version</li>
|
||
<li>Future format versions that cannot be read by this library</li>
|
||
</ul>
|
||
</li>
|
||
<li>AARUF_ERROR_CANNOT_READ_INDEX (-4) when index processing fails:<ul>
|
||
<li>Cannot seek to the index offset specified in the header</li>
|
||
<li>Cannot read the index signature</li>
|
||
<li>Index signature is not a recognized index block type</li>
|
||
<li>Index processing functions return NULL (corrupted index)</li>
|
||
</ul>
|
||
</li>
|
||
<li>Other error codes may be propagated from block processing functions:<ul>
|
||
<li>Data block processing errors</li>
|
||
<li>DDT processing errors</li>
|
||
<li>Metadata processing errors</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Format Support:<ul>
|
||
<li>Supports AaruFormat versions 1.x and 2.x</li>
|
||
<li>Automatically detects and handles different index formats (v1, v2, v3)</li>
|
||
<li>Backwards compatible with older DIC format identifiers</li>
|
||
<li>Handles both small and large deduplication tables</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Block Processing:<ul>
|
||
<li>Processes all indexed blocks including data, DDT, geometry, metadata, tracks, CICM, dump hardware, and checksums</li>
|
||
<li>Non-critical block processing errors are logged but don't prevent opening</li>
|
||
<li>Critical errors (DDT processing failures) cause opening to fail</li>
|
||
<li>Unknown block types are logged but ignored</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Memory Management:<ul>
|
||
<li>Allocates memory for various context structures and caches</li>
|
||
<li>On failure, all previously allocated memory is properly cleaned up</li>
|
||
<li>The returned context must be freed using <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a></li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Performance Optimization:<ul>
|
||
<li>Initializes block and header caches based on sector size and available memory</li>
|
||
<li>Cache sizes are calculated to optimize memory usage and access patterns</li>
|
||
<li>ECC context is pre-initialized for Compact Disc support</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The function requires a valid user data deduplication table to be present. Images without a DDT will fail to open even if otherwise valid.</dd>
|
||
<dd>
|
||
File access is performed in binary read mode. The file must be accessible and not locked by other processes.</dd>
|
||
<dd>
|
||
Some memory allocations (version strings) are optional and failure doesn't prevent opening, but may affect functionality that depends on version information. </dd></dl>
|
||
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
|
||
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
|
||
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="open_8c_source.html#l00125">125</a> of file <a class="el" href="open_8c_source.html">open.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="header_8h_source.html#l00059">AARU_HEADER_APP_NAME_LEN</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="close_8c_source.html#l03995">aaruf_close()</a>, <a class="el" href="ecc__cd_8c_source.html#l00035">aaruf_ecc_cd_init()</a>, <a class="el" href="errors_8h_source.html#l00043">AARUF_ERROR_CANNOT_READ_INDEX</a>, <a class="el" href="errors_8h_source.html#l00041">AARUF_ERROR_FILE_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00042">AARUF_ERROR_INCOMPATIBLE_VERSION</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="helpers_8c_source.html#l00339">aaruf_get_xml_mediatype()</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="consts_8h_source.html#l00068">AARUF_VERSION</a>, <a class="el" href="consts_8h_source.html#l00075">AARUF_VERSION_V2</a>, <a class="el" href="enums_8h_source.html#l00159">AaruMetadataJsonBlock</a>, <a class="el" href="aaru_8h_source.html#l00877">ImageInfo::Application</a>, <a class="el" href="header_8h_source.html#l00109">AaruHeaderV2::application</a>, <a class="el" href="header_8h_source.html#l00112">AaruHeaderV2::applicationMajorVersion</a>, <a class="el" href="header_8h_source.html#l00113">AaruHeaderV2::applicationMinorVersion</a>, <a class="el" href="aaru_8h_source.html#l00878">ImageInfo::ApplicationVersion</a>, <a class="el" href="context_8h_source.html#l00257">aaruformat_context::block_cache</a>, <a class="el" href="context_8h_source.html#l00256">aaruformat_context::block_header_cache</a>, <a class="el" href="enums_8h_source.html#l00219">BlockMedia</a>, <a class="el" href="index_8h_source.html#l00110">IndexEntry::blockType</a>, <a class="el" href="lru_8h_source.html#l00048">CacheHeader::cache</a>, <a class="el" href="enums_8h_source.html#l00152">ChecksumBlock</a>, <a class="el" href="enums_8h_source.html#l00151">CicmBlock</a>, <a class="el" href="open_8c_source.html#l00031">cleanup_open_failure()</a>, <a class="el" href="aaru_8h_source.html#l00879">ImageInfo::CreationTime</a>, <a class="el" href="header_8h_source.html#l00116">AaruHeaderV2::creationTime</a>, <a class="el" href="context_8h_source.html#l00234">aaruformat_context::cylinders</a>, <a class="el" href="enums_8h_source.html#l00141">DataBlock</a>, <a class="el" href="index_8h_source.html#l00111">IndexEntry::dataType</a>, <a class="el" href="enums_8h_source.html#l00142">DeDuplicationTable</a>, <a class="el" href="enums_8h_source.html#l00143">DeDuplicationTable2</a>, <a class="el" href="consts_8h_source.html#l00061">DIC_MAGIC</a>, <a class="el" href="enums_8h_source.html#l00156">DumpHardwareBlock</a>, <a class="el" href="context_8h_source.html#l00248">aaruformat_context::ecc_cd_context</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00229">aaruformat_context::geometry_block</a>, <a class="el" href="enums_8h_source.html#l00148">GeometryBlock</a>, <a class="el" href="context_8h_source.html#l00175">aaruformat_context::header</a>, <a class="el" href="context_8h_source.html#l00235">aaruformat_context::heads</a>, <a class="el" href="header_8h_source.html#l00108">AaruHeaderV2::identifier</a>, <a class="el" href="data_8h_source.html#l00092">GeometryBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="header_8h_source.html#l00110">AaruHeaderV2::imageMajorVersion</a>, <a class="el" href="header_8h_source.html#l00111">AaruHeaderV2::imageMinorVersion</a>, <a class="el" href="aaru_8h_source.html#l00873">ImageInfo::ImageSize</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="enums_8h_source.html#l00145">IndexBlock</a>, <a class="el" href="enums_8h_source.html#l00146">IndexBlock2</a>, <a class="el" href="enums_8h_source.html#l00147">IndexBlock3</a>, <a class="el" href="header_8h_source.html#l00115">AaruHeaderV2::indexOffset</a>, <a class="el" href="aaru_8h_source.html#l00880">ImageInfo::LastModificationTime</a>, <a class="el" href="header_8h_source.html#l00117">AaruHeaderV2::lastWrittenTime</a>, <a class="el" href="aaruformat_8h_source.html#l00022">LIBAARUFORMAT_MAJOR_VERSION</a>, <a class="el" href="aaruformat_8h_source.html#l00023">LIBAARUFORMAT_MINOR_VERSION</a>, <a class="el" href="context_8h_source.html#l00177">aaruformat_context::library_major_version</a>, <a class="el" href="context_8h_source.html#l00178">aaruformat_context::library_minor_version</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="consts_8h_source.html#l00079">MAX_CACHE_SIZE</a>, <a class="el" href="lru_8h_source.html#l00047">CacheHeader::max_items</a>, <a class="el" href="aaru_8h_source.html#l00916">MaxSectorTag</a>, <a class="el" href="aaru_8h_source.html#l00881">ImageInfo::MediaType</a>, <a class="el" href="header_8h_source.html#l00114">AaruHeaderV2::mediaType</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="index_8h_source.html#l00112">IndexEntry::offset</a>, <a class="el" href="blocks_2metadata_8c_source.html#l00470">process_aaru_metadata_json_block()</a>, <a class="el" href="checksum_8c_source.html#l00039">process_checksum_block()</a>, <a class="el" href="blocks_2metadata_8c_source.html#l00306">process_cicm_block()</a>, <a class="el" href="data_8c_source.html#l00071">process_data_block()</a>, <a class="el" href="ddt__v1_8c_source.html#l00085">process_ddt_v1()</a>, <a class="el" href="ddt__v2_8c_source.html#l00096">process_ddt_v2()</a>, <a class="el" href="blocks_2dump_8c_source.html#l00108">process_dumphw_block()</a>, <a class="el" href="blocks_2metadata_8c_source.html#l00246">process_geometry_block()</a>, <a class="el" href="index__v1_8c_source.html#l00079">process_index_v1()</a>, <a class="el" href="index__v2_8c_source.html#l00081">process_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00098">process_index_v3()</a>, <a class="el" href="blocks_2metadata_8c_source.html#l00035">process_metadata_block()</a>, <a class="el" href="tape_8c_source.html#l00126">process_tape_files_block()</a>, <a class="el" href="tape_8c_source.html#l00346">process_tape_partitions_block()</a>, <a class="el" href="optical_8c_source.html#l00111">process_tracks_block()</a>, <a class="el" href="context_8h_source.html#l00263">aaruformat_context::readableSectorTags</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="context_8h_source.html#l00236">aaruformat_context::sectors_per_track</a>, <a class="el" href="aaru_8h_source.html#l00875">ImageInfo::SectorSize</a>, <a class="el" href="context_8h_source.html#l00195">aaruformat_context::shift</a>, <a class="el" href="enums_8h_source.html#l00157">TapeFileBlock</a>, <a class="el" href="enums_8h_source.html#l00158">TapePartitionBlock</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="enums_8h_source.html#l00150">TracksBlock</a>, and <a class="el" href="aaru_8h_source.html#l00876">ImageInfo::Version</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a48f93ec154d0aed7cb713391a7717b46" name="a48f93ec154d0aed7cb713391a7717b46"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a48f93ec154d0aed7cb713391a7717b46">◆ </a></span>aaruf_read_media_tag()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_read_media_tag </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">const int32_t</td> <td class="paramname"><span class="paramname"><em>tag</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reads a media tag from the AaruFormat image. </p>
|
||
<p>Reads the specified media tag from the image and stores it in the provided buffer. Media tags contain metadata information about the storage medium such as disc information, lead-in/lead-out data, manufacturer-specific information, or other medium-specific metadata. This function uses a hash table lookup for efficient tag retrieval and supports buffer size querying when data pointer is NULL.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the buffer to store the tag data. Can be NULL to query tag length. </td></tr>
|
||
<tr><td class="paramname">tag</td><td>Tag identifier to read (specific to media type and format). </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to the length of the buffer on input; updated with actual tag length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully read the media tag. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The requested media tag exists in the image's media tag hash table</li>
|
||
<li>The provided buffer is large enough to contain the tag data</li>
|
||
<li>The tag data is successfully copied to the output buffer</li>
|
||
<li>The length parameter is updated with the actual tag data length</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_MEDIA_TAG_NOT_PRESENT</td><td>(-11) The requested media tag does not exist. This occurs when:<ul>
|
||
<li>The tag identifier is not found in the image's media tag hash table</li>
|
||
<li>The image was created without the requested metadata</li>
|
||
<li>The tag identifier is not supported for this media type</li>
|
||
<li>The length parameter is set to 0 when this error is returned</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer is insufficient. This occurs when:<ul>
|
||
<li>The data parameter is NULL (used for length querying)</li>
|
||
<li>The buffer length (*length) is smaller than the required tag data length</li>
|
||
<li>The length parameter is updated with the required size for retry</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Buffer Size Querying:<ul>
|
||
<li>Pass data as NULL to query the required buffer size without reading data</li>
|
||
<li>The length parameter will be updated with the required size</li>
|
||
<li>This allows proper buffer allocation before the actual read operation</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Media Tag Types:<ul>
|
||
<li>Tags are media-type specific (optical disc, floppy disk, hard disk, etc.)</li>
|
||
<li>Common tags include TOC data, lead-in/out, manufacturer data, defect lists</li>
|
||
<li>Tag availability depends on what was preserved during the imaging process</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Hash Table Lookup:<ul>
|
||
<li>Uses efficient O(1) hash table lookup for tag retrieval</li>
|
||
<li>Tag identifiers are integer values specific to the media format</li>
|
||
<li>Hash table is populated during image opening from indexed metadata blocks</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The function performs a direct memory copy operation. Ensure the output buffer has sufficient space to prevent buffer overflows.</dd>
|
||
<dd>
|
||
Media tag data is stored as-is from the original medium. No format conversion or validation is performed on the tag content. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="read_8c_source.html#l00085">85</a> of file <a class="el" href="read_8c_source.html">read.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00050">AARUF_ERROR_MEDIA_TAG_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00120">mediaTagEntry::data</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00122">mediaTagEntry::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00264">aaruformat_context::mediaTags</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a53397980f6b05e3ad0145f2941de16d2" name="a53397980f6b05e3ad0145f2941de16d2"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a53397980f6b05e3ad0145f2941de16d2">◆ </a></span>aaruf_read_sector()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_read_sector </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 uint64_t</td> <td class="paramname"><span class="paramname"><em>sector_address</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">bool</td> <td class="paramname"><span class="paramname"><em>negative</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">uint32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reads a sector from the AaruFormat image. </p>
|
||
<p>Reads user data from the specified sector address in the image. This function reads only the user data portion of the sector, without any additional metadata or ECC/EDC information. It handles block-based deduplication, compression (LZMA/FLAC), and caching for optimal performance. The function supports both DDT v1 and v2 formats for sector-to-block mapping.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
|
||
<tr><td class="paramname">sector_address</td><td>The logical sector address to read from. </td></tr>
|
||
<tr><td class="paramname">negative</td><td>Indicates if the sector address is negative. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to buffer where sector data will be stored. Can be NULL to query length. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to variable containing buffer size on input, actual data length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully read the sector data. This is returned when:<ul>
|
||
<li>The sector data is successfully retrieved from cache or decompressed from storage</li>
|
||
<li>Block header and data are successfully read and processed</li>
|
||
<li>Decompression (if needed) completes successfully</li>
|
||
<li>The sector data is copied to the output buffer</li>
|
||
<li>The length parameter is updated with the actual sector size</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_STATUS_SECTOR_NOT_DUMPED</td><td>(1) The sector was not dumped during imaging. This occurs when:<ul>
|
||
<li>The DDT entry indicates the sector status is SectorStatusNotDumped</li>
|
||
<li>The original imaging process skipped this sector due to read errors</li>
|
||
<li>The length parameter is set to the expected sector size for buffer allocation</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</td><td>(-8) The sector address exceeds image bounds. This occurs when:<ul>
|
||
<li>sector_address is greater than or equal to ctx->imageInfo.Sectors</li>
|
||
<li>Attempting to read beyond the logical extent of the imaged medium</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The provided buffer is insufficient. This occurs when:<ul>
|
||
<li>The data parameter is NULL (used for length querying)</li>
|
||
<li>The buffer length (*length) is smaller than the block's sector size</li>
|
||
<li>The length parameter is updated with the required size for retry</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. This occurs when:<ul>
|
||
<li>Cannot allocate memory for block header (if not cached)</li>
|
||
<li>Cannot allocate memory for uncompressed block data</li>
|
||
<li>Cannot allocate memory for compressed data buffer (LZMA/FLAC)</li>
|
||
<li>Cannot allocate memory for decompressed block buffer</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_HEADER</td><td>(-6) Block header reading failed. This occurs when:<ul>
|
||
<li>Cannot read the complete <a class="el" href="structBlockHeader.html" title="Header preceding the compressed data payload of a data block (BlockType::DataBlock).">BlockHeader</a> structure from the image stream</li>
|
||
<li>File I/O errors prevent reading header data at the calculated block offset</li>
|
||
<li>Image file corruption or truncation</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-7) Block data reading failed. This occurs when:<ul>
|
||
<li>Cannot read uncompressed block data from the image stream</li>
|
||
<li>Cannot read LZMA properties from compressed blocks</li>
|
||
<li>Cannot read compressed data from LZMA or FLAC blocks</li>
|
||
<li>File I/O errors during block data access</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK</td><td>(-17) Decompression failed. This occurs when:<ul>
|
||
<li>LZMA decoder returns a non-zero error code during decompression</li>
|
||
<li>FLAC decoder fails to decompress audio data properly</li>
|
||
<li>Decompressed data size doesn't match the expected block length</li>
|
||
<li>Compression algorithm encounters corrupted or invalid compressed data</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_UNSUPPORTED_COMPRESSION</td><td>(-13) Unsupported compression algorithm. This occurs when:<ul>
|
||
<li>The block header specifies a compression type not supported by this library</li>
|
||
<li>Future compression algorithms not implemented in this version</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">Other</td><td>error codes may be propagated from DDT decoding functions:<ul>
|
||
<li>From <a class="el" href="internal_8h.html#a26e5fd58cdfd39948f1b724fafffcdc2" title="Decodes a DDT v1 entry for a given sector address.">decode_ddt_entry_v1()</a>: AARUF_ERROR_NOT_AARUFORMAT (-1)</li>
|
||
<li>From <a class="el" href="internal_8h.html#a805d607b45bb8ad8a3e6b0bcfabe3265" title="Decodes a DDT v2 entry for a given sector address.">decode_ddt_entry_v2()</a>: AARUF_ERROR_NOT_AARUFORMAT (-1), AARUF_ERROR_CANNOT_READ_BLOCK (-7), AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17), AARUF_ERROR_INVALID_BLOCK_CRC (-18)</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>DDT Processing:<ul>
|
||
<li>Automatically selects DDT v1 or v2 decoding based on ctx->ddtVersion</li>
|
||
<li>DDT decoding provides sector offset within block and block file offset</li>
|
||
<li>Handles deduplication where multiple sectors may reference the same block</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Caching Mechanism:<ul>
|
||
<li>Block headers are cached for performance (ctx->blockHeaderCache)</li>
|
||
<li>Decompressed block data is cached to avoid repeated decompression (ctx->blockCache)</li>
|
||
<li>Cache hits eliminate file I/O and decompression overhead</li>
|
||
<li>Cache sizes are determined during context initialization</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Compression Support:<ul>
|
||
<li>None: Direct reading of uncompressed block data</li>
|
||
<li>LZMA: Industry-standard compression with properties header</li>
|
||
<li>FLAC: Audio-optimized compression for CD audio blocks</li>
|
||
<li>Each compression type has specific decompression requirements and error conditions</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Buffer Size Querying:<ul>
|
||
<li>Pass data as NULL to query the required buffer size without reading data</li>
|
||
<li>The length parameter will be updated with the block's sector size</li>
|
||
<li>Useful for dynamic buffer allocation before the actual read operation</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>This function reads only user data. For complete sector data including metadata and ECC/EDC information, use <a class="el" href="read_8c.html#ae30e05b38fead34408ffcdf92fcb503a" title="Reads a complete sector with all metadata from the AaruFormat image.">aaruf_read_sector_long()</a>.</dd>
|
||
<dd>
|
||
Memory allocated for caching is managed by the context. Do not free cached block data as it may be reused by subsequent operations.</dd>
|
||
<dd>
|
||
Sector addresses are zero-based. The maximum valid address is ctx->imageInfo.Sectors - 1. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="read_8c_source.html#l00250">250</a> of file <a class="el" href="read_8c_source.html">read.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00056">AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00045">AARUF_ERROR_CANNOT_READ_HEADER</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00044">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</a>, <a class="el" href="errors_8h_source.html#l00047">AARUF_ERROR_UNSUPPORTED_COMPRESSION</a>, <a class="el" href="flac_8c_source.html#l00048">aaruf_flac_decode_redbook_buffer()</a>, <a class="el" href="lzma_8c_source.html#l00039">aaruf_lzma_decode_buffer()</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="errors_8h_source.html#l00076">AARUF_STATUS_SECTOR_NOT_DUMPED</a>, <a class="el" href="lru_8c_source.html#l00102">add_to_cache_uint64()</a>, <a class="el" href="context_8h_source.html#l00257">aaruformat_context::block_cache</a>, <a class="el" href="context_8h_source.html#l00256">aaruformat_context::block_header_cache</a>, <a class="el" href="data_8h_source.html#l00076">BlockHeader::cmpLength</a>, <a class="el" href="data_8h_source.html#l00074">BlockHeader::compression</a>, <a class="el" href="context_8h_source.html#l00194">aaruformat_context::ddt_version</a>, <a class="el" href="ddt__v1_8c_source.html#l00405">decode_ddt_entry_v1()</a>, <a class="el" href="ddt__v2_8c_source.html#l00507">decode_ddt_entry_v2()</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="lru_8c_source.html#l00088">find_in_cache_uint64()</a>, <a class="el" href="enums_8h_source.html#l00035">Flac</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="data_8h_source.html#l00077">BlockHeader::length</a>, <a class="el" href="enums_8h_source.html#l00034">Lzma</a>, <a class="el" href="consts_8h_source.html#l00082">LZMA_PROPERTIES_LENGTH</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="enums_8h_source.html#l00033">None</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="aaru_8h_source.html#l00875">ImageInfo::SectorSize</a>, <a class="el" href="data_8h_source.html#l00075">BlockHeader::sectorSize</a>, <a class="el" href="enums_8h_source.html#l00230">SectorStatusNotDumped</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="read_8c_source.html#l00815">aaruf_read_sector_long()</a>, and <a class="el" href="read_8c_source.html#l00663">aaruf_read_track_sector()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a719a992be38ee90a5e302725c18a791b" name="a719a992be38ee90a5e302725c18a791b"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a719a992be38ee90a5e302725c18a791b">◆ </a></span>aaruf_read_sector_long()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_read_sector_long </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 uint64_t</td> <td class="paramname"><span class="paramname"><em>sector_address</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">bool</td> <td class="paramname"><span class="paramname"><em>negative</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">uint32_t *</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reads a complete sector with all metadata from the AaruFormat image. </p>
|
||
<p>Reads the complete sector data including user data, ECC/EDC, subchannel data, and other metadata depending on the media type. For optical discs, this returns a full 2352-byte sector with sync, header, user data, and ECC/EDC. For block media with tags, this includes both the user data and tag information. The function handles complex sector reconstruction including ECC correction and format-specific metadata assembly.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
|
||
<tr><td class="paramname">sector_address</td><td>The logical sector address to read from. </td></tr>
|
||
<tr><td class="paramname">negative</td><td>Indicates if the sector address is negative. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to buffer where complete sector data will be stored. Can be NULL to query length. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to variable containing buffer size on input, actual data length on output.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully read the complete sector with metadata. This is returned when:<ul>
|
||
<li>The sector data is successfully retrieved and reconstructed with all metadata</li>
|
||
<li>For optical discs: sync, header, user data, and ECC/EDC are assembled into 2352 bytes</li>
|
||
<li>For block media: user data and tags are combined according to media type</li>
|
||
<li>ECC reconstruction (if applicable) completes successfully</li>
|
||
<li>All required metadata (prefix/suffix, subheaders, etc.) is available and applied</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_STATUS_SECTOR_NOT_DUMPED</td><td>(1) The sector or metadata was not dumped. This can occur when:<ul>
|
||
<li>The underlying sector data was not dumped during imaging</li>
|
||
<li>CD prefix or suffix metadata indicates NotDumped status for the sector</li>
|
||
<li>ECC reconstruction cannot be performed due to missing correction data</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_MEDIA_TYPE</td><td>(-5) The media type doesn't support long sector reading. This occurs when:<ul>
|
||
<li>ctx->imageInfo.XmlMediaType is not OpticalDisc or BlockMedia</li>
|
||
<li>For BlockMedia: the specific media type is not supported (not Apple, Priam, etc.)</li>
|
||
<li>Media types that don't have extended sector formats</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-10) The buffer is insufficient for complete sector data. This occurs when:<ul>
|
||
<li>The data parameter is NULL (used for length querying)</li>
|
||
<li>For optical discs: buffer length is less than 2352 bytes</li>
|
||
<li>For block media: buffer length is less than (user data size + tag size)</li>
|
||
<li>The length parameter is updated with the required size for retry</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. This occurs when:<ul>
|
||
<li>Cannot allocate memory for bare user data during optical disc processing</li>
|
||
<li>Cannot allocate memory for user data during block media processing</li>
|
||
<li>Memory allocation fails in underlying <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> calls</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_TRACK_NOT_FOUND</td><td>(-12) Cannot locate the sector's track. This occurs when:<ul>
|
||
<li>For optical discs: the sector address doesn't fall within any data track boundaries</li>
|
||
<li>No track contains the specified sector address (address not in any track.start to track.end range)</li>
|
||
<li>The track list is empty or corrupted</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INVALID_TRACK_FORMAT</td><td>(-14) The track has an unsupported format. This occurs when:<ul>
|
||
<li>The track type is not recognized (not Audio, Data, CdMode1, CdMode2*, etc.)</li>
|
||
<li>Internal track format validation fails</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_REACHED_UNREACHABLE_CODE</td><td>(-15) Internal logic error. This occurs when:<ul>
|
||
<li>Required metadata structures (sectorPrefix, sectorSuffix, etc.) are unexpectedly NULL</li>
|
||
<li>Control flow reaches states that should be impossible with valid image data</li>
|
||
<li>Indicates potential image corruption or library bug</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">All</td><td>error codes from <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> may be propagated:<ul>
|
||
<li>AARUF_ERROR_SECTOR_OUT_OF_BOUNDS (-8) - Calculated sector address exceeds image bounds</li>
|
||
<li>AARUF_ERROR_CANNOT_READ_HEADER (-6) - Block header cannot be read</li>
|
||
<li>AARUF_ERROR_CANNOT_READ_BLOCK (-7) - Block data cannot be read</li>
|
||
<li>AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17) - Decompression fails</li>
|
||
<li>AARUF_ERROR_UNSUPPORTED_COMPRESSION (-13) - Compression algorithm not supported</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Optical Disc Sector Reconstruction:<ul>
|
||
<li>Creates full 2352-byte sectors from separate user data, sync, header, and ECC/EDC components</li>
|
||
<li>Supports different CD modes: Mode 1, Mode 2 Form 1, Mode 2 Form 2, Mode 2 Formless</li>
|
||
<li>Handles ECC correction using stored correction data or reconstructed ECC</li>
|
||
<li>Uses prefix/suffix DDTs to determine correction strategy for each sector</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Block Media Tag Assembly:<ul>
|
||
<li>Combines user data (typically 512 bytes) with media-specific tags</li>
|
||
<li>Tag sizes vary by media type: Apple (12-20 bytes), Priam (24 bytes)</li>
|
||
<li>Tags contain manufacturer-specific information like spare sector mapping</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
ECC Reconstruction Modes:<ul>
|
||
<li>Correct: Reconstructs ECC/EDC from user data (no stored correction data needed)</li>
|
||
<li>NotDumped: Indicates the metadata portion was not successfully read during imaging</li>
|
||
<li>Stored: Uses pre-computed correction data stored separately in the image</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Buffer Size Requirements:<ul>
|
||
<li>Optical discs: Always 2352 bytes (full raw sector)</li>
|
||
<li>Block media: User data size + tag size (varies by media type)</li>
|
||
<li>Pass data as NULL to query the exact required buffer size</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>For optical discs, this function requires track information to be available. Images without track data may not support long sector reading.</dd>
|
||
<dd>
|
||
The function performs complex sector reconstruction. Corrupted metadata or missing correction data may result in incorrect sector assembly.</dd>
|
||
<dd>
|
||
Not all AaruFormat images contain the metadata necessary for long sector reading. Some images may only support basic sector reading via <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a>. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="read_8c_source.html#l00815">815</a> of file <a class="el" href="read_8c_source.html">read.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="ecc__cd_8c_source.html#l00455">aaruf_ecc_cd_reconstruct()</a>, <a class="el" href="ecc__cd_8c_source.html#l00388">aaruf_ecc_cd_reconstruct_prefix()</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00051">AARUF_ERROR_INCORRECT_MEDIA_TYPE</a>, <a class="el" href="errors_8h_source.html#l00054">AARUF_ERROR_INVALID_TRACK_FORMAT</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#l00053">AARUF_ERROR_REACHED_UNREACHABLE_CODE</a>, <a class="el" href="errors_8h_source.html#l00044">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</a>, <a class="el" href="errors_8h_source.html#l00052">AARUF_ERROR_TRACK_NOT_FOUND</a>, <a class="el" href="read_8c_source.html#l00250">aaruf_read_sector()</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="errors_8h_source.html#l00076">AARUF_STATUS_SECTOR_NOT_DUMPED</a>, <a class="el" href="aaru_8h_source.html#l00249">AppleFileWare</a>, <a class="el" href="aaru_8h_source.html#l00698">AppleProfile</a>, <a class="el" href="aaru_8h_source.html#l00248">AppleSonyDS</a>, <a class="el" href="aaru_8h_source.html#l00247">AppleSonySS</a>, <a class="el" href="aaru_8h_source.html#l00699">AppleWidget</a>, <a class="el" href="enums_8h_source.html#l00195">Audio</a>, <a class="el" href="enums_8h_source.html#l00219">BlockMedia</a>, <a class="el" href="consts_8h_source.html#l00102">CD_DFIX_MASK</a>, <a class="el" href="consts_8h_source.html#l00100">CD_XFIX_MASK</a>, <a class="el" href="enums_8h_source.html#l00197">CdMode1</a>, <a class="el" href="enums_8h_source.html#l00199">CdMode2Form1</a>, <a class="el" href="enums_8h_source.html#l00200">CdMode2Form2</a>, <a class="el" href="enums_8h_source.html#l00198">CdMode2Formless</a>, <a class="el" href="enums_8h_source.html#l00183">Correct</a>, <a class="el" href="enums_8h_source.html#l00196">Data</a>, <a class="el" href="context_8h_source.html#l00243">aaruformat_context::data_tracks</a>, <a class="el" href="aaru_8h_source.html#l00146">DVDDownload</a>, <a class="el" href="aaru_8h_source.html#l00139">DVDPR</a>, <a class="el" href="aaru_8h_source.html#l00143">DVDPRDL</a>, <a class="el" href="aaru_8h_source.html#l00140">DVDPRW</a>, <a class="el" href="aaru_8h_source.html#l00141">DVDPRWDL</a>, <a class="el" href="aaru_8h_source.html#l00137">DVDR</a>, <a class="el" href="aaru_8h_source.html#l00144">DVDRAM</a>, <a class="el" href="aaru_8h_source.html#l00142">DVDRDL</a>, <a class="el" href="aaru_8h_source.html#l00136">DVDROM</a>, <a class="el" href="aaru_8h_source.html#l00138">DVDRW</a>, <a class="el" href="aaru_8h_source.html#l00145">DVDRWDL</a>, <a class="el" href="context_8h_source.html#l00248">aaruformat_context::ecc_cd_context</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="aaru_8h_source.html#l00881">ImageInfo::MediaType</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="context_8h_source.html#l00204">aaruformat_context::mode2_subheaders</a>, <a class="el" href="enums_8h_source.html#l00184">Mode2Form1Ok</a>, <a class="el" href="enums_8h_source.html#l00186">Mode2Form2NoCrc</a>, <a class="el" href="enums_8h_source.html#l00185">Mode2Form2Ok</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="enums_8h_source.html#l00182">NotDumped</a>, <a class="el" href="context_8h_source.html#l00245">aaruformat_context::number_of_data_tracks</a>, <a class="el" href="aaru_8h_source.html#l00238">Nuon</a>, <a class="el" href="enums_8h_source.html#l00218">OpticalDisc</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="aaru_8h_source.html#l00701">PriamDataTower</a>, <a class="el" href="aaru_8h_source.html#l00205">PS2DVD</a>, <a class="el" href="aaru_8h_source.html#l00206">PS3DVD</a>, <a class="el" href="aaru_8h_source.html#l00121">SACD</a>, <a class="el" href="context_8h_source.html#l00207">aaruformat_context::sector_cpr_mai</a>, <a class="el" href="context_8h_source.html#l00208">aaruformat_context::sector_edc</a>, <a class="el" href="context_8h_source.html#l00205">aaruformat_context::sector_id</a>, <a class="el" href="context_8h_source.html#l00206">aaruformat_context::sector_ied</a>, <a class="el" href="context_8h_source.html#l00199">aaruformat_context::sector_prefix</a>, <a class="el" href="context_8h_source.html#l00200">aaruformat_context::sector_prefix_corrected</a>, <a class="el" href="context_8h_source.html#l00183">aaruformat_context::sector_prefix_ddt</a>, <a class="el" href="context_8h_source.html#l00185">aaruformat_context::sector_prefix_ddt2</a>, <a class="el" href="context_8h_source.html#l00203">aaruformat_context::sector_subchannel</a>, <a class="el" href="context_8h_source.html#l00201">aaruformat_context::sector_suffix</a>, <a class="el" href="context_8h_source.html#l00202">aaruformat_context::sector_suffix_corrected</a>, <a class="el" href="context_8h_source.html#l00184">aaruformat_context::sector_suffix_ddt</a>, <a class="el" href="context_8h_source.html#l00186">aaruformat_context::sector_suffix_ddt2</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="enums_8h_source.html#l00233">SectorStatusMode1Correct</a>, <a class="el" href="enums_8h_source.html#l00234">SectorStatusMode2Form1Ok</a>, <a class="el" href="enums_8h_source.html#l00236">SectorStatusMode2Form2NoCrc</a>, <a class="el" href="enums_8h_source.html#l00235">SectorStatusMode2Form2Ok</a>, <a class="el" href="enums_8h_source.html#l00230">SectorStatusNotDumped</a>, <a class="el" href="optical_8h_source.html#l00075">TrackEntry::start</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="optical_8h_source.html#l00074">TrackEntry::type</a>, and <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ae5a85524a6e27339c02c4a5791e0db57" name="ae5a85524a6e27339c02c4a5791e0db57"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ae5a85524a6e27339c02c4a5791e0db57">◆ </a></span>aaruf_read_sector_tag()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_read_sector_tag </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>context</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>sector_address</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const bool</td> <td class="paramname"><span class="paramname"><em>negative</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>length</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>tag</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reads a specific sector tag from the AaruFormat image. </p>
|
||
<p>Reads sector-level metadata tags such as subchannel data, track information, DVD sector metadata, or Apple/Priam proprietary tags from the specified sector. Sector tags are ancillary data stored separately from the main user data and provide format-specific metadata like track flags, ISRC codes, DVD encryption information, or ECC/EDC data. This function validates tag type against media type and ensures the tag data is present in the image before returning it.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
|
||
<tr><td class="paramname">sector_address</td><td>The logical sector address to read the tag from. </td></tr>
|
||
<tr><td class="paramname">negative</td><td>Indicates if the sector address is negative (pre-track area). </td></tr>
|
||
<tr><td class="paramname">buffer</td><td>Pointer to buffer where tag data will be stored. Can be NULL to query tag length. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to variable containing buffer size on input, actual tag length on output. </td></tr>
|
||
<tr><td class="paramname">tag</td><td>Tag identifier specifying which sector tag to read (see <a class="el" href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> enum).</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">AARUF_STATUS_OK</td><td>(0) Successfully read the sector tag. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The requested tag type exists and is applicable to the media type</li>
|
||
<li>The tag data is present in the image for the specified sector</li>
|
||
<li>The provided buffer is large enough to contain the tag data</li>
|
||
<li>The tag data is successfully copied to the output buffer</li>
|
||
<li>The length parameter is updated with the actual tag data length</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</td><td>(-5) The sector address exceeds image bounds. This occurs when:<ul>
|
||
<li>negative is true and sector_address > ctx->userDataDdtHeader.negative - 1</li>
|
||
<li>negative is false and sector_address > ctx->imageInfo.Sectors + ctx->userDataDdtHeader.overflow - 1</li>
|
||
<li>Attempting to read beyond the logical extent of the imaged medium</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_MEDIA_TYPE</td><td>(-12) Tag type incompatible with media type. This occurs when:<ul>
|
||
<li>Optical disc tags (CdTrackFlags, CdTrackIsrc, CdSectorSubchannel, DvdSector*) requested from BlockMedia</li>
|
||
<li>Block media tags (AppleSonyTag, AppleProfileTag, PriamDataTowerTag) requested from OpticalDisc</li>
|
||
<li>Tag type is specific to a media format not present in the current image</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_DATA_SIZE</td><td>(-26) The provided buffer has incorrect size. This occurs when:<ul>
|
||
<li>The buffer parameter is NULL (used for length querying - NOT an error, updates length and returns this)</li>
|
||
<li>The buffer length (*length) doesn't match the required tag data length</li>
|
||
<li>The length parameter is updated with the required exact size for retry</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_SECTOR_TAG_NOT_PRESENT</td><td>(-16) The requested tag is not stored in the image. This occurs when:<ul>
|
||
<li>The tag data was not captured during the imaging process</li>
|
||
<li>The storage pointer for the tag is NULL (e.g., ctx->sector_subchannel is NULL)</li>
|
||
<li>The imaging hardware/software did not support reading this tag type</li>
|
||
<li>The tag is optional and was not available on the source medium</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_TRACK_NOT_FOUND</td><td>(-13) Track information not found for the sector. This occurs when:<ul>
|
||
<li>Requesting CdTrackFlags or CdTrackIsrc for a sector not within any track boundaries</li>
|
||
<li>The sector address doesn't fall within any track's start/end range in ctx->trackEntries[]</li>
|
||
<li>Track metadata was not properly initialized or is corrupted</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INVALID_TAG</td><td>(-27) The tag identifier is not recognized or supported. This occurs when:<ul>
|
||
<li>The tag parameter value doesn't match any known <a class="el" href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> enum value</li>
|
||
<li>Future/unsupported tag types not implemented in this library version</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Supported Tag Types and Sizes: Optical Disc Tags (OpticalDisc media only):<ul>
|
||
<li>CdTrackFlags (11): 1 byte - Track control flags (audio/data, copy permitted, pre-emphasis)</li>
|
||
<li>CdTrackIsrc (9): 12 bytes - International Standard Recording Code (no null terminator)</li>
|
||
<li>CdSectorSubchannel (71): 96 bytes - Raw P-W subchannel data</li>
|
||
<li>DvdSectorCprMai (81): 6 bytes - DVD Copyright Management Information (CPR_MAI)</li>
|
||
<li>DvdSectorInformation (16): 1 byte - DVD sector information byte from ID field</li>
|
||
<li>DvdSectorNumber (17): 3 bytes - DVD sector number from ID field</li>
|
||
<li>DvdSectorIed (84): 2 bytes - DVD ID Error Detection code</li>
|
||
<li>DvdSectorEdc (85): 4 bytes - DVD Error Detection Code</li>
|
||
<li>DvdDiscKeyDecrypted (80): 5 bytes - Decrypted DVD title key for the sector</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<p>Block Media Tags (BlockMedia only):</p><ul>
|
||
<li>AppleSonyTag (73): 12 bytes - Apple Sony format 12-byte sector tag</li>
|
||
<li>AppleProfileTag (72): 20 bytes - Apple Profile format 20-byte sector tag</li>
|
||
<li>PriamDataTowerTag (74): 24 bytes - Priam DataTower format 24-byte sector tag</li>
|
||
</ul>
|
||
<dl class="section note"><dt>Note</dt><dd>Sector Address Correction:<ul>
|
||
<li>The function automatically adjusts sector addresses based on the negative parameter</li>
|
||
<li>Negative sectors are adjusted: corrected = sector_address - ctx->userDataDdtHeader.negative</li>
|
||
<li>Positive sectors are adjusted: corrected = sector_address + ctx->userDataDdtHeader.negative</li>
|
||
<li>Corrected addresses are used for indexing into tag data arrays</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Track-Based Tags (CdTrackFlags, CdTrackIsrc):<ul>
|
||
<li>These tags are per-track, not per-sector</li>
|
||
<li>Function searches ctx->trackEntries[] for track containing the sector</li>
|
||
<li>All sectors within a track return the same track-level metadata</li>
|
||
<li>Returns AARUF_ERROR_TRACK_NOT_FOUND if sector is outside all tracks</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
DVD Sector Tags:<ul>
|
||
<li>DVD sector tags are extracted from the DVD ID field or associated metadata</li>
|
||
<li>DvdSectorInformation and DvdSectorNumber are derived from ctx->sector_id array</li>
|
||
<li>Multiple tags may share the same underlying storage (e.g., ID field breakdown)</li>
|
||
<li>Presence depends on the DVD reading capabilities during imaging</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Buffer Size Querying:<ul>
|
||
<li>Pass buffer as NULL to query the required buffer size without reading data</li>
|
||
<li>The length parameter will be updated with the exact required size</li>
|
||
<li>Returns AARUF_ERROR_INCORRECT_DATA_SIZE (not a fatal error in this context)</li>
|
||
<li>Allows proper buffer allocation before the actual read operation</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Tag Data Storage:<ul>
|
||
<li>Tag data is stored in dedicated context arrays (ctx->sector_subchannel, ctx->sector_cpr_mai, etc.)</li>
|
||
<li>Each tag type has a specific array with fixed-size entries per sector</li>
|
||
<li>NULL storage pointer indicates tag was not captured/available</li>
|
||
<li>Tag data is indexed using the corrected sector address</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The buffer must be exactly the required size for each tag type. Unlike <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a>, this function enforces strict size matching.</dd>
|
||
<dd>
|
||
Tag availability is hardware and media dependent. Always check for AARUF_ERROR_SECTOR_TAG_NOT_PRESENT and handle gracefully.</dd>
|
||
<dd>
|
||
Track-based tags (CdTrackFlags, CdTrackIsrc) return the same value for all sectors within a track. Do not assume per-sector uniqueness.</dd>
|
||
<dd>
|
||
Some tags contain binary data without string termination (e.g., ISRC). Do not treat tag buffers as null-terminated strings without validation. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="read_8c_source.html#l01463">1463</a> of file <a class="el" href="read_8c_source.html">read.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00051">AARUF_ERROR_INCORRECT_MEDIA_TYPE</a>, <a class="el" href="errors_8h_source.html#l00066">AARUF_ERROR_INVALID_TAG</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00044">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</a>, <a class="el" href="errors_8h_source.html#l00055">AARUF_ERROR_SECTOR_TAG_NOT_PRESENT</a>, <a class="el" href="errors_8h_source.html#l00052">AARUF_ERROR_TRACK_NOT_FOUND</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="enums_8h_source.html#l00117">AppleProfileTag</a>, <a class="el" href="enums_8h_source.html#l00118">AppleSonyTag</a>, <a class="el" href="enums_8h_source.html#l00219">BlockMedia</a>, <a class="el" href="enums_8h_source.html#l00116">CdSectorSubchannel</a>, <a class="el" href="aaru_8h_source.html#l00907">CdTrackFlags</a>, <a class="el" href="aaru_8h_source.html#l00905">CdTrackIsrc</a>, <a class="el" href="aaru_8h_source.html#l00908">DvdCmi</a>, <a class="el" href="enums_8h_source.html#l00130">DvdSectorEdc</a>, <a class="el" href="enums_8h_source.html#l00129">DvdSectorIed</a>, <a class="el" href="aaru_8h_source.html#l00912">DvdSectorInformation</a>, <a class="el" href="aaru_8h_source.html#l00913">DvdSectorNumber</a>, <a class="el" href="aaru_8h_source.html#l00911">DvdTitleKeyDecrypted</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="optical_8h_source.html#l00080">TrackEntry::flags</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="optical_8h_source.html#l00079">TrackEntry::isrc</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="enums_8h_source.html#l00218">OpticalDisc</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="enums_8h_source.html#l00119">PriamDataTowerTag</a>, <a class="el" href="context_8h_source.html#l00207">aaruformat_context::sector_cpr_mai</a>, <a class="el" href="context_8h_source.html#l00209">aaruformat_context::sector_decrypted_title_key</a>, <a class="el" href="context_8h_source.html#l00208">aaruformat_context::sector_edc</a>, <a class="el" href="context_8h_source.html#l00205">aaruformat_context::sector_id</a>, <a class="el" href="context_8h_source.html#l00206">aaruformat_context::sector_ied</a>, <a class="el" href="context_8h_source.html#l00203">aaruformat_context::sector_subchannel</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="optical_8h_source.html#l00075">TrackEntry::start</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="context_8h_source.html#l00242">aaruformat_context::track_entries</a>, <a class="el" href="context_8h_source.html#l00244">aaruformat_context::tracks_header</a>, and <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a33f54ac12ab867e9a9b2347c239e6c6e" name="a33f54ac12ab867e9a9b2347c239e6c6e"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a33f54ac12ab867e9a9b2347c239e6c6e">◆ </a></span>aaruf_read_track_sector()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_read_track_sector </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">const uint64_t</td> <td class="paramname"><span class="paramname"><em>sector_address</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t *</td> <td class="paramname"><span class="paramname"><em>length</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>track</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Reads a sector from a specific track in the AaruFormat image. </p>
|
||
<p>Reads user data from the specified sector address within a particular track. This function is specifically designed for optical disc images where sectors are organized by tracks. The sector address is relative to the start of the track. It validates the media type, locates the specified track by sequence number, calculates the absolute sector address, and delegates to <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a>.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to buffer where sector data will be stored. </td></tr>
|
||
<tr><td class="paramname">sector_address</td><td>The sector address relative to the track start. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Pointer to variable containing buffer size on input, actual data length on output. </td></tr>
|
||
<tr><td class="paramname">track</td><td>The track sequence number to read from.</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">AARUF_STATUS_OK</td><td>(0) Successfully read the sector data from the specified track. This is returned when:<ul>
|
||
<li>The context is valid and the media type is OpticalDisc</li>
|
||
<li>The specified track sequence number exists in the data tracks array</li>
|
||
<li>The underlying <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> call succeeds</li>
|
||
<li>The sector data is successfully retrieved and copied to the output buffer</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_MEDIA_TYPE</td><td>(-5) The media is not an optical disc. This occurs when:<ul>
|
||
<li>ctx->imageInfo.XmlMediaType is not OpticalDisc</li>
|
||
<li>This function is only applicable to CD, DVD, BD, and other optical disc formats</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_TRACK_NOT_FOUND</td><td>(-12) The specified track does not exist. This occurs when:<ul>
|
||
<li>No track in ctx->dataTracks[] has a sequence number matching the requested track</li>
|
||
<li>The track may not contain data or may not have been imaged</li>
|
||
<li>Only data tracks are searched; audio-only tracks are not included</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">All</td><td>other error codes from <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> may be returned:<ul>
|
||
<li>AARUF_STATUS_SECTOR_NOT_DUMPED (1) - Sector was not dumped during imaging</li>
|
||
<li>AARUF_ERROR_SECTOR_OUT_OF_BOUNDS (-8) - Calculated absolute sector address exceeds image bounds</li>
|
||
<li>AARUF_ERROR_BUFFER_TOO_SMALL (-10) - Data buffer is NULL or insufficient size</li>
|
||
<li>AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) - Memory allocation fails during sector reading</li>
|
||
<li>AARUF_ERROR_CANNOT_READ_HEADER (-6) - Block header cannot be read from image stream</li>
|
||
<li>AARUF_ERROR_CANNOT_READ_BLOCK (-7) - Block data cannot be read from image stream</li>
|
||
<li>AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17) - LZMA or FLAC decompression fails</li>
|
||
<li>AARUF_ERROR_UNSUPPORTED_COMPRESSION (-13) - Block uses unsupported compression</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Track-Relative Addressing:<ul>
|
||
<li>The sector_address parameter is relative to the start of the specified track</li>
|
||
<li>The function calculates the absolute sector address as: track.start + sector_address</li>
|
||
<li>Track boundaries are defined by track.start and track.end values</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Data Track Filtering:<ul>
|
||
<li>Only tracks in the ctx->dataTracks[] array are searched</li>
|
||
<li>Audio-only tracks without data content are not included in this search</li>
|
||
<li>The track sequence number is the logical track number from the disc TOC</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Function Delegation:<ul>
|
||
<li>This function is a wrapper that performs track validation and address calculation</li>
|
||
<li>The actual sector reading is performed by <a class="el" href="read_8c.html#adb06ba1a94336663acf8fc60b3589faa" title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a></li>
|
||
<li>All caching, decompression, and DDT processing occurs in the underlying function</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>This function is only applicable to optical disc media types. Attempting to use it with block media will result in AARUF_ERROR_INCORRECT_MEDIA_TYPE.</dd>
|
||
<dd>
|
||
The sector_address is relative to the track start, not the disc start. Ensure correct address calculation when working with multi-track discs.</dd>
|
||
<dd>
|
||
Track sequence numbers may not be contiguous. Always verify track existence before assuming a track number is valid. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="read_8c_source.html#l00663">663</a> of file <a class="el" href="read_8c_source.html">read.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00051">AARUF_ERROR_INCORRECT_MEDIA_TYPE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00052">AARUF_ERROR_TRACK_NOT_FOUND</a>, <a class="el" href="read_8c_source.html#l00250">aaruf_read_sector()</a>, <a class="el" href="context_8h_source.html#l00243">aaruformat_context::data_tracks</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="context_8h_source.html#l00245">aaruformat_context::number_of_data_tracks</a>, <a class="el" href="enums_8h_source.html#l00218">OpticalDisc</a>, <a class="el" href="optical_8h_source.html#l00073">TrackEntry::sequence</a>, <a class="el" href="optical_8h_source.html#l00075">TrackEntry::start</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">◆ </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> )</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="#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">AARUF_STATUS_OK</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->isWriting is true)</li>
|
||
<li>Memory allocation for the JSON data succeeded</li>
|
||
<li>The JSON data is copied to ctx->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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="#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="metadata_8c.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_8c.html#adbc2790344fae0327f55d751b79dd800" 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_8c_source.html#l02258">2258</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="enums_8h_source.html#l00159">AaruMetadataJsonBlock</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="metadata_8h_source.html#l00121">AaruMetadataJsonBlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00215">aaruformat_context::json_block</a>, <a class="el" href="context_8h_source.html#l00233">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#l00174">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="af7fcca1ab5ff0422ec81ec6e99001b38" name="af7fcca1ab5ff0422ec81ec6e99001b38"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#af7fcca1ab5ff0422ec81ec6e99001b38">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l00607">607</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00218">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a1da2dd0571762fa7c13bc956ec12dfab" name="a1da2dd0571762fa7c13bc956ec12dfab"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a1da2dd0571762fa7c13bc956ec12dfab">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l00493">493</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00216">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="add7cede9e5544ae12ae2b22eaf48e54c" name="add7cede9e5544ae12ae2b22eaf48e54c"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#add7cede9e5544ae12ae2b22eaf48e54c">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l01793">1793</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00228">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a3acb21067897f9cfc40e6288050a60c1" name="a3acb21067897f9cfc40e6288050a60c1"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a3acb21067897f9cfc40e6288050a60c1">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l01412">1412</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00224">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a1b4d35ee16a27a13f1bc16b0a17d65d1" name="a1b4d35ee16a27a13f1bc16b0a17d65d1"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a1b4d35ee16a27a13f1bc16b0a17d65d1">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l01534">1534</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00225">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="aef269305958754978beedf4c44618d98" name="aef269305958754978beedf4c44618d98"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#aef269305958754978beedf4c44618d98">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l01658">1658</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00226">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ad98012dc12a51d9eadbd79a25aab8299" name="ad98012dc12a51d9eadbd79a25aab8299"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ad98012dc12a51d9eadbd79a25aab8299">◆ </a></span>aaruf_set_dumphw()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_set_dumphw </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> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Sets the dump hardware block for the image during creation. </p>
|
||
<p>Embeds dump hardware information into the image being created. The dump hardware block documents the hardware and software environments used to create the image, recording one or more "dump
|
||
environments" – typically combinations of physical devices (drives, controllers, adapters) and the software stacks that performed the read operations. This metadata is essential for understanding the imaging context, validating acquisition integrity, reproducing imaging conditions, and supporting forensic or archival documentation requirements.</p>
|
||
<p>Each environment entry includes hardware identification (manufacturer, model, revision, firmware, serial number), software identification (name, version, operating system), and optional extent ranges that specify which logical sectors or units were contributed by that particular environment. This structure supports complex imaging scenarios where multiple devices or software configurations were used to create a composite image.</p>
|
||
<p>The function accepts a complete, pre-serialized DumpHardwareBlock in the on-disk binary format (as returned by <a class="el" href="dump_8c.html#a36af83897e131ba792c51ae8caec9984" title="Retrieves the dump hardware block containing acquisition environment information.">aaruf_get_dumphw()</a> or manually constructed). The block is validated for correct identifier, length consistency, and CRC64 integrity before being parsed and stored in the context. The function deserializes the binary block, extracts all entries with their variable-length UTF-8 strings and extent arrays, and creates null-terminated in-memory copies for internal use.</p>
|
||
<p><b>Validation performed:</b></p><ol type="1">
|
||
<li>Context validation (non-NULL, correct magic, write mode)</li>
|
||
<li>Data buffer validation (non-NULL, non-zero length)</li>
|
||
<li>Block identifier validation (must be DumpHardwareBlock)</li>
|
||
<li>Length consistency (buffer length must equal sizeof(DumpHardwareHeader) + header.length)</li>
|
||
<li>CRC64 integrity verification (calculated CRC64 must match header.crc64)</li>
|
||
</ol>
|
||
<p><b>Parsing process:</b></p><ol type="1">
|
||
<li>Read and validate the <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> from the buffer</li>
|
||
<li>Allocate array for all dump hardware entries</li>
|
||
<li>For each entry:<ul>
|
||
<li>Read the <a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> structure (36 bytes)</li>
|
||
<li>Allocate and copy each non-empty UTF-8 string with +1 byte for null terminator</li>
|
||
<li>Allocate and copy the <a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> array if extents > 0</li>
|
||
</ul>
|
||
</li>
|
||
<li>Free any previously set dump hardware data</li>
|
||
<li>Store the new parsed data in ctx->dumpHardwareEntriesWithData</li>
|
||
<li>Store the header in ctx->dumpHardwareHeader</li>
|
||
</ol>
|
||
<p><b>Memory management:</b> If any memory allocation fails during parsing, all previously allocated memory for the new data is freed via the free_copy_and_error label, and AARUF_ERROR_NOT_ENOUGH_MEMORY is returned. Any existing dump hardware data in the context is freed before storing new data, ensuring no memory leaks when replacing dump hardware information.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, write-enabled image context). </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the dump hardware block data in on-disk binary format. Must contain a complete DumpHardwareBlock starting with <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> followed by all entries, strings, and extent arrays. Must not be NULL. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Length of the dump hardware block data in bytes. Must equal sizeof(DumpHardwareHeader) + header.length for validation to succeed.</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">AARUF_STATUS_OK</td><td>(0) Successfully set dump hardware block. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The context is opened in write mode (ctx->isWriting is true)</li>
|
||
<li>The data buffer contains a valid DumpHardwareBlock</li>
|
||
<li>The block identifier is DumpHardwareBlock</li>
|
||
<li>The length is consistent (buffer length == header size + payload length)</li>
|
||
<li>The CRC64 checksum is valid</li>
|
||
<li>All memory allocations succeeded</li>
|
||
<li>All entries with strings and extents are parsed and stored</li>
|
||
<li>Any previous dump hardware data is freed</li>
|
||
<li>ctx->dumpHardwareEntriesWithData is populated with parsed entries</li>
|
||
<li>ctx->dumpHardwareHeader is updated with the new header</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-6) Invalid block identifier. This occurs when:<ul>
|
||
<li>The identifier field in the <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> doesn't equal DumpHardwareBlock</li>
|
||
<li>The data buffer doesn't contain a valid dump hardware block</li>
|
||
<li>The block type is incorrect or corrupted</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_DATA_SIZE</td><td>(-11) Invalid data or length. This occurs when:<ul>
|
||
<li>The data parameter is NULL</li>
|
||
<li>The length parameter is 0 (empty block)</li>
|
||
<li>The buffer length doesn't match sizeof(DumpHardwareHeader) + header.length</li>
|
||
<li>Length inconsistency indicates corrupted or incomplete block data</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INVALID_BLOCK_CRC</td><td>(-10) CRC64 checksum mismatch. This occurs when:<ul>
|
||
<li>The calculated CRC64 over the payload doesn't match header.crc64</li>
|
||
<li>Block data is corrupted or tampered with</li>
|
||
<li>Block was not properly constructed or serialized</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) Memory allocation failed. This occurs when:<ul>
|
||
<li>calloc() or malloc() failed to allocate memory for entries array</li>
|
||
<li>Failed to allocate memory for any string field (manufacturer, model, etc.)</li>
|
||
<li>Failed to allocate memory for extent arrays</li>
|
||
<li>System is out of memory or memory is severely fragmented</li>
|
||
<li>All partially allocated memory is freed before returning</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Dump Hardware Block Format:<ul>
|
||
<li>The data buffer must contain a complete serialized DumpHardwareBlock</li>
|
||
<li>Format: <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> + repeated entries with strings and extents</li>
|
||
<li>All strings are UTF-8 encoded and NOT null-terminated in the buffer</li>
|
||
<li>The function adds null terminators when copying strings to internal storage</li>
|
||
<li>String lengths are in bytes, not character counts</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Creating Block Data:<ul>
|
||
<li>Use <a class="el" href="dump_8c.html#a36af83897e131ba792c51ae8caec9984" title="Retrieves the dump hardware block containing acquisition environment information.">aaruf_get_dumphw()</a> to retrieve a block from an existing image</li>
|
||
<li>Manually construct by serializing <a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a>, entries, strings, and extents</li>
|
||
<li>Calculate CRC64-ECMA over the payload (everything after the header)</li>
|
||
<li>Ensure all length fields accurately reflect the data sizes</li>
|
||
<li>Ensure total buffer size equals sizeof(DumpHardwareHeader) + payload length</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Hardware Identification Fields:<ul>
|
||
<li>manufacturer: Device manufacturer (e.g., "Plextor", "Sony", "Samsung")</li>
|
||
<li>model: Device model number (e.g., "PX-716A", "DRU-820A")</li>
|
||
<li>revision: Hardware revision identifier</li>
|
||
<li>firmware: Firmware version (e.g., "1.11", "KY08")</li>
|
||
<li>serial: Device serial number for unique identification</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Software Identification Fields:<ul>
|
||
<li>softwareName: Dumping software name (e.g., "Aaru", "ddrescue", "IsoBuster")</li>
|
||
<li>softwareVersion: Software version (e.g., "5.3.0", "1.25")</li>
|
||
<li>softwareOperatingSystem: Host OS (e.g., "Linux 5.10.0", "Windows 10", "macOS 12.0")</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Extent Arrays:<ul>
|
||
<li>Each <a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> specifies a [start, end] logical sector range</li>
|
||
<li>Extents indicate which sectors this environment contributed</li>
|
||
<li>Empty extent arrays (extents == 0) mean the environment dumped entire medium</li>
|
||
<li>Extents are stored in the order provided in the input buffer</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Memory Ownership:<ul>
|
||
<li>The function creates internal copies of all data</li>
|
||
<li>The caller retains ownership of the input data buffer</li>
|
||
<li>The caller may free the input buffer immediately after this function returns</li>
|
||
<li>Internal copies are freed during <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> or when replaced by another call</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Replacing Existing Data:<ul>
|
||
<li>Calling this function multiple times replaces previous dump hardware data</li>
|
||
<li>All previous entries, strings, and extents are freed before storing new data</li>
|
||
<li>No memory leaks occur when updating dump hardware information</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The dump hardware block is only written to the image file during <a class="el" href="#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>
|
||
CRC64 validation protects against corrupted blocks, but construction errors in the input buffer (incorrect lengths, misaligned data) may cause parsing to fail or produce incorrect results even with a valid checksum.</dd>
|
||
<dd>
|
||
The function assumes the input buffer is properly formatted and packed according to the DumpHardwareBlock specification. Malformed input may cause crashes or memory corruption.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> for the block header structure definition. </dd>
|
||
<dd>
|
||
<a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> for the per-environment entry structure definition. </dd>
|
||
<dd>
|
||
<a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> for the extent range structure definition. </dd>
|
||
<dd>
|
||
<a class="el" href="dump_8c.html#a36af83897e131ba792c51ae8caec9984" title="Retrieves the dump hardware block containing acquisition environment information.">aaruf_get_dumphw()</a> for retrieving dump hardware from opened images. </dd>
|
||
<dd>
|
||
<a class="el" href="close_8c.html#a796034966c1e918152e652635431dc39" title="Serialize the dump hardware block containing acquisition environment information.">write_dumphw_block()</a> for the serialization process during image closing. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="dump_8c_source.html#l00531">531</a> of file <a class="el" href="dump_8c_source.html">dump.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00057">AARUF_ERROR_INVALID_BLOCK_CRC</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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="helpers_8c_source.html#l00451">compare_extents()</a>, <a class="el" href="dump_8c.html#a6b41f4a00a255e6704583614ef33571f">COPY_STRING_FIELD</a>, <a class="el" href="dump_8h_source.html#l00095">DumpHardwareHeader::crc64</a>, <a class="el" href="context_8h_source.html#l00212">aaruformat_context::dump_hardware_entries_with_data</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::dump_hardware_header</a>, <a class="el" href="enums_8h_source.html#l00156">DumpHardwareBlock</a>, <a class="el" href="dump_8h_source.html#l00093">DumpHardwareHeader::entries</a>, <a class="el" href="context_8h_source.html#l00315">DumpHardwareEntriesWithData::entry</a>, <a class="el" href="context_8h_source.html#l00316">DumpHardwareEntriesWithData::extents</a>, <a class="el" href="dump_8h_source.html#l00122">DumpHardwareEntry::extents</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="dump_8c_source.html#l00026">free_dump_hardware_entries()</a>, <a class="el" href="dump_8h_source.html#l00092">DumpHardwareHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="dump_8h_source.html#l00094">DumpHardwareHeader::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a21f4b3cf398b1a1c008c9a070ef9277b" name="a21f4b3cf398b1a1c008c9a070ef9277b"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a21f4b3cf398b1a1c008c9a070ef9277b">◆ </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> )</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">AARUF_STATUS_OK</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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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->geometryBlock: Written to the image file as a GeometryBlock during close</li>
|
||
<li>ctx->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="#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="#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="#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_8c_source.html#l00229">229</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00234">aaruformat_context::cylinders</a>, <a class="el" href="data_8h_source.html#l00093">GeometryBlockHeader::cylinders</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00229">aaruformat_context::geometry_block</a>, <a class="el" href="enums_8h_source.html#l00148">GeometryBlock</a>, <a class="el" href="context_8h_source.html#l00235">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00236">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="a4499e33d2fd3f8b514e510180972ec6f" name="a4499e33d2fd3f8b514e510180972ec6f"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a4499e33d2fd3f8b514e510180972ec6f">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l01176">1176</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00222">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a3d46262ff1f9d51d57d1e95648f4083b" name="a3d46262ff1f9d51d57d1e95648f4083b"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a3d46262ff1f9d51d57d1e95648f4083b">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l00832">832</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00219">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a8eed9fbf0341f48bac755524f4c99ef2" name="a8eed9fbf0341f48bac755524f4c99ef2"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a8eed9fbf0341f48bac755524f4c99ef2">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l00939">939</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00220">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a05157a196fb583605599414d7ab06f53" name="a05157a196fb583605599414d7ab06f53"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a05157a196fb583605599414d7ab06f53">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l01297">1297</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00223">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a00537ecc9cb55b4ce3c92d61a8cea094" name="a00537ecc9cb55b4ce3c92d61a8cea094"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a00537ecc9cb55b4ce3c92d61a8cea094">◆ </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> )</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">AARUF_STATUS_OK</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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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="#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 <= 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 > 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 <= 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="#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_8c_source.html#l00363">363</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">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#l00292">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#l00174">aaruformat_context::magic</a>, <a class="el" href="metadata_8h_source.html#l00072">MetadataBlockHeader::mediaSequence</a>, <a class="el" href="context_8h_source.html#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a2dff9d23775ba429c38efd251844092d" name="a2dff9d23775ba429c38efd251844092d"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a2dff9d23775ba429c38efd251844092d">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l01054">1054</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00221">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a37f50b38ceaee7db0b7731ee978b8241" name="a37f50b38ceaee7db0b7731ee978b8241"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a37f50b38ceaee7db0b7731ee978b8241">◆ </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> )</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">AARUF_STATUS_OK</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->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->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">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) 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="#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_8c_source.html#l00720">720</a> of file <a class="el" href="metadata_8c_source.html">metadata.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">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#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00217">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#l00230">aaruformat_context::metadata_block_header</a>, <a class="el" href="enums_8h_source.html#l00149">MetadataBlock</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a01c915ab49a4b47fd6768a2055208c48" name="a01c915ab49a4b47fd6768a2055208c48"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a01c915ab49a4b47fd6768a2055208c48">◆ </a></span>aaruf_set_tape_file()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_set_tape_file </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>partition</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>file</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>starting_block</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>ending_block</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Sets or updates the block range for a specific tape file in an Aaru tape image. </p>
|
||
<p>Creates or modifies a tape file entry in the context's hash table, defining the logical file's extent on the tape medium by its partition number, file number, and block range. This function is the write-mode counterpart to <a class="el" href="tape_8c.html#a6221f89b294ca55944944a04edb964e3" title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> and is used when creating or modifying tape images to establish the file structure metadata.</p>
|
||
<p><b>Tape File Registration:</b> When writing a tape image, this function should be called for each logical file to register its location. Each file is uniquely identified by:</p><ul>
|
||
<li><b>Partition number</b> (8-bit): The tape partition containing the file</li>
|
||
<li><b>File number</b> (32-bit): The sequential file number within that partition</li>
|
||
</ul>
|
||
<p>These values are combined into a 64-bit composite key: key = (partition << 32) | file_number</p>
|
||
<p>The file entry (including the block range) is then stored in the context's tapeFiles hash table and will be written to the image's TapeFileBlock during finalization.</p>
|
||
<p><b>Block Range Definition:</b> The block range [starting_block, ending_block] defines the file's extent:</p><ul>
|
||
<li>starting_block: The first block address where the file begins (inclusive)</li>
|
||
<li>ending_block: The final block address where the file ends (inclusive)</li>
|
||
<li>Block count: (ending_block - starting_block + 1)</li>
|
||
</ul>
|
||
<p>Block addresses must be absolute positions within the tape image's logical block space. The caller is responsible for ensuring:</p><ul>
|
||
<li>starting_block <= ending_block (no validation is performed)</li>
|
||
<li>Block ranges don't conflict with other files (no validation is performed)</li>
|
||
<li>All blocks in the range have been or will be written to the image</li>
|
||
</ul>
|
||
<p><b>Typical Usage Flow:</b></p><ol type="1">
|
||
<li>Open or create an Aaru tape image with write access</li>
|
||
<li>Write the file's data blocks to the image</li>
|
||
<li>Call <a class="el" href="tape_8c.html#a03d080a18e07adc52a654dc31b26eea0" title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> to register the file's block range</li>
|
||
<li>Repeat for all files on the tape</li>
|
||
<li>Close the image (TapeFileBlock will be written during finalization)</li>
|
||
</ol>
|
||
<p><b>Update/Replace Behavior:</b> If a file entry with the same partition/file combination already exists:</p><ul>
|
||
<li>The old entry is automatically freed</li>
|
||
<li>The new entry replaces it in the hash table</li>
|
||
<li>A TRACE message indicates the replacement</li>
|
||
</ul>
|
||
<p>This allows updating file metadata or correcting errors without manual deletion.</p>
|
||
<p><b>Error Handling:</b> The function performs validation in the following order:</p><ol type="1">
|
||
<li>Context pointer validation (NULL check)</li>
|
||
<li>Magic number verification (ensures valid aaruformat context)</li>
|
||
<li>Write mode verification (ensures image is opened for writing)</li>
|
||
<li>Memory allocation for the hash entry</li>
|
||
</ol>
|
||
<p>If any validation fails, an appropriate error code is returned and no modifications are made to the context's tape file table.</p>
|
||
<p><b>Thread Safety:</b> This function modifies the shared context's hash table and is NOT thread-safe. Concurrent calls to <a class="el" href="tape_8c.html#a03d080a18e07adc52a654dc31b26eea0" title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> or other functions that modify ctx->tapeFiles may result in data corruption or memory leaks. The caller must ensure exclusive access through external synchronization if needed.</p>
|
||
<p><b>Memory Management:</b></p><ul>
|
||
<li>Allocates a new hash table entry (<a class="el" href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a>) for each call</li>
|
||
<li>HASH_REPLACE automatically frees replaced entries</li>
|
||
<li>All hash entries are freed when the context is closed</li>
|
||
<li>On allocation failure, no entry is added and an error is returned</li>
|
||
</ul>
|
||
<p><b>Performance Characteristics:</b></p><ul>
|
||
<li>Hash table insertion/replacement: O(1) average case</li>
|
||
<li>No I/O operations performed (metadata written during image close)</li>
|
||
<li>Minimal stack usage</li>
|
||
<li>Suitable for bulk file registration operations</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been opened with write access (isWriting=true). The context's tapeFiles hash table will be updated with the new entry.</td></tr>
|
||
<tr><td class="paramname">partition</td><td>The partition number (0-255) where the file is located. For single-partition tapes, this is typically 0. Multi-partition tapes can have files in different partitions with potentially overlapping file numbers.</td></tr>
|
||
<tr><td class="paramname">file</td><td>The file number within the specified partition. File numbers are typically sequential (0, 1, 2, ...) but gaps are allowed. The same file number can exist in different partitions without conflict.</td></tr>
|
||
<tr><td class="paramname">starting_block</td><td>The first block address of the file (inclusive). This should be the absolute block number in the image where the file's first byte begins. Must be <= ending_block (not validated).</td></tr>
|
||
<tr><td class="paramname">ending_block</td><td>The last block address of the file (inclusive). This should be the absolute block number in the image where the file's last byte ends. Must be >= starting_block (not validated).</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully set tape file information. The hash table has been updated with the file entry. If an entry with the same partition/file combination existed, it has been replaced. The metadata will be written to the TapeFileBlock when the image is closed.</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
|
||
<li>The context pointer is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) No modifications are made to the context.</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-22) The context is not opened for writing. This is returned when ctx->isWriting is false, indicating the image was opened in read-only mode. Tape file metadata cannot be modified in read-only mode. No modifications are made to the context.</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. The system could not allocate memory for the hash table entry (<a class="el" href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a>). This is a critical error indicating low memory conditions. No modifications are made to the context.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
|
||
<dd>
|
||
The tape file metadata is not immediately written to disk. It remains in the context's hash table until the image is closed, at which point all entries are serialized and written to a TapeFileBlock.</dd>
|
||
<dd>
|
||
No validation is performed on the block range values. The caller is responsible for ensuring that starting_block <= ending_block and that the range is valid for the image being created.</dd>
|
||
<dd>
|
||
No validation is performed to detect overlapping file ranges. Multiple files can reference the same or overlapping block ranges, which may be intentional (e.g., for multi-track or multi-partition scenarios).</dd>
|
||
<dd>
|
||
If the same partition/file combination is set multiple times, only the last values are retained. This can be used to update file metadata but also means accidental duplicate calls will silently overwrite previous values.</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>This function is NOT thread-safe. Concurrent modifications to the tape file table may result in undefined behavior, memory corruption, or memory leaks.</dd>
|
||
<dd>
|
||
The caller must ensure the image is opened with write access before calling this function. Attempting to modify read-only images will fail with AARUF_READ_ONLY.</dd>
|
||
<dd>
|
||
Parameter validation is minimal. Invalid block ranges (starting_block > ending_block) are accepted and will be written to the image, potentially causing problems when reading the image later.</dd>
|
||
<dd>
|
||
If memory allocation fails (AARUF_ERROR_NOT_ENOUGH_MEMORY), the file entry is not added. The caller should handle this error appropriately, potentially by freeing memory and retrying or aborting the write operation.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="tape_8c.html#a6221f89b294ca55944944a04edb964e3" title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> for retrieving tape file information from images </dd>
|
||
<dd>
|
||
<a class="el" href="tape_8c.html#a829bbac3c17b60efd8f93188a8de8278" title="Processes a tape file metadata block from the image stream.">process_tape_files_block()</a> for tape file table initialization during read </dd>
|
||
<dd>
|
||
<a class="el" href="structTapeFileEntry.html" title="Describes a single logical file on a tape medium.">TapeFileEntry</a> for the structure defining file block ranges </dd>
|
||
<dd>
|
||
<a class="el" href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a> for the hash table entry structure </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="tape_8c_source.html#l00770">770</a> of file <a class="el" href="tape_8c_source.html">tape.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="tape_8h_source.html#l00135">TapeFileEntry::File</a>, <a class="el" href="context_8h_source.html#l00129">TapeFileHashEntry::fileEntry</a>, <a class="el" href="tape_8h_source.html#l00139">TapeFileEntry::FirstBlock</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00128">TapeFileHashEntry::key</a>, <a class="el" href="tape_8h_source.html#l00142">TapeFileEntry::LastBlock</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="tape_8h_source.html#l00137">TapeFileEntry::Partition</a>, <a class="el" href="context_8h_source.html#l00302">aaruformat_context::tape_files</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a9daeeb54c74dd2707d95ab47e8ab0a00" name="a9daeeb54c74dd2707d95ab47e8ab0a00"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a9daeeb54c74dd2707d95ab47e8ab0a00">◆ </a></span>aaruf_set_tape_partition()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_set_tape_partition </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>partition</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>starting_block</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>ending_block</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Sets or updates the block range for a specific tape partition in an Aaru tape image. </p>
|
||
<p>Creates or modifies a tape partition entry in the context's hash table, defining the physical partition's extent on the tape medium by its partition number and block range. This function is the write-mode counterpart to <a class="el" href="tape_8c.html#a91c40d91fdeb98193d6eeb95f16d8973" title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> and is used when creating or modifying tape images to establish the partition structure metadata.</p>
|
||
<p><b>Tape Partition Registration:</b> When writing a tape image, this function should be called for each physical partition to register its block range. Each partition is uniquely identified by its partition number (0-255), and most tapes have a single partition (partition 0), though formats like LTO, DLT, and AIT support multiple partitions.</p>
|
||
<p>The partition entry (including the block range) is stored in the context's tapePartitions hash table and will be written to the image's TapePartitionBlock during finalization.</p>
|
||
<p><b>Block Range Definition:</b> The block range [starting_block, ending_block] defines the partition's extent:</p><ul>
|
||
<li>starting_block: The first block address in the partition (often 0, but format-dependent)</li>
|
||
<li>ending_block: The final block address in the partition (inclusive)</li>
|
||
<li>Block count: (ending_block - starting_block + 1)</li>
|
||
</ul>
|
||
<p>Block addresses are local to each partition. The caller is responsible for ensuring:</p><ul>
|
||
<li>starting_block <= ending_block (no validation is performed)</li>
|
||
<li>Partition ranges don't overlap (no validation is performed)</li>
|
||
<li>All blocks in the range have been or will be written to the image</li>
|
||
<li>Files referencing this partition have block addresses within this range</li>
|
||
</ul>
|
||
<p><b>Typical Usage Flow:</b></p><ol type="1">
|
||
<li>Open or create an Aaru tape image with write access</li>
|
||
<li>Define partition layout by calling <a class="el" href="tape_8c.html#aa16d4457093df66246ce5622c3565a17" title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> for each partition</li>
|
||
<li>Write data blocks to the image within the defined partition ranges</li>
|
||
<li>Register files within partitions using <a class="el" href="tape_8c.html#a03d080a18e07adc52a654dc31b26eea0" title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a></li>
|
||
<li>Close the image (TapePartitionBlock will be written during finalization)</li>
|
||
</ol>
|
||
<p><b>Update/Replace Behavior:</b> If a partition entry with the same partition number already exists:</p><ul>
|
||
<li>The old entry is automatically freed</li>
|
||
<li>The new entry replaces it in the hash table</li>
|
||
<li>A TRACE message indicates the replacement</li>
|
||
</ul>
|
||
<p>This allows updating partition metadata or correcting errors without manual deletion.</p>
|
||
<p><b>Error Handling:</b> The function performs validation in the following order:</p><ol type="1">
|
||
<li>Context pointer validation (NULL check)</li>
|
||
<li>Magic number verification (ensures valid aaruformat context)</li>
|
||
<li>Write mode verification (ensures image is opened for writing)</li>
|
||
<li>Memory allocation for the hash entry</li>
|
||
</ol>
|
||
<p>If any validation fails, an appropriate error code is returned and no modifications are made to the context's tape partition table.</p>
|
||
<p><b>Thread Safety:</b> This function modifies the shared context's hash table and is NOT thread-safe. Concurrent calls to <a class="el" href="tape_8c.html#aa16d4457093df66246ce5622c3565a17" title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> or other functions that modify ctx->tapePartitions may result in data corruption or memory leaks. The caller must ensure exclusive access through external synchronization if needed.</p>
|
||
<p><b>Memory Management:</b></p><ul>
|
||
<li>Allocates a new hash table entry (<a class="el" href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a>) for each call</li>
|
||
<li>HASH_REPLACE automatically frees replaced entries</li>
|
||
<li>All hash entries are freed when the context is closed</li>
|
||
<li>On allocation failure, no entry is added and an error is returned</li>
|
||
</ul>
|
||
<p><b>Performance Characteristics:</b></p><ul>
|
||
<li>Hash table insertion/replacement: O(1) average case</li>
|
||
<li>No I/O operations performed (metadata written during image close)</li>
|
||
<li>Minimal stack usage</li>
|
||
<li>Suitable for bulk partition registration operations</li>
|
||
</ul>
|
||
<p><b>Partition Organization:</b> Proper partition metadata is essential for:</p><ul>
|
||
<li>Documenting the physical layout of multi-partition tapes</li>
|
||
<li>Validating file block ranges against partition boundaries</li>
|
||
<li>Preserving the original tape's partitioning scheme for archival purposes</li>
|
||
<li>Supporting tape formats that require specific partition structures</li>
|
||
<li>Enabling applications to understand and navigate complex tape layouts</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been opened with write access (isWriting=true). The context's tapePartitions hash table will be updated with the new entry.</td></tr>
|
||
<tr><td class="paramname">partition</td><td>The partition number (0-255) to set. For single-partition tapes, this is typically 0. Multi-partition tapes use sequential numbers (0, 1, 2, ...) though the numbering scheme is format-specific.</td></tr>
|
||
<tr><td class="paramname">starting_block</td><td>The first block address of the partition (inclusive). This defines where the partition begins in the tape's block address space. Often 0 for the first partition, but format-dependent. Must be <= ending_block (not validated).</td></tr>
|
||
<tr><td class="paramname">ending_block</td><td>The last block address of the partition (inclusive). This defines where the partition ends in the tape's block address space. Must be >= starting_block (not validated).</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully set tape partition information. The hash table has been updated with the partition entry. If an entry with the same partition number existed, it has been replaced. The metadata will be written to the TapePartitionBlock when the image is closed.</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
|
||
<li>The context pointer is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) No modifications are made to the context.</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-22) The context is not opened for writing. This is returned when ctx->isWriting is false, indicating the image was opened in read-only mode. Tape partition metadata cannot be modified in read-only mode. No modifications are made to the context.</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. The system could not allocate memory for the hash table entry (<a class="el" href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a>). This is a critical error indicating low memory conditions. No modifications are made to the context.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
|
||
<dd>
|
||
The tape partition metadata is not immediately written to disk. It remains in the context's hash table until the image is closed, at which point all entries are serialized and written to a TapePartitionBlock.</dd>
|
||
<dd>
|
||
No validation is performed on the block range values. The caller is responsible for ensuring that starting_block <= ending_block and that the range is valid for the image being created.</dd>
|
||
<dd>
|
||
No validation is performed to detect overlapping partition ranges. Partitions with overlapping block addresses may be accepted but will likely cause problems when reading the image or accessing files.</dd>
|
||
<dd>
|
||
If the same partition number is set multiple times, only the last values are retained. This can be used to update partition metadata but also means accidental duplicate calls will silently overwrite previous values.</dd>
|
||
<dd>
|
||
For single-partition tapes, it may be acceptable to omit the TapePartitionBlock entirely. Applications reading such images should assume a default partition 0 spanning the entire tape if no partition metadata is present.</dd>
|
||
<dd>
|
||
Block addresses are local to each partition. Files within a partition reference blocks relative to that partition's address space, not the global tape address space (though in practice, many formats use absolute addressing).</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>This function is NOT thread-safe. Concurrent modifications to the tape partition table may result in undefined behavior, memory corruption, or memory leaks.</dd>
|
||
<dd>
|
||
The caller must ensure the image is opened with write access before calling this function. Attempting to modify read-only images will fail with AARUF_READ_ONLY.</dd>
|
||
<dd>
|
||
Parameter validation is minimal. Invalid block ranges (starting_block > ending_block) are accepted and will be written to the image, potentially causing problems when reading the image later.</dd>
|
||
<dd>
|
||
If memory allocation fails (AARUF_ERROR_NOT_ENOUGH_MEMORY), the partition entry is not added. The caller should handle this error appropriately, potentially by freeing memory and retrying or aborting the write operation.</dd>
|
||
<dd>
|
||
Partition metadata should be consistent with file metadata. Files should only reference partitions that have been defined, and their block ranges should fall within the partition boundaries. No automatic validation is performed.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="tape_8c.html#a91c40d91fdeb98193d6eeb95f16d8973" title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> for retrieving tape partition information from images </dd>
|
||
<dd>
|
||
<a class="el" href="tape_8c.html#aa76718b0402b1a28be3d563d5e62028e" title="Processes a tape partition metadata block from the image stream.">process_tape_partitions_block()</a> for partition table initialization during read </dd>
|
||
<dd>
|
||
<a class="el" href="structTapePartitionEntry.html" title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> for the structure defining partition block ranges </dd>
|
||
<dd>
|
||
<a class="el" href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a> for the hash table entry structure </dd>
|
||
<dd>
|
||
<a class="el" href="tape_8c.html#a03d080a18e07adc52a654dc31b26eea0" title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> for setting file metadata within partitions </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="tape_8c_source.html#l01196">1196</a> of file <a class="el" href="tape_8c_source.html">tape.c</a>.</p>
|
||
|
||
<p class="reference">References <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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="tape_8h_source.html#l00323">TapePartitionEntry::FirstBlock</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00135">TapePartitionHashEntry::key</a>, <a class="el" href="tape_8h_source.html#l00325">TapePartitionEntry::LastBlock</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="tape_8h_source.html#l00321">TapePartitionEntry::Number</a>, <a class="el" href="context_8h_source.html#l00136">TapePartitionHashEntry::partitionEntry</a>, <a class="el" href="context_8h_source.html#l00303">aaruformat_context::tape_partitions</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a518d8d68debf1b9a24af3eb6bc2f9e49" name="a518d8d68debf1b9a24af3eb6bc2f9e49"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a518d8d68debf1b9a24af3eb6bc2f9e49">◆ </a></span>aaruf_set_tracks()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_set_tracks </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"><a class="el" href="structTrackEntry.html">TrackEntry</a> *</td> <td class="paramname"><span class="paramname"><em>tracks</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const int</td> <td class="paramname"><span class="paramname"><em>count</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Replace (or clear) the in-memory track table for an AaruFormat image context. </p>
|
||
<p>Copies an array of caller-provided <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures into the internal context, replacing any previously stored track metadata. A CRC64 is recomputed over the new table and stored in the associated <a class="el" href="structTracksHeader.html" title="Header for an optical tracks block listing track entries.">TracksHeader</a>. Passing a count of 0 clears existing track information.</p>
|
||
<p>Typical usage:</p><ul>
|
||
<li>Prepare an array of <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures describing each track (filled by the caller).</li>
|
||
<li>Call <a class="el" href="optical_8c.html#a518d8d68debf1b9a24af3eb6bc2f9e49" title="Replace (or clear) the in-memory track table for an AaruFormat image context.">aaruf_set_tracks()</a> with the array and the track count to load them into the context.</li>
|
||
<li>Subsequently the table can be retrieved with <a class="el" href="optical_8c.html#a2ce65757ca5209f17d467c51ba7d445d" title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a>.</li>
|
||
</ul>
|
||
<p>Memory ownership:</p><ul>
|
||
<li>The function allocates (or frees when clearing) internal storage sized to (count * sizeof(TrackEntry)).</li>
|
||
<li>The caller retains ownership of the input array (if any) and may free or reuse it after the call.</li>
|
||
</ul>
|
||
<p>Validation performed:</p><ul>
|
||
<li><code class="param">context</code> must be non-NULL and reference aaruformatContext with magic == AARU_MAGIC.</li>
|
||
<li><code class="param">tracks</code> must be non-NULL when <code class="param">count</code> > 0.</li>
|
||
<li><code class="param">count</code> must be >= 0. (Negative values produce AARUF_ERROR_INVALID_TRACK_FORMAT.)</li>
|
||
<li>(Implementation detail) count is truncated to uint16_t for header storage; values > UINT16_MAX will silently wrap. Callers should ensure count <= 65535. This behavior may change in a future version.</li>
|
||
</ul>
|
||
<p>Concurrency & thread-safety:</p><ul>
|
||
<li>Not thread-safe. Mutates shared context state. External synchronization is required if multiple threads access the same context.</li>
|
||
</ul>
|
||
<p>Side effects:</p><ul>
|
||
<li>Frees any existing internal track table before allocating the new one.</li>
|
||
<li>Updates ctx->tracksHeader.identifier, entries, crc64.</li>
|
||
<li>When clearing (count == 0) sets header to zero and frees internal table.</li>
|
||
</ul>
|
||
<p>Error handling & atomicity:</p><ul>
|
||
<li>On allocation failure the previous track table is already freed (non-atomic replace) and the header is zeroed (no partial new state left). Caller must repopulate.</li>
|
||
<li>No partial copies: either all tracks are stored or none.</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Opaque pointer that MUST point to a valid aaruformatContext returned by an open/create call. </td></tr>
|
||
<tr><td class="paramname">tracks</td><td>Pointer to an array of <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures to copy. Must not be NULL if count > 0. Ignored (may be NULL) when count == 0. </td></tr>
|
||
<tr><td class="paramname">count</td><td>Number of <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> elements in <code class="param">tracks</code>. If 0, existing tracks are cleared. Must be >= 0 and (recommended) <= UINT16_MAX.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>int32_t API status code indicating success or the nature of the failure. </dd></dl>
|
||
<dl class="retval"><dt>Return values</dt><dd>
|
||
<table class="retval">
|
||
<tr><td class="paramname">AARUF_STATUS_OK</td><td>Success (tracks replaced or cleared). </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td><code class="param">context</code> is NULL or not a recognized libaaruformat context. </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INVALID_TRACK_FORMAT</td><td>Invalid input (tracks NULL with count > 0, or count < 0). </td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>Memory allocation failed while copying tracks.</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>Not thread-safe. Do not invoke concurrently with readers/writers of the same context. </dd></dl>
|
||
<dl class="section note"><dt>Note</dt><dd>After success, <a class="el" href="optical_8c.html#a2ce65757ca5209f17d467c51ba7d445d" title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a> can be used to read back the stored table. </dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="optical_8c.html#a2ce65757ca5209f17d467c51ba7d445d" title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a></dd></dl>
|
||
<dl class="section since"><dt>Since</dt><dd>1.0</dd></dl>
|
||
<p>Usage example (conceptual):</p><ol type="1">
|
||
<li>Prepare an array of <a class="el" href="structTrackEntry.html" title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures (N elements) and fill the fields.</li>
|
||
<li>Call aaruf_set_tracks(ctx, array, N) to store them; check for AARUF_STATUS_OK.</li>
|
||
<li>To clear all tracks later call aaruf_set_tracks(ctx, NULL, 0).</li>
|
||
<li>Use <a class="el" href="optical_8c.html#a2ce65757ca5209f17d467c51ba7d445d" title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a> afterwards to retrieve them if needed. </li>
|
||
</ol>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="optical_8c_source.html#l00392">392</a> of file <a class="el" href="optical_8c_source.html">optical.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="crc64_8c_source.html#l00160">aaruf_crc64_data()</a>, <a class="el" href="errors_8h_source.html#l00054">AARUF_ERROR_INVALID_TRACK_FORMAT</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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="optical_8h_source.html#l00065">TracksHeader::crc64</a>, <a class="el" href="context_8h_source.html#l00243">aaruformat_context::data_tracks</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="aaru_8h_source.html#l00871">ImageInfo::HasPartitions</a>, <a class="el" href="aaru_8h_source.html#l00872">ImageInfo::HasSessions</a>, <a class="el" href="optical_8h_source.html#l00063">TracksHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00245">aaruformat_context::number_of_data_tracks</a>, <a class="el" href="optical_8h_source.html#l00073">TrackEntry::sequence</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="context_8h_source.html#l00242">aaruformat_context::track_entries</a>, <a class="el" href="context_8h_source.html#l00244">aaruformat_context::tracks_header</a>, and <a class="el" href="enums_8h_source.html#l00150">TracksBlock</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a1e8667b4e2bc168a5411d9671a44a73c" name="a1e8667b4e2bc168a5411d9671a44a73c"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a1e8667b4e2bc168a5411d9671a44a73c">◆ </a></span>aaruf_sha1_buffer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha1_buffer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>size</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned char *</td> <td class="paramname"><span class="paramname"><em>result</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha1_8c_source.html#l00155">155</a> of file <a class="el" href="sha1_8c_source.html">sha1.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha1_8c_source.html#l00124">aaruf_sha1_final()</a>, <a class="el" href="sha1_8c_source.html#l00034">aaruf_sha1_init()</a>, and <a class="el" href="sha1_8c_source.html#l00089">aaruf_sha1_update()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a0396232d1020b16b2cb4bf0b1aa2b021" name="a0396232d1020b16b2cb4bf0b1aa2b021"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a0396232d1020b16b2cb4bf0b1aa2b021">◆ </a></span>aaruf_sha1_final()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha1_final </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structsha1__ctx.html">sha1_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned char *</td> <td class="paramname"><span class="paramname"><em>result</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha1_8c_source.html#l00124">124</a> of file <a class="el" href="sha1_8c_source.html">sha1.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha1_8c_source.html#l00089">aaruf_sha1_update()</a>, <a class="el" href="sha1_8h_source.html#l00046">sha1_ctx::buffer</a>, <a class="el" href="sha1_8h_source.html#l00045">sha1_ctx::count</a>, and <a class="el" href="sha1_8h_source.html#l00044">sha1_ctx::state</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="sha1_8c_source.html#l00155">aaruf_sha1_buffer()</a>, and <a class="el" href="close_8c_source.html#l00654">write_checksum_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a9bcd5c47b9b593c95be9d4f82253739a" name="a9bcd5c47b9b593c95be9d4f82253739a"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a9bcd5c47b9b593c95be9d4f82253739a">◆ </a></span>aaruf_sha1_init()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha1_init </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structsha1__ctx.html">sha1_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha1_8c_source.html#l00034">34</a> of file <a class="el" href="sha1_8c_source.html">sha1.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha1_8h_source.html#l00046">sha1_ctx::buffer</a>, <a class="el" href="sha1_8h_source.html#l00045">sha1_ctx::count</a>, and <a class="el" href="sha1_8h_source.html#l00044">sha1_ctx::state</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>, and <a class="el" href="sha1_8c_source.html#l00155">aaruf_sha1_buffer()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="abead53c8e55f1f99900fdae16d9da70f" name="abead53c8e55f1f99900fdae16d9da70f"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#abead53c8e55f1f99900fdae16d9da70f">◆ </a></span>aaruf_sha1_update()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha1_update </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structsha1__ctx.html">sha1_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>size</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha1_8c_source.html#l00089">89</a> of file <a class="el" href="sha1_8c_source.html">sha1.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha1_8h_source.html#l00046">sha1_ctx::buffer</a>, <a class="el" href="sha1_8h_source.html#l00045">sha1_ctx::count</a>, <a class="el" href="sha1_8c_source.html#l00045">sha1_transform()</a>, and <a class="el" href="sha1_8h_source.html#l00044">sha1_ctx::state</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="sha1_8c_source.html#l00155">aaruf_sha1_buffer()</a>, <a class="el" href="sha1_8c_source.html#l00124">aaruf_sha1_final()</a>, <a class="el" href="write_8c_source.html#l00098">aaruf_write_sector()</a>, and <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a7bae173c313a0752035e6eac045326e8" name="a7bae173c313a0752035e6eac045326e8"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a7bae173c313a0752035e6eac045326e8">◆ </a></span>aaruf_sha256_buffer()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha256_buffer </td>
|
||
<td>(</td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>size</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned char *</td> <td class="paramname"><span class="paramname"><em>result</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha256_8c_source.html#l00141">141</a> of file <a class="el" href="sha256_8c_source.html">sha256.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha256_8c_source.html#l00115">aaruf_sha256_final()</a>, <a class="el" href="sha256_8c_source.html#l00076">aaruf_sha256_init()</a>, and <a class="el" href="sha256_8c_source.html#l00090">aaruf_sha256_update()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a6456150dad701ca7f071940ef169c4cf" name="a6456150dad701ca7f071940ef169c4cf"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a6456150dad701ca7f071940ef169c4cf">◆ </a></span>aaruf_sha256_final()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha256_final </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structsha256__ctx.html">sha256_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned char *</td> <td class="paramname"><span class="paramname"><em>result</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha256_8c_source.html#l00115">115</a> of file <a class="el" href="sha256_8c_source.html">sha256.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha256_8c_source.html#l00090">aaruf_sha256_update()</a>, <a class="el" href="sha256_8h_source.html#l00044">sha256_ctx::bitcount</a>, <a class="el" href="sha256_8h_source.html#l00045">sha256_ctx::buffer</a>, and <a class="el" href="sha256_8h_source.html#l00043">sha256_ctx::state</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="sha256_8c_source.html#l00141">aaruf_sha256_buffer()</a>, and <a class="el" href="close_8c_source.html#l00654">write_checksum_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a075527f7b15b70dc7028cf91d9062a90" name="a075527f7b15b70dc7028cf91d9062a90"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a075527f7b15b70dc7028cf91d9062a90">◆ </a></span>aaruf_sha256_init()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha256_init </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structsha256__ctx.html">sha256_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha256_8c_source.html#l00076">76</a> of file <a class="el" href="sha256_8c_source.html">sha256.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha256_8h_source.html#l00044">sha256_ctx::bitcount</a>, <a class="el" href="sha256_8h_source.html#l00045">sha256_ctx::buffer</a>, and <a class="el" href="sha256_8h_source.html#l00043">sha256_ctx::state</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>, and <a class="el" href="sha256_8c_source.html#l00141">aaruf_sha256_buffer()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ab5f178e5ec94596e44a3fdb001d4a5f8" name="ab5f178e5ec94596e44a3fdb001d4a5f8"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ab5f178e5ec94596e44a3fdb001d4a5f8">◆ </a></span>aaruf_sha256_update()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_sha256_update </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structsha256__ctx.html">sha256_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>data</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>size</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="sha256_8c_source.html#l00090">90</a> of file <a class="el" href="sha256_8c_source.html">sha256.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="sha256_8h_source.html#l00044">sha256_ctx::bitcount</a>, <a class="el" href="sha256_8h_source.html#l00045">sha256_ctx::buffer</a>, <a class="el" href="sha256_8c_source.html#l00041">sha256_transform()</a>, and <a class="el" href="sha256_8h_source.html#l00043">sha256_ctx::state</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="sha256_8c_source.html#l00141">aaruf_sha256_buffer()</a>, <a class="el" href="sha256_8c_source.html#l00115">aaruf_sha256_final()</a>, <a class="el" href="write_8c_source.html#l00098">aaruf_write_sector()</a>, and <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="ab1f4894af1962e933767248c4fb0e2e8" name="ab1f4894af1962e933767248c4fb0e2e8"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#ab1f4894af1962e933767248c4fb0e2e8">◆ </a></span>aaruf_spamsum_final()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int aaruf_spamsum_final </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t *</td> <td class="paramname"><span class="paramname"><em>result</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00191">191</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="spamsum_8c_source.html#l00032">b64</a>, <a class="el" href="spamsum_8h_source.html#l00054">spamsum_ctx::bh</a>, <a class="el" href="spamsum_8h_source.html#l00053">spamsum_ctx::bh_end</a>, <a class="el" href="spamsum_8h_source.html#l00052">spamsum_ctx::bh_start</a>, <a class="el" href="spamsum_8h_source.html#l00038">blockhash_ctx::d_len</a>, <a class="el" href="spamsum_8h_source.html#l00036">blockhash_ctx::digest</a>, <a class="el" href="spamsum_8h_source.html#l00030">FUZZY_MAX_RESULT</a>, <a class="el" href="spamsum_8h_source.html#l00034">blockhash_ctx::h</a>, <a class="el" href="spamsum_8h_source.html#l00037">blockhash_ctx::half_digest</a>, <a class="el" href="spamsum_8h_source.html#l00035">blockhash_ctx::half_h</a>, <a class="el" href="spamsum_8h_source.html#l00025">NUM_BLOCKHASHES</a>, <a class="el" href="spamsum_8c_source.html#l00080">ROLL_SUM</a>, <a class="el" href="spamsum_8h_source.html#l00024">SPAMSUM_LENGTH</a>, and <a class="el" href="spamsum_8c_source.html#l00082">SSDEEP_BS</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="close_8c_source.html#l00654">write_checksum_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a6fe74704e44be7adfaa2ce676f3c3de4" name="a6fe74704e44be7adfaa2ce676f3c3de4"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a6fe74704e44be7adfaa2ce676f3c3de4">◆ </a></span>aaruf_spamsum_free()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void aaruf_spamsum_free </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Frees a spamsum (fuzzy hash) context. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">ctx</td><td>Pointer to the spamsum context to free. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00075">75</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, and <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00030">cleanup_failed_create()</a>, and <a class="el" href="close_8c_source.html#l00654">write_checksum_block()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a793dac760aedda6414ba4014eb2ed0c7" name="a793dac760aedda6414ba4014eb2ed0c7"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a793dac760aedda6414ba4014eb2ed0c7">◆ </a></span>aaruf_spamsum_init()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> * aaruf_spamsum_init </td>
|
||
<td>(</td>
|
||
<td class="paramtype">void</td> <td class="paramname"><span class="paramname"><em></em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00037">37</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="spamsum_8h_source.html#l00054">spamsum_ctx::bh</a>, <a class="el" href="spamsum_8h_source.html#l00053">spamsum_ctx::bh_end</a>, <a class="el" href="spamsum_8h_source.html#l00034">blockhash_ctx::h</a>, <a class="el" href="spamsum_8h_source.html#l00035">blockhash_ctx::half_h</a>, and <a class="el" href="spamsum_8h_source.html#l00027">HASH_INIT</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a5a9767f3b860752b493aa7bee9d39a8d" name="a5a9767f3b860752b493aa7bee9d39a8d"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a5a9767f3b860752b493aa7bee9d39a8d">◆ </a></span>aaruf_spamsum_update()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int aaruf_spamsum_update </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</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 uint32_t</td> <td class="paramname"><span class="paramname"><em>len</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Updates the spamsum context with new data. </p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">ctx</td><td>Pointer to the spamsum context. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the data to process. </td></tr>
|
||
<tr><td class="paramname">len</td><td>Length of the data in bytes. </td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00059">59</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="spamsum_8c_source.html#l00084">fuzzy_engine_step()</a>, and <a class="el" href="spamsum_8h_source.html#l00055">spamsum_ctx::total_size</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l00098">aaruf_write_sector()</a>, and <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a8cbf4d8059c4b36e8ab5e18fec057b52" name="a8cbf4d8059c4b36e8ab5e18fec057b52"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a8cbf4d8059c4b36e8ab5e18fec057b52">◆ </a></span>aaruf_verify_image()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_verify_image </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>Verifies the integrity of an AaruFormat image file. </p>
|
||
<p>Checks the integrity of all blocks and deduplication tables in the image by validating CRC64 checksums for each indexed block. This function performs comprehensive verification of data blocks, DDT v1 and v2 tables, tracks blocks, and other structural components. It reads blocks in chunks to optimize memory usage during verification and supports version-specific CRC endianness handling.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat 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">AARUF_STATUS_OK</td><td>(0) Successfully verified image integrity. This is returned when:<ul>
|
||
<li>All indexed blocks are successfully read and processed</li>
|
||
<li>All CRC64 checksums match their expected values</li>
|
||
<li>Index verification passes for the detected index version</li>
|
||
<li>All block headers are readable and valid</li>
|
||
<li>Memory allocation for verification buffer succeeds</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_HEADER</td><td>(-6) Failed to read critical headers. This occurs when:<ul>
|
||
<li>Cannot read the index signature from the image stream</li>
|
||
<li>File I/O errors prevent reading header structures</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_INDEX</td><td>(-4) Index processing or validation failed. This occurs when:<ul>
|
||
<li>Index signature is not a recognized type (IndexBlock, IndexBlock2, or IndexBlock3)</li>
|
||
<li>Index verification functions return error codes</li>
|
||
<li>Index processing functions return NULL (corrupted or invalid index)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. This occurs when:<ul>
|
||
<li>Cannot allocate VERIFY_SIZE (1MB) buffer for reading block data during verification</li>
|
||
<li>System is out of available memory for verification operations</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-7) Block reading failed. This occurs when:<ul>
|
||
<li>Cannot read block headers (DataBlock, DeDuplicationTable, DeDuplicationTable2, TracksBlock)</li>
|
||
<li>File I/O errors prevent reading block structure data</li>
|
||
<li>CRC64 context initialization fails (internal error)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INVALID_BLOCK_CRC</td><td>(-18) CRC verification failed. This occurs when:<ul>
|
||
<li>Calculated CRC64 doesn't match the expected CRC64 in block headers</li>
|
||
<li>Data corruption is detected in any verified block</li>
|
||
<li>This applies to DataBlock, DeDuplicationTable, DeDuplicationTable2, and TracksBlock types</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Verification Process:<ul>
|
||
<li>Reads blocks in VERIFY_SIZE (1MB) chunks to optimize memory usage</li>
|
||
<li>Supports version-specific CRC64 endianness (v1 uses byte-swapped CRC64)</li>
|
||
<li>Verifies only blocks that have CRC checksums (skips blocks without checksums)</li>
|
||
<li>Unknown block types are logged but don't cause verification failure</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Block Types Verified:<ul>
|
||
<li>DataBlock: Verifies compressed data CRC64 against block header</li>
|
||
<li>DeDuplicationTable (v1): Verifies DDT data CRC64 with version-specific endianness</li>
|
||
<li>DeDuplicationTable2 (v2): Verifies DDT data CRC64 (no endianness conversion)</li>
|
||
<li>TracksBlock: Verifies track entries CRC64 with version-specific endianness</li>
|
||
<li>Other block types are ignored during verification</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Performance Considerations:<ul>
|
||
<li>Uses chunked reading to minimize memory footprint during verification</li>
|
||
<li>Processes blocks sequentially to maintain good disk access patterns</li>
|
||
<li>CRC64 contexts are created and destroyed for each block to prevent memory leaks</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>This function performs read-only verification and does not modify the image. It requires the image to be properly opened with a valid context.</dd>
|
||
<dd>
|
||
Verification failure indicates data corruption or tampering. Images that fail verification should not be trusted for data recovery operations.</dd>
|
||
<dd>
|
||
The function allocates a 1MB buffer for verification. Ensure sufficient memory is available before calling this function on resource-constrained systems. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="verify_8c_source.html#l00130">130</a> of file <a class="el" href="verify_8c_source.html">verify.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="crc64_8c_source.html#l00141">aaruf_crc64_final()</a>, <a class="el" href="crc64_8c_source.html#l00155">aaruf_crc64_free()</a>, <a class="el" href="crc64_8c_source.html#l00032">aaruf_crc64_init()</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00045">AARUF_ERROR_CANNOT_READ_HEADER</a>, <a class="el" href="errors_8h_source.html#l00043">AARUF_ERROR_CANNOT_READ_INDEX</a>, <a class="el" href="errors_8h_source.html#l00057">AARUF_ERROR_INVALID_BLOCK_CRC</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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="consts_8h_source.html#l00071">AARUF_VERSION_V1</a>, <a class="el" href="index_8h_source.html#l00110">IndexEntry::blockType</a>, <a class="el" href="endian_8h_source.html#l00081">bswap_64</a>, <a class="el" href="data_8h_source.html#l00078">BlockHeader::cmpCrc64</a>, <a class="el" href="ddt_8h_source.html#l00161">DdtHeader2::cmpCrc64</a>, <a class="el" href="ddt_8h_source.html#l00074">DdtHeader::cmpCrc64</a>, <a class="el" href="data_8h_source.html#l00076">BlockHeader::cmpLength</a>, <a class="el" href="ddt_8h_source.html#l00159">DdtHeader2::cmpLength</a>, <a class="el" href="ddt_8h_source.html#l00072">DdtHeader::cmpLength</a>, <a class="el" href="optical_8h_source.html#l00065">TracksHeader::crc64</a>, <a class="el" href="enums_8h_source.html#l00141">DataBlock</a>, <a class="el" href="enums_8h_source.html#l00142">DeDuplicationTable</a>, <a class="el" href="enums_8h_source.html#l00143">DeDuplicationTable2</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00175">aaruformat_context::header</a>, <a class="el" href="header_8h_source.html#l00110">AaruHeaderV2::imageMajorVersion</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="enums_8h_source.html#l00145">IndexBlock</a>, <a class="el" href="enums_8h_source.html#l00146">IndexBlock2</a>, <a class="el" href="enums_8h_source.html#l00147">IndexBlock3</a>, <a class="el" href="header_8h_source.html#l00115">AaruHeaderV2::indexOffset</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="index_8h_source.html#l00112">IndexEntry::offset</a>, <a class="el" href="index__v1_8c_source.html#l00079">process_index_v1()</a>, <a class="el" href="index__v2_8c_source.html#l00081">process_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00098">process_index_v3()</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="enums_8h_source.html#l00150">TracksBlock</a>, <a class="el" href="verify_8c_source.html#l00030">update_crc64_from_stream()</a>, <a class="el" href="index__v1_8c_source.html#l00225">verify_index_v1()</a>, <a class="el" href="index__v2_8c_source.html#l00227">verify_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00408">verify_index_v3()</a>, and <a class="el" href="verify_8c_source.html#l00028">VERIFY_SIZE</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="aa041a789fbae70c1e1ec3e38f1ab369d" name="aa041a789fbae70c1e1ec3e38f1ab369d"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#aa041a789fbae70c1e1ec3e38f1ab369d">◆ </a></span>aaruf_write_media_tag()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_write_media_tag </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>type</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>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Writes a media tag to the AaruFormat image, storing medium-specific metadata and descriptors. </p>
|
||
<p>This function stores arbitrary media-specific metadata (media tags) in the AaruFormat image context for later serialization during image finalization. Media tags represent higher-level descriptors and metadata structures that characterize the storage medium beyond sector data, including disc information structures, lead-in/lead-out data, manufacturer identifiers, drive capabilities, and format-specific metadata. The function uses a hash table for efficient tag storage and retrieval, automatically replacing existing tags of the same type and managing memory for tag data.</p>
|
||
<p><b>Supported Media Tag Categories:</b></p>
|
||
<p><b>Optical Disc Metadata (CD/DVD/BD/HD DVD):</b></p><ul>
|
||
<li><b>CD_TOC (0)</b>: Table of Contents from READ TOC/PMA/ATIP command (Format 0000b - Formatted TOC)<ul>
|
||
<li>Contains track entries, session boundaries, lead-in/lead-out addressing, and track types</li>
|
||
<li>Essential for multi-session and mixed-mode CD structure representation</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>CD_FullTOC (1)</b>: Full TOC (Format 0010b) including session info and point/ADR/control fields<ul>
|
||
<li>Provides complete session structure with ADR field interpretation and sub-Q channel details</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>CD_SessionInfo (2)</b>: Session information (Format 0001b) for multi-session discs</li>
|
||
<li><b>CD_TEXT (3)</b>: CD-TEXT data from lead-in area (artist, title, performer, songwriter metadata)</li>
|
||
<li><b>CD_ATIP (4)</b>: Absolute Time In Pregroove (CD-R/RW timing calibration and media manufacturer data)</li>
|
||
<li><b>CD_PMA (5)</b>: Power Management Area (CD-R/RW recording session management metadata)</li>
|
||
<li><b>DVD_PFI (6)</b>: Physical Format Information (DVD layer characteristics, book type, linear density)</li>
|
||
<li><b>DVD_DMI (7)</b>: Disc Manufacturing Information (DVD unique identifier and replication metadata)</li>
|
||
<li><b>DVD_BCA (8)</b>: Burst Cutting Area (copy protection and regional management data for DVD-Video)</li>
|
||
<li><b>BD_DI (28)</b>: Disc Information (Blu-ray layer count, recording format, disc size, channel bit length)</li>
|
||
<li><b>BD_BCA (29)</b>: Blu-ray Burst Cutting Area (unique disc identifier and anti-counterfeiting data)</li>
|
||
</ul>
|
||
<p><b>Recordable Media Structures:</b></p><ul>
|
||
<li><b>DVDR_RMD (17)</b>: Recorded Media Data (last border-out RMD for DVD-R/-RW finalization state)</li>
|
||
<li><b>DVDR_PreRecordedInfo (18)</b>: Pre-recorded information area from lead-in (DVD-R physical specs)</li>
|
||
<li><b>DVDR_MediaIdentifier (19)</b>: Writable media identifier (DVD-R/-RW unique ID from manufacturer)</li>
|
||
<li><b>BD_DDS (30)</b>: Disc Definition Structure (BD-R/RE recording management and spare area allocation)</li>
|
||
<li><b>BD_SpareArea (32)</b>: BD spare area allocation map (defect management for recordable Blu-ray)</li>
|
||
</ul>
|
||
<p><b>Copy Protection and Security:</b></p><ul>
|
||
<li><b>AACS_VolumeIdentifier (33)</b>: AACS Volume Identifier (content identifier for AACS-protected media)</li>
|
||
<li><b>AACS_SerialNumber (34)</b>: Pre-recorded media serial number (unique per AACS disc pressing)</li>
|
||
<li><b>AACS_MediaIdentifier (35)</b>: AACS Media Identifier (cryptographic binding to physical medium)</li>
|
||
<li><b>AACS_MKB (36)</b>: AACS Media Key Block (encrypted title keys and revocation lists)</li>
|
||
<li><b>AACS_DataKeys (37)</b>: Extracted AACS title/volume keys (when decrypted, for archival purposes)</li>
|
||
<li><b>AACS_CPRM_MKB (39)</b>: CPRM Media Key Block (Content Protection for Recordable Media)</li>
|
||
</ul>
|
||
<p><b>Device and Drive Information:</b></p><ul>
|
||
<li><b>SCSI_INQUIRY (45)</b>: SCSI INQUIRY standard data (device type, vendor, model, firmware revision)</li>
|
||
<li><b>SCSI_MODEPAGE_2A (46)</b>: SCSI Mode Page 2Ah (CD/DVD/BD capabilities and supported features)</li>
|
||
<li><b>ATA_IDENTIFY (47)</b>: ATA IDENTIFY DEVICE response (512 bytes of drive capabilities and geometry)</li>
|
||
<li><b>ATAPI_IDENTIFY (48)</b>: ATA PACKET IDENTIFY DEVICE (ATAPI drive identification and features)</li>
|
||
<li><b>MMC_WriteProtection (41)</b>: Write protection status from MMC GET CONFIGURATION command</li>
|
||
<li><b>MMC_DiscInformation (42)</b>: Disc Information (recordable status, erasable flag, last session)</li>
|
||
</ul>
|
||
<p><b>Flash and Solid-State Media:</b></p><ul>
|
||
<li><b>SD_CID (50)</b>: SecureDigital Card ID register (manufacturer, OEM, product name, serial number)</li>
|
||
<li><b>SD_CSD (51)</b>: SecureDigital Card Specific Data (capacity, speed class, file format)</li>
|
||
<li><b>SD_SCR (52)</b>: SecureDigital Configuration Register (SD spec version, bus widths, security)</li>
|
||
<li><b>SD_OCR (53)</b>: SecureDigital Operation Conditions Register (voltage ranges, capacity type)</li>
|
||
<li><b>MMC_CID (54)</b>: MMC Card ID (similar to SD_CID for eMMC/MMC devices)</li>
|
||
<li><b>MMC_CSD (55)</b>: MMC Card Specific Data (MMC device parameters)</li>
|
||
<li><b>MMC_ExtendedCSD (57)</b>: MMC Extended CSD (512 bytes of extended MMC capabilities)</li>
|
||
</ul>
|
||
<p><b>Gaming Console Media:</b></p><ul>
|
||
<li><b>Xbox_SecuritySector (58)</b>: Xbox/Xbox 360 Security Sector (SS.bin - anti-piracy signature data)</li>
|
||
<li><b>Xbox_DMI (66)</b>: Xbox Disc Manufacturing Info (manufacturing plant and batch metadata)</li>
|
||
<li><b>Xbox_PFI (67)</b>: Xbox Physical Format Information (Xbox-specific DVD layer configuration)</li>
|
||
</ul>
|
||
<p><b>Specialized Structures:</b></p><ul>
|
||
<li><b>CD_FirstTrackPregap (61)</b>: First track pregap (index 0 contents, typically silent on audio CDs)</li>
|
||
<li><b>CD_LeadOut (62)</b>: Lead-out area contents (post-data region signaling disc end)</li>
|
||
<li><b>CD_LeadIn (68)</b>: Raw lead-in data (TOC frames and sub-Q channel from pre-data region)</li>
|
||
<li><b>Floppy_LeadOut (59)</b>: Manufacturer/duplication cylinder (floppy copy protection metadata)</li>
|
||
<li><b>PCMCIA_CIS (49)</b>: PCMCIA/CardBus Card Information Structure tuple chain</li>
|
||
<li><b>USB_Descriptors (65)</b>: Concatenated USB descriptors (device/config/interface for USB drives)</li>
|
||
</ul>
|
||
<p><b>Data Processing Pipeline:</b></p><ol type="1">
|
||
<li><b>Context Validation</b>: Verifies context is valid AaruFormat context with write permissions</li>
|
||
<li><b>Parameter Validation</b>: Checks data pointer is non-NULL and length is non-zero</li>
|
||
<li><b>Memory Allocation</b>: Allocates new buffer for tag data and <a class="el" href="structmediaTagEntry.html" title="Hash table entry for an arbitrary media tag (e.g., proprietary drive/medium descriptor).">mediaTagEntry</a> structure</li>
|
||
<li><b>Data Copying</b>: Performs deep copy of tag data to ensure context owns the memory</li>
|
||
<li><b>Hash Table Insertion</b>: Adds or replaces entry in mediaTags hash table using uthash HASH_REPLACE_INT</li>
|
||
<li><b>Cleanup</b>: Frees old media tag entry and data if replacement occurred</li>
|
||
<li><b>Return Success</b>: Returns AARUF_STATUS_OK on successful completion</li>
|
||
</ol>
|
||
<p><b>Memory Management Strategy:</b></p><ul>
|
||
<li><b>Deep Copy Semantics</b>: Function performs deep copy of input data; caller retains ownership of original buffer</li>
|
||
<li><b>Automatic Replacement</b>: Existing tag of same type is automatically freed when replaced</li>
|
||
<li><b>Hash Table Storage</b>: Media tags stored in uthash-based hash table for O(1) lookup by type</li>
|
||
<li><b>Deferred Serialization</b>: Tag data remains in memory until <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> serializes to image file</li>
|
||
<li><b>Cleanup on Close</b>: All media tag memory automatically freed during <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a></li>
|
||
</ul>
|
||
<p><b>Tag Type Identification:</b> The type parameter accepts <a class="el" href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> enumeration values (0-68) that identify the semantic meaning of the tag data. The library does not validate tag data structure or size against the type identifier - callers are responsible for providing correctly formatted tag data matching the declared type. Type values are preserved as-is and used during serialization to identify tag purpose during image reading.</p>
|
||
<p><b>Replacement Behavior:</b> When a media tag of the same type already exists in the context:</p><ul>
|
||
<li>The old tag entry is removed from the hash table</li>
|
||
<li>The old tag's data buffer is freed</li>
|
||
<li>The old tag entry structure is freed</li>
|
||
<li>The new tag replaces the old tag in the hash table</li>
|
||
<li>No warning or error is generated for replacement This allows incremental updates to media tags during image creation.</li>
|
||
</ul>
|
||
<p><b>Serialization and Persistence:</b> Media tags written via this function are not immediately written to the image file. Instead, they are accumulated in the context's mediaTags hash table and serialized during <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> as part of the image finalization process. The serialization creates a metadata block in the image file that preserves all media tags with their type identifiers and data lengths.</p>
|
||
<p><b>Thread Safety and Concurrency:</b> This function is NOT thread-safe. The context contains mutable shared state including:</p><ul>
|
||
<li>mediaTags hash table modification</li>
|
||
<li>Memory allocation and deallocation</li>
|
||
<li>No internal locking or synchronization External synchronization required for concurrent access from multiple threads.</li>
|
||
</ul>
|
||
<p><b>Performance Considerations:</b></p><ul>
|
||
<li>Hash table insertion is O(1) average case for new tags</li>
|
||
<li>Hash table replacement is O(1) for existing tags</li>
|
||
<li>Memory allocation overhead proportional to tag data size</li>
|
||
<li>No disk I/O occurs during this call (deferred to <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>)</li>
|
||
<li>Suitable for frequent tag updates during image creation workflow</li>
|
||
</ul>
|
||
<p><b>Typical Usage Scenarios:</b></p><ul>
|
||
<li><b>Optical Disc Imaging</b>: Store TOC, PMA, ATIP, CD-TEXT from READ TOC family commands</li>
|
||
<li><b>Copy Protection Preservation</b>: Store BCA, AACS structures, media identifiers for archival</li>
|
||
<li><b>Drive Capabilities</b>: Store INQUIRY, Mode Page 2Ah, IDENTIFY data for forensic metadata</li>
|
||
<li><b>Flash Card Imaging</b>: Store CID, CSD, SCR, OCR registers from SD/MMC cards</li>
|
||
<li><b>Console Game Preservation</b>: Store Xbox security sectors and manufacturing metadata</li>
|
||
<li><b>Recordable Media</b>: Store RMD, media identifiers, spare area maps for write-once media</li>
|
||
</ul>
|
||
<p><b>Validation and Error Handling:</b></p><ul>
|
||
<li>Context validity checked via magic number comparison (AARU_MAGIC)</li>
|
||
<li>Write permission verified via isWriting flag</li>
|
||
<li>NULL data pointer triggers AARUF_ERROR_INCORRECT_DATA_SIZE</li>
|
||
<li>Zero length triggers AARUF_ERROR_INCORRECT_DATA_SIZE</li>
|
||
<li>Memory allocation failures return AARUF_ERROR_NOT_ENOUGH_MEMORY</li>
|
||
<li>No validation of tag data structure or size against type identifier</li>
|
||
</ul>
|
||
<p><b>Data Format Requirements:</b> The function accepts arbitrary binary data without format validation. Callers must ensure:</p><ul>
|
||
<li>Tag data matches the declared <a class="el" href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> structure and size</li>
|
||
<li>Binary data is properly byte-ordered for the target platform</li>
|
||
<li>Variable-length tags include proper internal length fields if required</li>
|
||
<li>Tag data represents a complete, self-contained structure</li>
|
||
</ul>
|
||
<p><b>Integration with Image Creation Workflow:</b> Media tags should typically be written after creating the image context (<a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>) but before writing sector data. However, tags can be added or updated at any point during the writing process. Common workflow:</p><ol type="1">
|
||
<li>Create image context with <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>Set tracks with <a class="el" href="#a518d8d68debf1b9a24af3eb6bc2f9e49" title="Replace (or clear) the in-memory track table for an AaruFormat image context.">aaruf_set_tracks()</a> if applicable</li>
|
||
<li>Write media tags with write_media_tag() for all available metadata</li>
|
||
<li>Write sector data with <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> or <a class="el" href="write_8c.html#a69ca66242c0becf7640b3d1cc8da8f9c" title="Writes a full ("long") raw sector from optical or block media, parsing structure and validating conte...">aaruf_write_sector_long()</a></li>
|
||
<li>Close image with <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> to finalize and serialize all metadata</li>
|
||
</ol>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformatContext with magic == AARU_MAGIC opened for writing. Must be created via <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a> and not yet closed. The context's isWriting flag must be true, indicating write mode is active. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the media tag data buffer to write. Must be a valid non-NULL pointer to a buffer containing the complete tag data. The function performs a deep copy of this data, so the caller retains ownership and may free or modify the source buffer after this call returns. The data format must match the structure expected for the specified type parameter. </td></tr>
|
||
<tr><td class="paramname">type</td><td>Integer identifier specifying the type of media tag (<a class="el" href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> enumeration). Values range from 0 (CD_TOC) to 68 (CD_LeadIn). The type identifies the semantic meaning of the tag data and is preserved in the image file for interpretation during reading. The library does not validate that the data structure matches the declared type - caller responsibility to ensure correctness. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Length in bytes of the media tag data buffer. Must be greater than zero. Specifies how many bytes to copy from the data buffer. No maximum length enforced, but extremely large tags may cause memory allocation failures.</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">AARUF_STATUS_OK</td><td>(0) Successfully wrote the media tag. This is returned when:<ul>
|
||
<li>Context is valid with correct magic number (AARU_MAGIC)</li>
|
||
<li>Context is in writing mode (isWriting == true)</li>
|
||
<li>Data pointer is non-NULL and length is non-zero</li>
|
||
<li>Memory allocation succeeded for both tag data and entry structure</li>
|
||
<li>Tag entry successfully inserted into mediaTags hash table</li>
|
||
<li>If replacing existing tag, old tag successfully freed</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context provided. This occurs when:<ul>
|
||
<li>context parameter is NULL (no context provided)</li>
|
||
<li>Context magic number != AARU_MAGIC (wrong context type, corrupted context, or uninitialized)</li>
|
||
<li>Context was not created by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a> or has been corrupted</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-22) Attempting to write to read-only image. This occurs when:<ul>
|
||
<li>Context isWriting flag is false</li>
|
||
<li>Image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
<li>Context is in read-only mode and modifications are not permitted</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_DATA_SIZE</td><td>(-8) Invalid data or length parameters. This occurs when:<ul>
|
||
<li>data parameter is NULL (no tag data provided)</li>
|
||
<li>length parameter is zero (no data to write)</li>
|
||
<li>Parameters indicate invalid or empty tag data</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. This occurs when:<ul>
|
||
<li>Failed to allocate buffer for tag data copy (malloc(length) failed)</li>
|
||
<li>Failed to allocate <a class="el" href="structmediaTagEntry.html" title="Hash table entry for an arbitrary media tag (e.g., proprietary drive/medium descriptor).">mediaTagEntry</a> structure (malloc(sizeof(mediaTagEntry)) failed)</li>
|
||
<li>System is out of available memory for requested allocation size</li>
|
||
<li>Memory allocation fails due to resource exhaustion or fragmentation</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd><b>Cross-References</b>: This function is the write counterpart to <a class="el" href="#a48f93ec154d0aed7cb713391a7717b46" title="Reads a media tag from the AaruFormat image.">aaruf_read_media_tag()</a>. See also:<ul>
|
||
<li><a class="el" href="#a48f93ec154d0aed7cb713391a7717b46" title="Reads a media tag from the AaruFormat image.">aaruf_read_media_tag()</a>: Reads media tag data from opened image</li>
|
||
<li><a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a>: Creates writable image context required for this function</li>
|
||
<li><a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>: Serializes media tags to image file and frees tag memory</li>
|
||
<li><a class="el" href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> enumeration in <a class="el" href="aaru_8h.html" title="Public high-level API types: media classifications, per-sector / per-media tag enums and image summar...">aaru.h</a>: Defines valid type identifier values</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
<b>Memory Ownership</b>: The function performs a deep copy of tag data. After successful return, the context owns the copied tag data and the caller may free or modify the original data buffer. On failure, no memory is retained by the context - caller maintains full ownership of input buffer regardless of success or failure.</dd>
|
||
<dd>
|
||
<b>Tag Uniqueness</b>: Only one media tag of each type can exist in an image. Writing a tag with a type that already exists will replace the previous tag, freeing its memory and using the new tag data. No error or warning is generated for replacements.</dd>
|
||
<dd>
|
||
<b>Deferred Serialization</b>: Media tags are not written to disk until <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> is called. All tags remain in memory throughout the image creation process. For images with many or large media tags, memory usage may be significant.</dd>
|
||
<dd>
|
||
<b>No Type Validation</b>: The library does not validate that tag data matches the declared type. Callers must ensure data structure correctness. Mismatched data may cause reading applications to fail or misinterpret tag contents.</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd><b>Memory Growth</b>: Each media tag consumes memory equal to tag data size plus <a class="el" href="structmediaTagEntry.html" title="Hash table entry for an arbitrary media tag (e.g., proprietary drive/medium descriptor).">mediaTagEntry</a> structure overhead. Large tags or many tags can significantly increase memory usage. Monitor memory consumption when writing extensive metadata.</dd>
|
||
<dd>
|
||
<b>Type Correctness</b>: No validation occurs for tag data format against type identifier. Providing incorrectly formatted data or mismatched type identifiers will create a valid image file with invalid tag data that may cause failures when reading. Ensure data format matches <a class="el" href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> specification requirements.</dd>
|
||
<dd>
|
||
<b>Replacement Silent</b>: Replacing an existing tag does not generate warnings or errors. Applications expecting to detect duplicate tag writes must track this externally. The most recent write_media_tag() call for each type determines the final tag value.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a48f93ec154d0aed7cb713391a7717b46" title="Reads a media tag from the AaruFormat image.">aaruf_read_media_tag()</a> for corresponding media tag reading functionality </dd>
|
||
<dd>
|
||
<a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a> for image context creation in write mode </dd>
|
||
<dd>
|
||
<a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> for media tag serialization and memory cleanup </dd>
|
||
<dd>
|
||
<a class="el" href="group__MediaTags.html#gabdd09c559df8f34ae68fcb2ff1892ebe">MediaTagType</a> enumeration for valid type identifier values and meanings </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="write_8c_source.html#l01780">1780</a> of file <a class="el" href="write_8c_source.html">write.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#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#l00075">AARUF_STATUS_OK</a>, <a class="el" href="context_8h_source.html#l00120">mediaTagEntry::data</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00122">mediaTagEntry::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00264">aaruformat_context::mediaTags</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, and <a class="el" href="context_8h_source.html#l00121">mediaTagEntry::type</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a4b8cd2bb5fd9e2c670a0a13695c6f9e3" name="a4b8cd2bb5fd9e2c670a0a13695c6f9e3"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a4b8cd2bb5fd9e2c670a0a13695c6f9e3">◆ </a></span>aaruf_write_sector()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_write_sector </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">uint64_t</td> <td class="paramname"><span class="paramname"><em>sector_address</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">bool</td> <td class="paramname"><span class="paramname"><em>negative</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">uint8_t</td> <td class="paramname"><span class="paramname"><em>sector_status</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Writes a sector to the AaruFormat image. </p>
|
||
<p>Writes the given data to the specified sector address in the image, with the given status and length. This function handles buffering data into blocks, automatically closing blocks when necessary (sector size changes or block size limits are reached), and managing the deduplication table (DDT) entries.</p>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
|
||
<tr><td class="paramname">sector_address</td><td>Logical sector address to write. </td></tr>
|
||
<tr><td class="paramname">negative</td><td>Indicates if the sector address is negative. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the data buffer to write. </td></tr>
|
||
<tr><td class="paramname">sector_status</td><td>Status of the sector to write. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Length of the data buffer.</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">AARUF_STATUS_OK</td><td>(0) Successfully wrote the sector data. This is returned when:<ul>
|
||
<li>The sector data is successfully copied to the writing buffer</li>
|
||
<li>The DDT entry is successfully updated for the sector address</li>
|
||
<li>Block management operations complete successfully</li>
|
||
<li>Buffer positions and offsets are properly updated</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-22) Attempting to write to a read-only image. This occurs when:<ul>
|
||
<li>The context's isWriting flag is false</li>
|
||
<li>The image was opened in read-only mode</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. This occurs when:<ul>
|
||
<li>Failed to allocate memory for the writing buffer when creating a new block</li>
|
||
<li>The system is out of available memory for buffer allocation</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_WRITE_BLOCK_HEADER</td><td>(-23) Failed to write block header to the image file. This can occur during automatic block closure when:<ul>
|
||
<li>The fwrite() call for the block header fails</li>
|
||
<li>Disk space is insufficient or file system errors occur</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_WRITE_BLOCK_DATA</td><td>(-24) Failed to write block data to the image file. This can occur during automatic block closure when:<ul>
|
||
<li>The fwrite() call for the block data fails</li>
|
||
<li>Disk space is insufficient or file system errors occur</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_SET_DDT_ENTRY</td><td>(-25) Failed to update the deduplication table (DDT) entry. This occurs when:<ul>
|
||
<li>The DDT entry for the specified sector address could not be set or updated</li>
|
||
<li>Internal DDT management functions return failure</li>
|
||
<li>DDT table corruption or memory issues prevent entry updates</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Block Management:<ul>
|
||
<li>The function automatically closes the current block when sector size changes</li>
|
||
<li>Blocks are also closed when they reach the maximum size (determined by dataShift)</li>
|
||
<li>New blocks are created automatically when needed with appropriate headers</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Memory Management:<ul>
|
||
<li>Writing buffers are allocated on-demand when creating new blocks</li>
|
||
<li>Buffer memory is freed when blocks are closed</li>
|
||
<li>Buffer size is calculated based on sector size and data shift parameters</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
DDT Updates:<ul>
|
||
<li>Each written sector updates the corresponding DDT entry</li>
|
||
<li>DDT entries track block offset, position, and sector status</li>
|
||
<li>Uses DDT version 2 format for entries</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>The function may trigger automatic block closure, which can result in disk I/O operations and potential write errors even for seemingly simple sector writes. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="write_8c_source.html#l00098">98</a> of file <a class="el" href="write_8c_source.html">write.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="write_8c_source.html#l01383">aaruf_close_current_block()</a>, <a class="el" href="errors_8h_source.html#l00064">AARUF_ERROR_CANNOT_SET_DDT_ENTRY</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#l00044">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</a>, <a class="el" href="md5_8c_source.html#l00436">aaruf_md5_update()</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</a>, <a class="el" href="sha1_8c_source.html#l00089">aaruf_sha1_update()</a>, <a class="el" href="sha256_8c_source.html#l00090">aaruf_sha256_update()</a>, <a class="el" href="spamsum_8c_source.html#l00059">aaruf_spamsum_update()</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="enums_8h_source.html#l00195">Audio</a>, <a class="el" href="context_8h_source.html#l00268">aaruformat_context::blake3_context</a>, <a class="el" href="context_8h_source.html#l00277">aaruformat_context::calculating_blake3</a>, <a class="el" href="context_8h_source.html#l00273">aaruformat_context::calculating_md5</a>, <a class="el" href="context_8h_source.html#l00274">aaruformat_context::calculating_sha1</a>, <a class="el" href="context_8h_source.html#l00275">aaruformat_context::calculating_sha256</a>, <a class="el" href="context_8h_source.html#l00276">aaruformat_context::calculating_spamsum</a>, <a class="el" href="data_8h_source.html#l00074">BlockHeader::compression</a>, <a class="el" href="context_8h_source.html#l00299">aaruformat_context::compression_enabled</a>, <a class="el" href="context_8h_source.html#l00281">aaruformat_context::current_block_header</a>, <a class="el" href="context_8h_source.html#l00288">aaruformat_context::current_block_offset</a>, <a class="el" href="context_8h_source.html#l00290">aaruformat_context::current_track_type</a>, <a class="el" href="enums_8h_source.html#l00196">Data</a>, <a class="el" href="enums_8h_source.html#l00141">DataBlock</a>, <a class="el" href="ddt_8h_source.html#l00155">DdtHeader2::dataShift</a>, <a class="el" href="context_8h_source.html#l00298">aaruformat_context::deduplicate</a>, <a class="el" href="optical_8h_source.html#l00076">TrackEntry::end</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="enums_8h_source.html#l00035">Flac</a>, <a class="el" href="data_8h_source.html#l00072">BlockHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="hash__map_8c_source.html#l00153">insert_map()</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="aaru_8h_source.html#l00232">JaguarCD</a>, <a class="el" href="context_8h_source.html#l00283">aaruformat_context::last_written_block</a>, <a class="el" href="hash__map_8c_source.html#l00196">lookup_map()</a>, <a class="el" href="enums_8h_source.html#l00034">Lzma</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00270">aaruformat_context::md5_context</a>, <a class="el" href="aaru_8h_source.html#l00881">ImageInfo::MediaType</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="context_8h_source.html#l00282">aaruformat_context::next_block_position</a>, <a class="el" href="enums_8h_source.html#l00033">None</a>, <a class="el" href="enums_8h_source.html#l00218">OpticalDisc</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="context_8h_source.html#l00293">aaruformat_context::rewinded</a>, <a class="el" href="context_8h_source.html#l00253">aaruformat_context::sector_hash_map</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="data_8h_source.html#l00075">BlockHeader::sectorSize</a>, <a class="el" href="optical_8h_source.html#l00073">TrackEntry::sequence</a>, <a class="el" href="optical_8h_source.html#l00078">TrackEntry::session</a>, <a class="el" href="ddt__v2_8c_source.html#l00988">set_ddt_entry_v2()</a>, <a class="el" href="context_8h_source.html#l00271">aaruformat_context::sha1_context</a>, <a class="el" href="context_8h_source.html#l00272">aaruformat_context::sha256_context</a>, <a class="el" href="context_8h_source.html#l00267">aaruformat_context::spamsum_context</a>, <a class="el" href="optical_8h_source.html#l00075">TrackEntry::start</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="context_8h_source.html#l00242">aaruformat_context::track_entries</a>, <a class="el" href="context_8h_source.html#l00244">aaruformat_context::tracks_header</a>, <a class="el" href="data_8h_source.html#l00073">BlockHeader::type</a>, <a class="el" href="optical_8h_source.html#l00074">TrackEntry::type</a>, <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>, <a class="el" href="enums_8h_source.html#l00046">UserData</a>, <a class="el" href="aaru_8h_source.html#l00771">VideoNow</a>, <a class="el" href="aaru_8h_source.html#l00772">VideoNowColor</a>, <a class="el" href="aaru_8h_source.html#l00773">VideoNowXp</a>, <a class="el" href="context_8h_source.html#l00280">aaruformat_context::writing_buffer</a>, <a class="el" href="context_8h_source.html#l00289">aaruformat_context::writing_buffer_position</a>, and <a class="el" href="context_8h_source.html#l00294">aaruformat_context::writing_long</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l00532">aaruf_write_sector_long()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a69ca66242c0becf7640b3d1cc8da8f9c" name="a69ca66242c0becf7640b3d1cc8da8f9c"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a69ca66242c0becf7640b3d1cc8da8f9c">◆ </a></span>aaruf_write_sector_long()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_write_sector_long </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">uint64_t</td> <td class="paramname"><span class="paramname"><em>sector_address</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">bool</td> <td class="paramname"><span class="paramname"><em>negative</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">uint8_t</td> <td class="paramname"><span class="paramname"><em>sector_status</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint32_t</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Writes a full ("long") raw sector from optical or block media, parsing structure and validating content. </p>
|
||
<p>This function processes complete raw sectors including structural metadata, error correction codes, and subchannel information. It is the primary entry point for ingesting raw sector data where the caller provides the complete sector including synchronization patterns, headers, user data, and error correction information. The function intelligently parses the sector structure based on media type and track information, validates correctness, and delegates user data writing to <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>.</p>
|
||
<p>Supported Media Types and Sector Formats:</p>
|
||
<p><b>Optical Disc Media (2352-byte sectors):</b></p><ul>
|
||
<li><b>Audio tracks</b>: Raw PCM audio data (2352 bytes) passed directly to <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a></li>
|
||
<li><b>Data tracks</b>: Raw data sectors passed directly to <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a></li>
|
||
<li><b>CD Mode 1</b>: Sync(12) + Header(4) + <a class="el" href="enums_8h.html#ad8ed01ff3ff33333d8e19db4d2818bb6a73bb26133ccd01972725933b00ec3a06" title="User (main) data.">UserData(2048)</a> + EDC(4) + Reserved(8) + ECC_P(172) + ECC_Q(104)<ul>
|
||
<li>Validates sync pattern (00 FF FF FF FF FF FF FF FF FF FF 00), mode byte (01), and MSF timing</li>
|
||
<li>Checks EDC/ECC correctness using <a class="el" href="#afbc09e16b1a654de04706e07c3212ecb" title="Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 1).">aaruf_ecc_cd_is_suffix_correct()</a></li>
|
||
<li>Stores anomalous prefixes/suffixes in separate buffers with mini-DDT indexing</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>CD Mode 2 Form 1</b>: Sync(12) + Header(4) + Subheader(8) + <a class="el" href="enums_8h.html#ad8ed01ff3ff33333d8e19db4d2818bb6a73bb26133ccd01972725933b00ec3a06" title="User (main) data.">UserData(2048)</a> + EDC(4) + ECC_P(172) + ECC_Q(104)<ul>
|
||
<li>Validates sync pattern, mode byte (02), and Form 1 identification in subheader</li>
|
||
<li>Checks both EDC and ECC correctness for Form 1 sectors</li>
|
||
<li>Extracts and stores 8-byte subheader separately in mode2_subheaders buffer</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>CD Mode 2 Form 2</b>: Sync(12) + Header(4) + Subheader(8) + <a class="el" href="enums_8h.html#ad8ed01ff3ff33333d8e19db4d2818bb6a73bb26133ccd01972725933b00ec3a06" title="User (main) data.">UserData(2324)</a> + EDC(4)<ul>
|
||
<li>Validates sync pattern, mode byte (02), and Form 2 identification in subheader</li>
|
||
<li>Checks EDC correctness, handles missing EDC (zero) as valid state</li>
|
||
<li>No ECC validation for Form 2 sectors (not present in format)</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>CD Mode 2 Formless</b>: Similar to Form 2 but without form determination from subheader</li>
|
||
</ul>
|
||
<p><b>Block Media (512+ byte sectors with tags):</b></p><ul>
|
||
<li><b>Apple Profile/FileWare</b>: 512-byte sectors + 20-byte Profile tags</li>
|
||
<li><b>Apple Sony SS/DS</b>: 512-byte sectors + 12-byte Sony tags</li>
|
||
<li><b>Apple Widget</b>: 512-byte sectors with tag conversion support</li>
|
||
<li><b>Priam DataTower</b>: 512-byte sectors + 24-byte Priam tags</li>
|
||
<li>Supports automatic tag format conversion between Sony (12), Profile (20), and Priam (24) byte formats</li>
|
||
<li>Tag data stored in sector_subchannel buffer for preservation</li>
|
||
</ul>
|
||
<p><b>Data Processing Pipeline:</b></p><ol type="1">
|
||
<li><b>Context and Parameter Validation</b>: Verifies context magic, write permissions, and sector bounds</li>
|
||
<li><b>Track Resolution</b>: Locates track entry covering the sector address to determine track type</li>
|
||
<li><b>Rewind Detection</b>: Detects out-of-order writing and disables hash calculations to maintain integrity</li>
|
||
<li><b>Hash Updates</b>: Updates MD5, SHA1, SHA256, SpamSum, and BLAKE3 contexts for user-range sectors</li>
|
||
<li><b>Structure Parsing</b>: Splits raw sector into prefix, user data, and suffix components</li>
|
||
<li><b>Validation</b>: Checks sync patterns, timing fields, EDC/ECC correctness, and format compliance</li>
|
||
<li><b>Metadata Storage</b>: Stores anomalous or non-standard components in dedicated buffers</li>
|
||
<li><b>User Data Delegation</b>: Calls <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> with extracted user data and derived status</li>
|
||
</ol>
|
||
<p><b>Memory Management Strategy:</b></p><ul>
|
||
<li><b>DDT Arrays</b>: Lazily allocated 64-bit arrays sized for total addressable space (negative + user + overflow)<ul>
|
||
<li>sectorPrefixDdt2: Tracks prefix status and buffer offsets (high 4 bits = status, low 60 bits = offset/16)</li>
|
||
<li>sectorSuffixDdt2: Tracks suffix status and buffer offsets (high 4 bits = status, low 60 bits = offset/288)</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>Prefix Buffer</b>: Dynamically growing buffer storing non-standard 16-byte CD prefixes</li>
|
||
<li><b>Suffix Buffer</b>: Dynamically growing buffer storing non-standard CD suffixes (288 bytes for Mode 1, 4 bytes for Mode 2 Form 2, 280 bytes for Mode 2 Form 1)</li>
|
||
<li><b>Subheader Buffer</b>: Fixed-size buffer (8 bytes per sector) for Mode 2 subheaders</li>
|
||
<li><b>Subchannel Buffer</b>: Fixed-size buffer for block media tag data</li>
|
||
<li>All buffers use doubling reallocation strategy when capacity exceeded</li>
|
||
</ul>
|
||
<p><b>Address Space Management:</b> The function handles three logical address regions:</p><ul>
|
||
<li><b>Negative Region</b>: Pre-gap sectors (sector_address < negative region size, negative=true)</li>
|
||
<li><b>User Region</b>: Main data sectors (0 ≤ sector_address < Sectors, negative=false)</li>
|
||
<li><b>Overflow Region</b>: Post-data sectors (sector_address ≥ Sectors, negative=false) Internal corrected_sector_address provides linear indexing: corrected = address ± negative_size</li>
|
||
</ul>
|
||
<p><b>Sector Status Classification:</b> Status codes stored in high nibble of mini-DDT entries:</p><ul>
|
||
<li><b>SectorStatusMode1Correct</b>: Valid Mode 1 sector with correct sync, timing, EDC, and ECC</li>
|
||
<li><b>SectorStatusMode2Form1Ok</b>: Valid Mode 2 Form 1 with correct subheader, EDC, and ECC</li>
|
||
<li><b>SectorStatusMode2Form2Ok</b>: Valid Mode 2 Form 2 with correct subheader and EDC</li>
|
||
<li><b>SectorStatusMode2Form2NoCrc</b>: Mode 2 Form 2 with zero EDC (acceptable state)</li>
|
||
<li><b>SectorStatusErrored</b>: Sector with validation errors, anomalous data stored in buffers</li>
|
||
<li><b>SectorStatusNotDumped</b>: All-zero sectors treated as not dumped</li>
|
||
</ul>
|
||
<p><b>Deduplication Integration:</b> Long sector processing does not directly perform deduplication - this occurs in the delegated <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> call for the extracted user data portion. The prefix/suffix/subheader metadata is stored separately and not subject to deduplication.</p>
|
||
<p><b>Hash Calculation Behavior:</b></p><ul>
|
||
<li>Hashes computed on complete raw sector data (all 2352 bytes for optical, full tag+data for block)</li>
|
||
<li>Only performed for sectors in user address range (not negative or overflow regions)</li>
|
||
<li>Permanently disabled upon rewind detection to prevent corrupted streaming digests</li>
|
||
<li>Supports MD5, SHA1, SHA256, SpamSum, and BLAKE3 simultaneously when enabled</li>
|
||
</ul>
|
||
<p><b>Error Recovery and Validation:</b></p><ul>
|
||
<li>Sync pattern validation for optical sectors (CD standard 12-byte sync)</li>
|
||
<li>MSF timing validation (Minutes:Seconds:Frames converted to LBA must match sector_address)</li>
|
||
<li>Mode byte validation (01 for Mode 1, 02 for Mode 2)</li>
|
||
<li>EDC validation using <a class="el" href="#a67c65c3f2ca5cdf1596c16fa35558df1" title="Computes the EDC (Error Detection Code) for a CD sector.">aaruf_edc_cd_compute()</a> for computed vs stored comparison</li>
|
||
<li>ECC validation using <a class="el" href="#afbc09e16b1a654de04706e07c3212ecb" title="Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 1).">aaruf_ecc_cd_is_suffix_correct()</a> and <a class="el" href="#ab77ca170a2e8d2f0a2a7ea1a8a51690a" title="Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 2).">aaruf_ecc_cd_is_suffix_correct_mode2()</a></li>
|
||
<li>Form determination from subheader flags (bit 5 of bytes 18 and 22)</li>
|
||
<li>Tag format validation and conversion for block media</li>
|
||
</ul>
|
||
<p><b>Thread Safety and Concurrency:</b> This function is NOT thread-safe. The context contains mutable shared state including:</p><ul>
|
||
<li>Buffer pointers and offsets</li>
|
||
<li>Hash computation contexts</li>
|
||
<li>Rewind detection state</li>
|
||
<li>DDT modification operations External synchronization required for concurrent access.</li>
|
||
</ul>
|
||
<p><b>Performance Considerations:</b></p><ul>
|
||
<li>Buffer allocation occurs lazily on first use</li>
|
||
<li>Buffer growth uses doubling strategy to amortize allocation cost</li>
|
||
<li>Validation operations are optimized for common cases (correct sectors)</li>
|
||
<li>Memory copying minimized for standard compliant sectors</li>
|
||
<li>Hash updates operate on full sector to maintain streaming performance</li>
|
||
</ul>
|
||
<dl class="params"><dt>Parameters</dt><dd>
|
||
<table class="params">
|
||
<tr><td class="paramname">context</td><td>Pointer to a valid aaruformatContext with magic == AARU_MAGIC opened for writing. </td></tr>
|
||
<tr><td class="paramname">sector_address</td><td>Logical Block Address (LBA) for the sector. For negative regions, this is the negative-space address; for user/overflow regions, this is the standard 0-based LBA. </td></tr>
|
||
<tr><td class="paramname">negative</td><td>true if sector_address refers to the negative (pre-gap) region; false for user or overflow regions. </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the complete raw sector buffer. Must contain:<ul>
|
||
<li>For optical: exactly 2352 bytes of raw sector data</li>
|
||
<li>For block media: 512 bytes + tag data (12, 20, or 24 bytes depending on format) </li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">sector_status</td><td>Initial sector status hint from caller. May be overridden based on validation results when delegating to <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Length in bytes of the data buffer. Must be exactly 2352 for optical discs. For block media: 512 (no tags), 524 (Sony), 532 (Profile), or 536 (Priam).</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">AARUF_STATUS_OK</td><td>(0) Sector successfully processed and user data written. This occurs when:<ul>
|
||
<li>Raw sector structure parsed and validated successfully</li>
|
||
<li>Prefix/suffix/subheader metadata stored appropriately</li>
|
||
<li>User data portion successfully delegated to <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a></li>
|
||
<li>All buffer allocations and DDT updates completed successfully</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context provided. This occurs when:<ul>
|
||
<li>context parameter is NULL</li>
|
||
<li>Context magic number != AARU_MAGIC (wrong context type or corruption)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-22) Attempting to write to read-only image. This occurs when:<ul>
|
||
<li>Context isWriting flag is false</li>
|
||
<li>Image was opened without write permissions</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</td><td>(-7) Sector address outside valid ranges. This occurs when:<ul>
|
||
<li>negative=true and sector_address >= negative region size</li>
|
||
<li>negative=false and sector_address >= (Sectors + overflow region size)</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_DATA_SIZE</td><td>(-8) Invalid sector size for media type. This occurs when:<ul>
|
||
<li>length != 2352 for optical disc media</li>
|
||
<li>length not in {512, 524, 532, 536} for supported block media types</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. This occurs when:<ul>
|
||
<li>Failed to allocate mini-DDT arrays (sectorPrefixDdt2, sectorSuffixDdt2)</li>
|
||
<li>Failed to allocate or grow prefix buffer (sector_prefix)</li>
|
||
<li>Failed to allocate or grow suffix buffer (sector_suffix)</li>
|
||
<li>Failed to allocate subheader buffer (mode2_subheaders)</li>
|
||
<li>Failed to allocate subchannel buffer (sector_subchannel)</li>
|
||
<li>System out of memory during buffer reallocation</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_MEDIA_TYPE</td><td>(-26) Unsupported media type for long sectors. This occurs when:<ul>
|
||
<li>Media type is not OpticalDisc or supported BlockMedia variant</li>
|
||
<li>Block media type does not support the provided tag format</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_SET_DDT_ENTRY</td><td>(-25) DDT update failed. Propagated from <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> when:<ul>
|
||
<li>User data DDT entry could not be updated</li>
|
||
<li>DDT table corruption prevents entry modification</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_WRITE_BLOCK_HEADER</td><td>(-23) Block header write failed. Propagated from <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> when:<ul>
|
||
<li>Automatic block closure triggered by user data write fails</li>
|
||
<li>File system error prevents header write</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_CANNOT_WRITE_BLOCK_DATA</td><td>(-24) Block data write failed. Propagated from <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> when:<ul>
|
||
<li>User data portion write fails during block flush</li>
|
||
<li>Insufficient disk space or I/O error occurs</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd><b>Cross-References</b>: This function is the primary companion to <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> for raw sector ingestion. See also:<ul>
|
||
<li><a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a>: Handles user data portion writing and deduplication</li>
|
||
<li><a class="el" href="#afbc09e16b1a654de04706e07c3212ecb" title="Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 1).">aaruf_ecc_cd_is_suffix_correct()</a>: CD Mode 1 ECC validation</li>
|
||
<li><a class="el" href="#ab77ca170a2e8d2f0a2a7ea1a8a51690a" title="Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 2).">aaruf_ecc_cd_is_suffix_correct_mode2()</a>: CD Mode 2 Form 1 ECC validation</li>
|
||
<li><a class="el" href="#a67c65c3f2ca5cdf1596c16fa35558df1" title="Computes the EDC (Error Detection Code) for a CD sector.">aaruf_edc_cd_compute()</a>: EDC calculation and validation for all CD modes</li>
|
||
<li><a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>: Serializes prefix/suffix/subheader metadata to image file</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
<b>Buffer Management</b>: All dynamically allocated buffers (prefix, suffix, subheader, subchannel) are automatically freed during <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Applications should not attempt to access these buffers directly or free them manually.</dd>
|
||
<dd>
|
||
<b>Metadata Persistence</b>: Prefix, suffix, and subheader data captured by this function is serialized to the image file during <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> as separate metadata blocks with corresponding mini-DDT tables for efficient access during reading.</dd>
|
||
<dd>
|
||
<b>Tag Format Conversion</b>: For block media, automatic conversion between Sony, Profile, and Priam tag formats ensures compatibility regardless of source format. Conversion preserves all semantic information while adapting to target media type requirements.</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd><b>Rewind Detection</b>: Writing sectors out of strictly increasing order triggers rewind detection, permanently disabling hash calculations for the session. This prevents corrupted streaming digests but means hash values will be unavailable if non-sequential writing occurs. Plan sector writing order carefully if digest calculation is required.</dd>
|
||
<dd>
|
||
<b>Memory Growth</b>: Prefix and suffix buffers grow dynamically and can consume significant memory for images with many non-standard sectors. Monitor memory usage when processing damaged or non-compliant optical media.</dd>
|
||
<dd>
|
||
<b>Media Type Constraints</b>: This function only supports OpticalDisc and specific BlockMedia types. Other media types will return AARUF_ERROR_INCORRECT_MEDIA_TYPE. Use <a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> directly for unsupported media types.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="write_8c.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3" title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> for user data writing and deduplication </dd>
|
||
<dd>
|
||
<a class="el" href="#a719a992be38ee90a5e302725c18a791b" title="Reads a complete sector with all metadata from the AaruFormat image.">aaruf_read_sector_long()</a> for corresponding long sector reading functionality </dd>
|
||
<dd>
|
||
<a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> for metadata serialization and cleanup </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="write_8c_source.html#l00532">532</a> of file <a class="el" href="write_8c_source.html">write.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="ecc__cd_8c_source.html#l00101">aaruf_ecc_cd_is_suffix_correct()</a>, <a class="el" href="ecc__cd_8c_source.html#l00165">aaruf_ecc_cd_is_suffix_correct_mode2()</a>, <a class="el" href="ecc__cd_8c_source.html#l00543">aaruf_edc_cd_compute()</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00051">AARUF_ERROR_INCORRECT_MEDIA_TYPE</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#l00044">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</a>, <a class="el" href="md5_8c_source.html#l00436">aaruf_md5_update()</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</a>, <a class="el" href="sha1_8c_source.html#l00089">aaruf_sha1_update()</a>, <a class="el" href="sha256_8c_source.html#l00090">aaruf_sha256_update()</a>, <a class="el" href="spamsum_8c_source.html#l00059">aaruf_spamsum_update()</a>, <a class="el" href="write_8c_source.html#l00098">aaruf_write_sector()</a>, <a class="el" href="aaru_8h_source.html#l00249">AppleFileWare</a>, <a class="el" href="aaru_8h_source.html#l00698">AppleProfile</a>, <a class="el" href="aaru_8h_source.html#l00248">AppleSonyDS</a>, <a class="el" href="aaru_8h_source.html#l00247">AppleSonySS</a>, <a class="el" href="aaru_8h_source.html#l00699">AppleWidget</a>, <a class="el" href="enums_8h_source.html#l00195">Audio</a>, <a class="el" href="context_8h_source.html#l00268">aaruformat_context::blake3_context</a>, <a class="el" href="enums_8h_source.html#l00219">BlockMedia</a>, <a class="el" href="lisa__tag_8c_source.html#l00112">bytes_to_priam_tag()</a>, <a class="el" href="lisa__tag_8c_source.html#l00142">bytes_to_profile_tag()</a>, <a class="el" href="lisa__tag_8c_source.html#l00082">bytes_to_sony_tag()</a>, <a class="el" href="context_8h_source.html#l00277">aaruformat_context::calculating_blake3</a>, <a class="el" href="context_8h_source.html#l00273">aaruformat_context::calculating_md5</a>, <a class="el" href="context_8h_source.html#l00274">aaruformat_context::calculating_sha1</a>, <a class="el" href="context_8h_source.html#l00275">aaruformat_context::calculating_sha256</a>, <a class="el" href="context_8h_source.html#l00276">aaruformat_context::calculating_spamsum</a>, <a class="el" href="enums_8h_source.html#l00197">CdMode1</a>, <a class="el" href="enums_8h_source.html#l00199">CdMode2Form1</a>, <a class="el" href="enums_8h_source.html#l00200">CdMode2Form2</a>, <a class="el" href="enums_8h_source.html#l00198">CdMode2Formless</a>, <a class="el" href="enums_8h_source.html#l00196">Data</a>, <a class="el" href="aaru_8h_source.html#l00146">DVDDownload</a>, <a class="el" href="aaru_8h_source.html#l00139">DVDPR</a>, <a class="el" href="aaru_8h_source.html#l00143">DVDPRDL</a>, <a class="el" href="aaru_8h_source.html#l00140">DVDPRW</a>, <a class="el" href="aaru_8h_source.html#l00141">DVDPRWDL</a>, <a class="el" href="aaru_8h_source.html#l00137">DVDR</a>, <a class="el" href="aaru_8h_source.html#l00144">DVDRAM</a>, <a class="el" href="aaru_8h_source.html#l00142">DVDRDL</a>, <a class="el" href="aaru_8h_source.html#l00136">DVDROM</a>, <a class="el" href="aaru_8h_source.html#l00138">DVDRW</a>, <a class="el" href="aaru_8h_source.html#l00145">DVDRWDL</a>, <a class="el" href="context_8h_source.html#l00248">aaruformat_context::ecc_cd_context</a>, <a class="el" href="optical_8h_source.html#l00076">TrackEntry::end</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="context_8h_source.html#l00283">aaruformat_context::last_written_block</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00270">aaruformat_context::md5_context</a>, <a class="el" href="aaru_8h_source.html#l00881">ImageInfo::MediaType</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="context_8h_source.html#l00204">aaruformat_context::mode2_subheaders</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="aaru_8h_source.html#l00238">Nuon</a>, <a class="el" href="enums_8h_source.html#l00218">OpticalDisc</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="lisa__tag_8c_source.html#l00409">priam_tag_to_bytes()</a>, <a class="el" href="lisa__tag_8c_source.html#l00325">priam_tag_to_profile()</a>, <a class="el" href="lisa__tag_8c_source.html#l00291">priam_tag_to_sony()</a>, <a class="el" href="aaru_8h_source.html#l00701">PriamDataTower</a>, <a class="el" href="lisa__tag_8c_source.html#l00357">profile_tag_to_bytes()</a>, <a class="el" href="lisa__tag_8c_source.html#l00228">profile_tag_to_priam()</a>, <a class="el" href="lisa__tag_8c_source.html#l00257">profile_tag_to_sony()</a>, <a class="el" href="aaru_8h_source.html#l00205">PS2DVD</a>, <a class="el" href="aaru_8h_source.html#l00206">PS3DVD</a>, <a class="el" href="context_8h_source.html#l00293">aaruformat_context::rewinded</a>, <a class="el" href="aaru_8h_source.html#l00121">SACD</a>, <a class="el" href="context_8h_source.html#l00207">aaruformat_context::sector_cpr_mai</a>, <a class="el" href="context_8h_source.html#l00208">aaruformat_context::sector_edc</a>, <a class="el" href="context_8h_source.html#l00205">aaruformat_context::sector_id</a>, <a class="el" href="context_8h_source.html#l00206">aaruformat_context::sector_ied</a>, <a class="el" href="context_8h_source.html#l00199">aaruformat_context::sector_prefix</a>, <a class="el" href="context_8h_source.html#l00185">aaruformat_context::sector_prefix_ddt2</a>, <a class="el" href="context_8h_source.html#l00284">aaruformat_context::sector_prefix_length</a>, <a class="el" href="context_8h_source.html#l00286">aaruformat_context::sector_prefix_offset</a>, <a class="el" href="context_8h_source.html#l00203">aaruformat_context::sector_subchannel</a>, <a class="el" href="context_8h_source.html#l00201">aaruformat_context::sector_suffix</a>, <a class="el" href="context_8h_source.html#l00186">aaruformat_context::sector_suffix_ddt2</a>, <a class="el" href="context_8h_source.html#l00285">aaruformat_context::sector_suffix_length</a>, <a class="el" href="context_8h_source.html#l00287">aaruformat_context::sector_suffix_offset</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="enums_8h_source.html#l00232">SectorStatusErrored</a>, <a class="el" href="enums_8h_source.html#l00233">SectorStatusMode1Correct</a>, <a class="el" href="enums_8h_source.html#l00234">SectorStatusMode2Form1Ok</a>, <a class="el" href="enums_8h_source.html#l00236">SectorStatusMode2Form2NoCrc</a>, <a class="el" href="enums_8h_source.html#l00235">SectorStatusMode2Form2Ok</a>, <a class="el" href="enums_8h_source.html#l00230">SectorStatusNotDumped</a>, <a class="el" href="optical_8h_source.html#l00073">TrackEntry::sequence</a>, <a class="el" href="context_8h_source.html#l00271">aaruformat_context::sha1_context</a>, <a class="el" href="context_8h_source.html#l00272">aaruformat_context::sha256_context</a>, <a class="el" href="lisa__tag_8c_source.html#l00466">sony_tag_to_bytes()</a>, <a class="el" href="lisa__tag_8c_source.html#l00201">sony_tag_to_priam()</a>, <a class="el" href="lisa__tag_8c_source.html#l00173">sony_tag_to_profile()</a>, <a class="el" href="context_8h_source.html#l00267">aaruformat_context::spamsum_context</a>, <a class="el" href="optical_8h_source.html#l00075">TrackEntry::start</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="context_8h_source.html#l00242">aaruformat_context::track_entries</a>, <a class="el" href="context_8h_source.html#l00244">aaruformat_context::tracks_header</a>, <a class="el" href="optical_8h_source.html#l00074">TrackEntry::type</a>, <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>, and <a class="el" href="context_8h_source.html#l00294">aaruformat_context::writing_long</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a6a8994cd006711347fb03cec465eafa6" name="a6a8994cd006711347fb03cec465eafa6"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a6a8994cd006711347fb03cec465eafa6">◆ </a></span>aaruf_write_sector_tag()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">int32_t aaruf_write_sector_tag </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 uint64_t</td> <td class="paramname"><span class="paramname"><em>sector_address</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">const bool</td> <td class="paramname"><span class="paramname"><em>negative</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 size_t</td> <td class="paramname"><span class="paramname"><em>length</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>tag</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p>Writes per-sector tag data (auxiliary metadata) for a specific sector. </p>
|
||
<p>This function stores auxiliary metadata associated with individual sectors, such as CD subchannel data, DVD auxiliary fields, track metadata, or proprietary tag formats used by specific storage systems. Unlike media tags (which apply to the entire medium), sector tags are per-sector metadata that provide additional context, error correction, copy protection, or device-specific information for each individual sector.</p>
|
||
<p>The function validates the tag type against the media type, verifies the data size matches the expected length for that tag type, allocates buffers as needed, and stores the tag data at the appropriate offset within the tag buffer. Some tags (like track flags and ISRC) update track metadata rather than per-sector buffers.</p>
|
||
<p><b>Supported tag types and their characteristics:</b></p>
|
||
<p><b>Optical Disc (CD/DVD) Tags:</b></p><ul>
|
||
<li><b>CdTrackFlags</b> (1 byte): Track control flags for CD tracks<ul>
|
||
<li>Updates track metadata in ctx->trackEntries for the track containing the sector</li>
|
||
<li>Includes flags like copy permitted, data track, four-channel audio, etc.</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>CdTrackIsrc</b> (12 bytes): International Standard Recording Code for CD tracks<ul>
|
||
<li>Updates track metadata in ctx->trackEntries for the track containing the sector</li>
|
||
<li>Identifies the recording for copyright and royalty purposes</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>CdSectorSubchannel</b> (96 bytes): CD subchannel data (P-W subchannels)<ul>
|
||
<li>Stored in ctx->sector_subchannel buffer</li>
|
||
<li>Contains control information, track numbers, timecodes, and CD-TEXT data</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>DvdSectorCprMai</b> (6 bytes): DVD Copyright Management Information<ul>
|
||
<li>Stored in ctx->sector_cpr_mai buffer</li>
|
||
<li>Contains copy protection and media authentication information</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>DvdSectorInformation</b> (1 byte): DVD sector information field<ul>
|
||
<li>Stored in first byte of ctx->sector_id buffer (4 bytes per sector)</li>
|
||
<li>Contains sector type and layer information</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>DvdSectorNumber</b> (3 bytes): DVD sector number field<ul>
|
||
<li>Stored in bytes 1-3 of ctx->sector_id buffer (4 bytes per sector)</li>
|
||
<li>Physical sector address encoded in the sector header</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>DvdSectorIed</b> (2 bytes): DVD ID Error Detection field<ul>
|
||
<li>Stored in ctx->sector_ied buffer</li>
|
||
<li>Error detection code for the sector ID field</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>DvdSectorEdc</b> (4 bytes): DVD Error Detection Code<ul>
|
||
<li>Stored in ctx->sector_edc buffer</li>
|
||
<li>Error detection code for the entire sector</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>DvdDiscKeyDecrypted</b> (5 bytes): Decrypted DVD title key<ul>
|
||
<li>Stored in ctx->sector_decrypted_title_key buffer</li>
|
||
<li>Used for accessing encrypted DVD content</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><b>Block Media (Proprietary Format) Tags:</b></p><ul>
|
||
<li><b>AppleSonyTag</b> (12 bytes): Apple II Sony 3.5" disk tag data<ul>
|
||
<li>Stored in ctx->sector_subchannel buffer</li>
|
||
<li>Contains file system metadata used by Apple II systems</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>AppleProfileTag</b> (20 bytes): Apple ProFile/FileWare hard drive tag data<ul>
|
||
<li>Stored in ctx->sector_subchannel buffer</li>
|
||
<li>Contains file system and bad block metadata</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>PriamDataTowerTag</b> (24 bytes): Priam Data Tower hard drive tag data<ul>
|
||
<li>Stored in ctx->sector_subchannel buffer</li>
|
||
<li>Contains proprietary metadata used by Priam drives</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><b>Sector addressing:</b> The function supports both positive and negative sector addressing:</p><ul>
|
||
<li>Negative sectors: Lead-in area before sector 0 (for optical media)</li>
|
||
<li>Positive sectors: Main data area and lead-out overflow area</li>
|
||
<li>Internal correction adjusts addresses to buffer offsets</li>
|
||
</ul>
|
||
<p><b>Buffer allocation:</b> Tag buffers are allocated on-demand when the first tag of a given type is written. Buffers are sized to accommodate all sectors (negative + normal + overflow) and persist for the lifetime of the context. Memory is freed during <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>.</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">sector_address</td><td>The logical sector number to write the tag for. Must be within valid bounds for the image (0 to Sectors-1 for positive, 0 to negative-1 when using negative addressing). </td></tr>
|
||
<tr><td class="paramname">negative</td><td>If true, sector_address refers to a negative (lead-in) sector; if false, it refers to a positive sector (main data or overflow area). </td></tr>
|
||
<tr><td class="paramname">data</td><td>Pointer to the tag data to write. Must not be NULL. The data size must exactly match the expected size for the tag type. </td></tr>
|
||
<tr><td class="paramname">length</td><td>Length of the tag data in bytes. Must match the required size for the tag type. </td></tr>
|
||
<tr><td class="paramname">tag</td><td>Tag type identifier (from the tag enumeration). Determines which buffer to write to and the expected 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">AARUF_STATUS_OK</td><td>(0) Successfully wrote sector tag. This is returned when:<ul>
|
||
<li>The context is valid and properly initialized</li>
|
||
<li>The context is opened in write mode (ctx->isWriting is true)</li>
|
||
<li>The sector address is within valid bounds</li>
|
||
<li>The tag type is supported and appropriate for the media type</li>
|
||
<li>The data length matches the required size for the tag type</li>
|
||
<li>Memory allocation succeeded (if buffer needed to be created)</li>
|
||
<li>Tag data was copied to the appropriate buffer or track metadata updated</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
|
||
<li>The context parameter is NULL</li>
|
||
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
|
||
<li>The context was not properly initialized by <a class="el" href="#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
|
||
<li>The image was opened with <a class="el" href="#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="#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">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</td><td>(-4) Sector address is invalid. This occurs when:<ul>
|
||
<li>negative is true and sector_address > negative-1</li>
|
||
<li>negative is false and sector_address > Sectors+overflow-1</li>
|
||
<li>Attempting to write beyond the image boundaries</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_DATA_SIZE</td><td>(-11) Invalid data or length. This occurs when:<ul>
|
||
<li>The data parameter is NULL</li>
|
||
<li>The length parameter is 0</li>
|
||
<li>The length doesn't match the required size for the tag type</li>
|
||
<li>Tag size validation failed</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INCORRECT_MEDIA_TYPE</td><td>(-26) Invalid media type for tag. This occurs when:<ul>
|
||
<li>Attempting to write optical disc tags (CD/DVD) to block media</li>
|
||
<li>Attempting to write block media tags to optical disc</li>
|
||
<li>Tag type is incompatible with ctx->imageInfo.XmlMediaType</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) Memory allocation failed. This occurs when:<ul>
|
||
<li>calloc() failed to allocate buffer for tag data</li>
|
||
<li>System is out of memory or memory is severely fragmented</li>
|
||
<li>Buffer allocation is required but cannot be satisfied</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_TRACK_NOT_FOUND</td><td>(-25) Track not found for sector. This occurs when:<ul>
|
||
<li>Writing CdTrackFlags or CdTrackIsrc tags</li>
|
||
<li>The specified sector is not contained within any defined track</li>
|
||
<li>Track metadata has not been initialized</li>
|
||
</ul>
|
||
</td></tr>
|
||
<tr><td class="paramname">AARUF_ERROR_INVALID_TAG</td><td>(-27) Unsupported or unknown tag type. This occurs when:<ul>
|
||
<li>The tag parameter doesn't match any known tag type</li>
|
||
<li>The tag type is not implemented</li>
|
||
<li>Invalid tag identifier provided</li>
|
||
</ul>
|
||
</td></tr>
|
||
</table>
|
||
</dd>
|
||
</dl>
|
||
<dl class="section note"><dt>Note</dt><dd>Tag Data Persistence:<ul>
|
||
<li>Tag data is stored in memory until <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> is called</li>
|
||
<li>Tags are written as separate data blocks during image finalization</li>
|
||
<li>CD subchannel and DVD auxiliary fields are written by dedicated block writers</li>
|
||
<li>Track metadata (flags, ISRC) is written as part of the tracks block</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Buffer Reuse:<ul>
|
||
<li>Some tag types share the same buffer (ctx->sector_subchannel)</li>
|
||
<li>CD subchannel uses 96 bytes per sector</li>
|
||
<li>Apple Sony tag uses 12 bytes per sector</li>
|
||
<li>Apple Profile tag uses 20 bytes per sector</li>
|
||
<li>Priam Data Tower tag uses 24 bytes per sector</li>
|
||
<li>Ensure consistent tag type usage within a single image</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
DVD Sector ID Split:<ul>
|
||
<li>DVD sector ID is 4 bytes but written as two separate tags</li>
|
||
<li>DvdSectorInformation writes byte 0 (sector info)</li>
|
||
<li>DvdSectorNumber writes bytes 1-3 (sector number)</li>
|
||
<li>Both tags share ctx->sector_id buffer</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Tag Size Validation:<ul>
|
||
<li>Each tag type has a fixed expected size</li>
|
||
<li>Size mismatches are rejected with AARUF_ERROR_INCORRECT_DATA_SIZE</li>
|
||
<li>This prevents partial writes and buffer corruption</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Media Type Validation:<ul>
|
||
<li>Optical disc tags require <a class="el" href="enums_8h.html#abaa37b51ab0a4cc3d5d1a0b4820c8466" title="Enumeration of media types defined in CICM metadata.">XmlMediaType</a> == OpticalDisc</li>
|
||
<li>Block media tags require <a class="el" href="enums_8h.html#abaa37b51ab0a4cc3d5d1a0b4820c8466" title="Enumeration of media types defined in CICM metadata.">XmlMediaType</a> == BlockMedia</li>
|
||
<li>This prevents incompatible tag types from being written</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
Multiple Writes to Same Sector:<ul>
|
||
<li>Writing the same tag type to the same sector multiple times replaces the previous value</li>
|
||
<li>No warning or error is generated for overwrites</li>
|
||
<li>Last write wins</li>
|
||
</ul>
|
||
</dd></dl>
|
||
<dl class="section warning"><dt>Warning</dt><dd>Tag data is not immediately written to disk. All tag data is buffered in memory and written during <a class="el" href="#a6823e139f81a9dfd08efcb0e9b213a49" title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Ensure sufficient memory is available for large images with extensive tag data.</dd>
|
||
<dd>
|
||
Mixing incompatible tag types that share buffers (e.g., CD subchannel and Apple tags) will cause data corruption. Only use tag types appropriate for your media format.</dd>
|
||
<dd>
|
||
For track-based tags (CdTrackFlags, CdTrackIsrc), tracks must be defined before writing tags. Call <a class="el" href="#a518d8d68debf1b9a24af3eb6bc2f9e49" title="Replace (or clear) the in-memory track table for an AaruFormat image context.">aaruf_set_tracks()</a> to initialize track metadata first.</dd></dl>
|
||
<dl class="section see"><dt>See also</dt><dd><a class="el" href="write_8c.html#a35c5d9f10c59a1efe8f625963c9e91ba" title="Writes a media tag to the AaruFormat image, storing medium-specific metadata and descriptors.">aaruf_write_media_tag()</a> for writing whole-medium tags. </dd>
|
||
<dd>
|
||
<a class="el" href="write_8c.html#a69ca66242c0becf7640b3d1cc8da8f9c" title="Writes a full ("long") raw sector from optical or block media, parsing structure and validating conte...">aaruf_write_sector_long()</a> for writing sectors with embedded tag data. </dd>
|
||
<dd>
|
||
<a class="el" href="close_8c.html#ae0a4b670cbb5359edd44751e1b76ca9c" title="Serialize the per-sector subchannel or tag data block.">write_sector_subchannel()</a> for the serialization of <a class="el" href="group__MediaTypes.html#gga1499e9f8a76cb81b43b7a4b0dbe7e44aa9aea9e501fa935b114b235e8e9754267" title="Any unknown or standard violating CD.">CD</a> subchannel data. </dd>
|
||
<dd>
|
||
<a class="el" href="close_8c.html#a13f6c475294969c1eb8c59ff53c91af9" title="Serialize DVD long sector auxiliary data blocks to the image file.">write_dvd_long_sector_blocks()</a> for the serialization of DVD auxiliary data. </dd></dl>
|
||
|
||
<p class="definition">Definition at line <a class="el" href="write_8c_source.html#l02048">2048</a> of file <a class="el" href="write_8c_source.html">write.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00051">AARUF_ERROR_INCORRECT_MEDIA_TYPE</a>, <a class="el" href="errors_8h_source.html#l00066">AARUF_ERROR_INVALID_TAG</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#l00044">AARUF_ERROR_SECTOR_OUT_OF_BOUNDS</a>, <a class="el" href="errors_8h_source.html#l00052">AARUF_ERROR_TRACK_NOT_FOUND</a>, <a class="el" href="errors_8h_source.html#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="enums_8h_source.html#l00117">AppleProfileTag</a>, <a class="el" href="enums_8h_source.html#l00118">AppleSonyTag</a>, <a class="el" href="enums_8h_source.html#l00219">BlockMedia</a>, <a class="el" href="enums_8h_source.html#l00116">CdSectorSubchannel</a>, <a class="el" href="aaru_8h_source.html#l00907">CdTrackFlags</a>, <a class="el" href="aaru_8h_source.html#l00905">CdTrackIsrc</a>, <a class="el" href="aaru_8h_source.html#l00908">DvdCmi</a>, <a class="el" href="enums_8h_source.html#l00130">DvdSectorEdc</a>, <a class="el" href="enums_8h_source.html#l00129">DvdSectorIed</a>, <a class="el" href="aaru_8h_source.html#l00912">DvdSectorInformation</a>, <a class="el" href="aaru_8h_source.html#l00913">DvdSectorNumber</a>, <a class="el" href="aaru_8h_source.html#l00911">DvdTitleKeyDecrypted</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="optical_8h_source.html#l00080">TrackEntry::flags</a>, <a class="el" href="context_8h_source.html#l00260">aaruformat_context::image_info</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="optical_8h_source.html#l00079">TrackEntry::isrc</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="aaru_8h_source.html#l00882">ImageInfo::MetadataMediaType</a>, <a class="el" href="ddt_8h_source.html#l00149">DdtHeader2::negative</a>, <a class="el" href="enums_8h_source.html#l00218">OpticalDisc</a>, <a class="el" href="ddt_8h_source.html#l00151">DdtHeader2::overflow</a>, <a class="el" href="enums_8h_source.html#l00119">PriamDataTowerTag</a>, <a class="el" href="context_8h_source.html#l00207">aaruformat_context::sector_cpr_mai</a>, <a class="el" href="context_8h_source.html#l00209">aaruformat_context::sector_decrypted_title_key</a>, <a class="el" href="context_8h_source.html#l00208">aaruformat_context::sector_edc</a>, <a class="el" href="context_8h_source.html#l00205">aaruformat_context::sector_id</a>, <a class="el" href="context_8h_source.html#l00206">aaruformat_context::sector_ied</a>, <a class="el" href="context_8h_source.html#l00203">aaruformat_context::sector_subchannel</a>, <a class="el" href="aaru_8h_source.html#l00874">ImageInfo::Sectors</a>, <a class="el" href="optical_8h_source.html#l00075">TrackEntry::start</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="context_8h_source.html#l00242">aaruformat_context::track_entries</a>, <a class="el" href="context_8h_source.html#l00244">aaruformat_context::tracks_header</a>, and <a class="el" href="context_8h_source.html#l00189">aaruformat_context::user_data_ddt_header</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a680150d4b3df13261af758c504a1f848" name="a680150d4b3df13261af758c504a1f848"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a680150d4b3df13261af758c504a1f848">◆ </a></span>fuzzy_engine_step()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="mlabels">
|
||
<tr>
|
||
<td class="mlabels-left">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void fuzzy_engine_step </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t</td> <td class="paramname"><span class="paramname"><em>c</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
<td class="mlabels-right">
|
||
<span class="mlabels"><span class="mlabel inline">inline</span></span> </td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00084">84</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00055">AARU_LOCAL</a>, <a class="el" href="spamsum_8c_source.html#l00032">b64</a>, <a class="el" href="spamsum_8h_source.html#l00054">spamsum_ctx::bh</a>, <a class="el" href="spamsum_8h_source.html#l00052">spamsum_ctx::bh_start</a>, <a class="el" href="spamsum_8h_source.html#l00038">blockhash_ctx::d_len</a>, <a class="el" href="spamsum_8h_source.html#l00036">blockhash_ctx::digest</a>, <a class="el" href="spamsum_8c_source.html#l00175">fuzzy_try_fork_blockhash()</a>, <a class="el" href="spamsum_8c_source.html#l00155">fuzzy_try_reduce_blockhash()</a>, <a class="el" href="spamsum_8h_source.html#l00034">blockhash_ctx::h</a>, <a class="el" href="spamsum_8h_source.html#l00037">blockhash_ctx::half_digest</a>, <a class="el" href="spamsum_8h_source.html#l00035">blockhash_ctx::half_h</a>, <a class="el" href="spamsum_8h_source.html#l00027">HASH_INIT</a>, <a class="el" href="spamsum_8c_source.html#l00137">roll_hash()</a>, <a class="el" href="spamsum_8c_source.html#l00080">ROLL_SUM</a>, <a class="el" href="spamsum_8h_source.html#l00024">SPAMSUM_LENGTH</a>, <a class="el" href="spamsum_8c_source.html#l00082">SSDEEP_BS</a>, and <a class="el" href="spamsum_8c_source.html#l00081">SUM_HASH</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="spamsum_8c_source.html#l00059">aaruf_spamsum_update()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a24c6d35239a8d1fee6e93aa12bbd5bd6" name="a24c6d35239a8d1fee6e93aa12bbd5bd6"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a24c6d35239a8d1fee6e93aa12bbd5bd6">◆ </a></span>fuzzy_try_fork_blockhash()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="mlabels">
|
||
<tr>
|
||
<td class="mlabels-left">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void fuzzy_try_fork_blockhash </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
<td class="mlabels-right">
|
||
<span class="mlabels"><span class="mlabel inline">inline</span></span> </td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00175">175</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00055">AARU_LOCAL</a>, <a class="el" href="spamsum_8h_source.html#l00054">spamsum_ctx::bh</a>, <a class="el" href="spamsum_8h_source.html#l00053">spamsum_ctx::bh_end</a>, <a class="el" href="spamsum_8h_source.html#l00038">blockhash_ctx::d_len</a>, <a class="el" href="spamsum_8h_source.html#l00036">blockhash_ctx::digest</a>, <a class="el" href="spamsum_8h_source.html#l00034">blockhash_ctx::h</a>, <a class="el" href="spamsum_8h_source.html#l00037">blockhash_ctx::half_digest</a>, <a class="el" href="spamsum_8h_source.html#l00035">blockhash_ctx::half_h</a>, and <a class="el" href="spamsum_8h_source.html#l00025">NUM_BLOCKHASHES</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="spamsum_8c_source.html#l00084">fuzzy_engine_step()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a906ad6bd1809bf999874c848af7c648b" name="a906ad6bd1809bf999874c848af7c648b"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a906ad6bd1809bf999874c848af7c648b">◆ </a></span>fuzzy_try_reduce_blockhash()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="mlabels">
|
||
<tr>
|
||
<td class="mlabels-left">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void fuzzy_try_reduce_blockhash </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
<td class="mlabels-right">
|
||
<span class="mlabels"><span class="mlabel inline">inline</span></span> </td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00155">155</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00055">AARU_LOCAL</a>, <a class="el" href="spamsum_8h_source.html#l00054">spamsum_ctx::bh</a>, <a class="el" href="spamsum_8h_source.html#l00053">spamsum_ctx::bh_end</a>, <a class="el" href="spamsum_8h_source.html#l00052">spamsum_ctx::bh_start</a>, <a class="el" href="spamsum_8h_source.html#l00038">blockhash_ctx::d_len</a>, <a class="el" href="spamsum_8h_source.html#l00024">SPAMSUM_LENGTH</a>, <a class="el" href="spamsum_8c_source.html#l00082">SSDEEP_BS</a>, and <a class="el" href="spamsum_8h_source.html#l00055">spamsum_ctx::total_size</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="spamsum_8c_source.html#l00084">fuzzy_engine_step()</a>.</p>
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a9f287da4a58c0d3ab8f0243de5fe3f8d" name="a9f287da4a58c0d3ab8f0243de5fe3f8d"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a9f287da4a58c0d3ab8f0243de5fe3f8d">◆ </a></span>roll_hash()</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="mlabels">
|
||
<tr>
|
||
<td class="mlabels-left">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">void roll_hash </td>
|
||
<td>(</td>
|
||
<td class="paramtype"><a class="el" href="structspamsum__ctx.html">spamsum_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="paramkey"></td>
|
||
<td></td>
|
||
<td class="paramtype">uint8_t</td> <td class="paramname"><span class="paramname"><em>c</em></span> )</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
<td class="mlabels-right">
|
||
<span class="mlabels"><span class="mlabel inline">inline</span></span> </td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
<p class="definition">Definition at line <a class="el" href="spamsum_8c_source.html#l00137">137</a> of file <a class="el" href="spamsum_8c_source.html">spamsum.c</a>.</p>
|
||
|
||
<p class="reference">References <a class="el" href="decls_8h_source.html#l00055">AARU_LOCAL</a>, <a class="el" href="spamsum_8h_source.html#l00044">roll_state::h1</a>, <a class="el" href="spamsum_8h_source.html#l00045">roll_state::h2</a>, <a class="el" href="spamsum_8h_source.html#l00046">roll_state::h3</a>, <a class="el" href="spamsum_8h_source.html#l00047">roll_state::n</a>, <a class="el" href="spamsum_8h_source.html#l00056">spamsum_ctx::roll</a>, <a class="el" href="spamsum_8h_source.html#l00026">ROLLING_WINDOW</a>, and <a class="el" href="spamsum_8h_source.html#l00043">roll_state::window</a>.</p>
|
||
|
||
<p class="reference">Referenced by <a class="el" href="spamsum_8c_source.html#l00084">fuzzy_engine_step()</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_d44c64559bbebec7f509842c48db8b23.html">include</a></li><li class="navelem"><a href="dir_aeff2545c9dfcfc842fe9d84b123cb31.html">aaruformat</a></li><li class="navelem"><a href="decls_8h.html">decls.h</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.14.0 </li>
|
||
</ul>
|
||
</div>
|
||
</body>
|
||
</html>
|