<trclass="memdesc:aa8588f3b6c705666833c84e6cd4cfe62"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Reads a media tag from the AaruFormat image. <br/></td></tr>
<trclass="memdesc:a6feebf672750fc129fe2802ab738d563"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Reads a sector from the AaruFormat image. <br/></td></tr>
<trclass="memdesc:a84e3bc8f611af8e9fc77dac24788d53b"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Reads a sector from a specific track in the AaruFormat image. <br/></td></tr>
<trclass="memdesc:a7c8786fe6f2a1538bcb2362cfe21563c"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Reads a complete sector with all metadata from the AaruFormat image. <br/></td></tr>
<trclass="memdesc:ac6c55f931eb4c113d19ff7c194fce65a"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Reads a specific sector tag from the AaruFormat image. <br/></td></tr>
<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>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
<tr><tdclass="paramname">data</td><td>Pointer to the buffer to store the tag data. Can be NULL to query tag length. </td></tr>
<tr><tdclass="paramname">tag</td><td>Tag identifier to read (specific to media type and format). </td></tr>
<tr><tdclass="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>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully 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><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_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><tdclass="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>
<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>
<dlclass="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>
<pclass="definition">Definition at line <aclass="el"href="read_8c_source.html#l00085">85</a> of file <aclass="el"href="read_8c_source.html">read.c</a>.</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>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
<tr><tdclass="paramname">sector_address</td><td>The logical sector address to read from. </td></tr>
<tr><tdclass="paramname">negative</td><td>Indicates if the sector address is negative. </td></tr>
<tr><tdclass="paramname">data</td><td>Pointer to buffer where sector data will be stored. Can be NULL to query length. </td></tr>
<tr><tdclass="paramname">length</td><td>Pointer to variable containing buffer size on input, actual data length on output. </td></tr>
<tr><tdclass="paramname">sector_status</td><td>Pointer to variable that will receive the sector status flags. Must not be NULL. The status indicates the condition of the sector data, such as whether it contains errors, was not dumped, or has other quality indicators from the imaging process.</td></tr>
<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><tdclass="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><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_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><tdclass="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><tdclass="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><tdclass="paramname">AARUF_ERROR_CANNOT_READ_HEADER</td><td>(-6) Block header reading failed. This occurs when:<ul>
<li>Cannot read the complete <aclass="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><tdclass="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><tdclass="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><tdclass="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><tdclass="paramname">Other</td><td>error codes may be propagated from DDT decoding functions:<ul>
<li>From <aclass="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 <aclass="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>
<dlclass="section warning"><dt>Warning</dt><dd>This function reads only user data. For complete sector data including metadata and ECC/EDC information, use <aclass="el"href="#a7c8786fe6f2a1538bcb2362cfe21563c"title="Reads a complete sector with all metadata from the AaruFormat image.">aaruf_read_sector_long()</a>.</dd>
<pclass="definition">Definition at line <aclass="el"href="read_8c_source.html#l00253">253</a> of file <aclass="el"href="read_8c_source.html">read.c</a>.</p>
<pclass="reference">Referenced by <aclass="el"href="read_8c_source.html#l00826">aaruf_read_sector_long()</a>, and <aclass="el"href="read_8c_source.html#l00670">aaruf_read_track_sector()</a>.</p>
<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>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
<tr><tdclass="paramname">sector_address</td><td>The logical sector address to read from. </td></tr>
<tr><tdclass="paramname">negative</td><td>Indicates if the sector address is negative. </td></tr>
<tr><tdclass="paramname">data</td><td>Pointer to buffer where complete sector data will be stored. Can be NULL to query length. </td></tr>
<tr><tdclass="paramname">length</td><td>Pointer to variable containing buffer size on input, actual data length on output. </td></tr>
<tr><tdclass="paramname">sector_status</td><td>Pointer to variable that will receive the sector status flags. Must not be NULL. The status indicates the condition of the sector data, such as whether it contains errors, was not dumped, or has other quality indicators from the imaging process.</td></tr>
<li>Memory allocation fails in underlying <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> calls</li>
<tr><tdclass="paramname">All</td><td>error codes from <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> may be propagated:<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>
<dlclass="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>
Not all AaruFormat images contain the metadata necessary for long sector reading. Some images may only support basic sector reading via <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a>. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="read_8c_source.html#l00826">826</a> of file <aclass="el"href="read_8c_source.html">read.c</a>.</p>
<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>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context. </td></tr>
<tr><tdclass="paramname">sector_address</td><td>The logical sector address to read the tag from. </td></tr>
<tr><tdclass="paramname">negative</td><td>Indicates if the sector address is negative (pre-track area). </td></tr>
<tr><tdclass="paramname">buffer</td><td>Pointer to buffer where tag data will be stored. Can be NULL to query tag length. </td></tr>
<tr><tdclass="paramname">length</td><td>Pointer to variable containing buffer size on input, actual tag length on output. </td></tr>
<tr><tdclass="paramname">tag</td><td>Tag identifier specifying which sector tag to read (see <aclass="el"href="group__SectorTags.html#gaf863e81d172ce7a216d8687a8a23293a">SectorTagType</a> enum).</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully 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><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_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><tdclass="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><tdclass="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><tdclass="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><tdclass="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><tdclass="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 <aclass="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>
<dlclass="section note"><dt>Note</dt><dd>Supported Tag Types and Sizes: Optical Disc Tags (OpticalDisc media only):<ul>
<dlclass="section warning"><dt>Warning</dt><dd>The buffer must be exactly the required size for each tag type. Unlike <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a>, this function enforces strict size matching.</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>
<pclass="definition">Definition at line <aclass="el"href="read_8c_source.html#l01474">1474</a> of file <aclass="el"href="read_8c_source.html">read.c</a>.</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 <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a>.</p>
<tr><tdclass="paramname">track</td><td>The track sequence number to read from. </td></tr>
<tr><tdclass="paramname">sector_status</td><td>Pointer to variable that will receive the sector status flags. Must not be NULL. The status indicates the condition of the sector data, such as whether it contains errors, was not dumped, or has other quality indicators from the imaging process.</td></tr>
<li>The underlying <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> call succeeds</li>
<tr><tdclass="paramname">All</td><td>other error codes from <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"title="Reads a sector from the AaruFormat image.">aaruf_read_sector()</a> may be returned:<ul>
<li>The actual sector reading is performed by <aclass="el"href="#a6feebf672750fc129fe2802ab738d563"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>
<dlclass="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>
<pclass="definition">Definition at line <aclass="el"href="read_8c_source.html#l00670">670</a> of file <aclass="el"href="read_8c_source.html">read.c</a>.</p>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.14.0 </li>
