aaru-dps/libaaruformat
1
0
Fork 0
mirror of https://github.com/aaru-dps/libaaruformat.git synced 2025-12-16 19:24:40 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
dde81f67730915d10c15e3efff56d35b4f26789c
libaaruformat/docs/html/read_8c.html

851 lines
63 KiB
HTML
Raw Normal View History

Add doxygen documentation
2025-10-11 01:35:43 +01:00
<!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: src/read.c File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">libaaruformat<span id="projectnumber">&#160;1.0</span>
</div>
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.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('read_8c.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="headertitle"><div class="title">read.c File Reference</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><code>#include &lt;stdlib.h&gt;</code><br />
<code>#include &lt;string.h&gt;</code><br />
<code>#include &lt;<a class="el" href="aaruformat_8h_source.html">aaruformat.h</a>&gt;</code><br />
<code>#include &quot;<a class="el" href="internal_8h_source.html">internal.h</a>&quot;</code><br />
<code>#include &quot;<a class="el" href="log_8h_source.html">log.h</a>&quot;</code><br />
</div>
<p><a href="read_8c_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:aa8588f3b6c705666833c84e6cd4cfe62" id="r_aa8588f3b6c705666833c84e6cd4cfe62"><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#aa8588f3b6c705666833c84e6cd4cfe62">aaruf_read_media_tag</a> (void *context, uint8_t *data, const int32_t tag, uint32_t *length)</td></tr>
<tr class="memdesc:aa8588f3b6c705666833c84e6cd4cfe62"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads a media tag from the AaruFormat image. <br /></td></tr>
<tr class="memitem:adb06ba1a94336663acf8fc60b3589faa" id="r_adb06ba1a94336663acf8fc60b3589faa"><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#adb06ba1a94336663acf8fc60b3589faa">aaruf_read_sector</a> (void *context, const uint64_t sector_address, bool negative, uint8_t *data, uint32_t *length)</td></tr>
<tr class="memdesc:adb06ba1a94336663acf8fc60b3589faa"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads a sector from the AaruFormat image. <br /></td></tr>
<tr class="memitem:acf3ceb372324a578b2ba71886a857103" id="r_acf3ceb372324a578b2ba71886a857103"><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#acf3ceb372324a578b2ba71886a857103">aaruf_read_track_sector</a> (void *context, uint8_t *data, const uint64_t sector_address, uint32_t *length, const uint8_t track)</td></tr>
<tr class="memdesc:acf3ceb372324a578b2ba71886a857103"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads a sector from a specific track in the AaruFormat image. <br /></td></tr>
<tr class="memitem:ae30e05b38fead34408ffcdf92fcb503a" id="r_ae30e05b38fead34408ffcdf92fcb503a"><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ae30e05b38fead34408ffcdf92fcb503a">aaruf_read_sector_long</a> (void *context, const uint64_t sector_address, bool negative, uint8_t *data, uint32_t *length)</td></tr>
<tr class="memdesc:ae30e05b38fead34408ffcdf92fcb503a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads a complete sector with all metadata from the AaruFormat image. <br /></td></tr>
<tr class="memitem:ac6c55f931eb4c113d19ff7c194fce65a" id="r_ac6c55f931eb4c113d19ff7c194fce65a"><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ac6c55f931eb4c113d19ff7c194fce65a">aaruf_read_sector_tag</a> (const void *context, const uint64_t sector_address, const bool negative, uint8_t *buffer, uint32_t *length, const int32_t tag)</td></tr>
<tr class="memdesc:ac6c55f931eb4c113d19ff7c194fce65a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads a specific sector tag from the AaruFormat image. <br /></td></tr>
</table>
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
<a id="aa8588f3b6c705666833c84e6cd4cfe62" name="aa8588f3b6c705666833c84e6cd4cfe62"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa8588f3b6c705666833c84e6cd4cfe62">&#9670;&#160;</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>&#160;)</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="adb06ba1a94336663acf8fc60b3589faa" name="adb06ba1a94336663acf8fc60b3589faa"></a>
<h2 class="memtitle"><span class="permalink"><a href="#adb06ba1a94336663acf8fc60b3589faa">&#9670;&#160;</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>&#160;)</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-&gt;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-&gt;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-&gt;blockHeaderCache)</li>
<li>Decompressed block data is cached to avoid repeated decompression (ctx-&gt;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="#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-&gt;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="ae30e05b38fead34408ffcdf92fcb503a" name="ae30e05b38fead34408ffcdf92fcb503a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae30e05b38fead34408ffcdf92fcb503a">&#9670;&#160;</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>&#160;)</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-&gt;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="#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="#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="#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="enum
</div>
</div>
<a id="ac6c55f931eb4c113d19ff7c194fce65a" name="ac6c55f931eb4c113d19ff7c194fce65a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac6c55f931eb4c113d19ff7c194fce65a">&#9670;&#160;</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>&#160;)</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 &gt; ctx-&gt;userDataDdtHeader.negative - 1</li>
<li>negative is false and sector_address &gt; ctx-&gt;imageInfo.Sectors + ctx-&gt;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-&gt;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-&gt;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-&gt;userDataDdtHeader.negative</li>
<li>Positive sectors are adjusted: corrected = sector_address + ctx-&gt;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-&gt;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-&gt;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-&gt;sector_subchannel, ctx-&gt;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="#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="acf3ceb372324a578b2ba71886a857103" name="acf3ceb372324a578b2ba71886a857103"></a>
<h2 class="memtitle"><span class="permalink"><a href="#acf3ceb372324a578b2ba71886a857103">&#9670;&#160;</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>&#160;)</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="#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="#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-&gt;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-&gt;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="#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-&gt;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="#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>
</div><!-- contents -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a href="dir_68267d1309a1af8e8297ef4c3efbcdba.html">src</a></li><li class="navelem"><a href="read_8c.html">read.c</a></li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0 </li>
</ul>
</div>
</body>
</html>
Reference in New Issue Copy Permalink