<trclass="memdesc:ac85ad03ba0f06b8799d7fe056b87a18e"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Adds entries from a subindex block (version 3) to the main index entries array. <br/></td></tr>
<trclass="memdesc:aff88fae9938d5f56318bfd7a455d5e94"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Processes an index block (version 3) from the image stream. <br/></td></tr>
<trclass="memdesc:ad7ed9250463c320c7bc8d83689bcfefb"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Verifies the integrity of an index block (version 3) in the image stream. <br/></td></tr>
<p>Adds entries from a subindex block (version 3) to the main index entries array. </p>
<p>Recursively reads subindex blocks and appends their entries to the main index entries array. This function is a critical component of the hierarchical index system in AaruFormat version 3, enabling scalable index organization for large image files. It performs recursive traversal of subindex structures, flattening the hierarchy into a single array while maintaining entry order and handling nested subindex references.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context containing the image stream. </td></tr>
<tr><tdclass="paramname">index_entries</td><td>Pointer to the UT_array of main index entries to append to. </td></tr>
<tr><tdclass="paramname">subindex_entry</td><td>Pointer to the <aclass="el"href="structIndexEntry.html"title="Single index entry describing a block's type, (optional) data classification, and file offset.">IndexEntry</a> describing the subindex location and metadata.</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns true when entries are appended successfully, false when an error occurs.</dd></dl>
<li>Designed for graceful degradation - errors don't propagate to callers</li>
<li>Invalid subindexes are skipped without affecting other processing</li>
<li>Partial success is possible when some subindexes fail but others succeed</li>
<li>Logging provides visibility into processing failures for debugging</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>This function modifies the index_entries array by appending new entries. Ensure the array has sufficient capacity and is properly initialized.</dd>
<dd>
Recursive processing can cause significant stack usage for deeply nested subindex structures. Very deep hierarchies may cause stack overflow.</dd>
<dd>
The function assumes subindex_entry->offset points to a valid subindex block. Invalid offsets will cause file access errors but are handled gracefully.</dd>
<dd>
No validation is performed on individual <aclass="el"href="structIndexEntry.html"title="Single index entry describing a block's type, (optional) data classification, and file offset.">IndexEntry</a> contents - only structural validation of subindex headers is done. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="index__v3_8c_source.html#l00247">247</a> of file <aclass="el"href="index__v3_8c_source.html">index_v3.c</a>.</p>
<pclass="reference">Referenced by <aclass="el"href="index__v3_8c_source.html#l00247">add_subindex_entries()</a>, and <aclass="el"href="index__v3_8c_source.html#l00098">process_index_v3()</a>.</p>
<p>Processes an index block (version 3) from the image stream. </p>
<p>Reads and parses an index block (version 3) from the image, returning an array of index entries. This function handles the advanced index format used in current AaruFormat versions, supporting hierarchical subindex structures for improved scalability. It reads the <aclass="el"href="structIndexHeader3.html"title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a> structure followed by index entries, recursively processing any subindex blocks encountered to create a flattened array of all index entries.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context containing the image stream and header information.</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following values: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">UT_array*</td><td>Successfully processed the index block and all subindexes. This is returned when:<ul>
<li>The context and image stream are valid</li>
<li>The index header is successfully read from the position specified in ctx->header.indexOffset</li>
<li>The index identifier matches IndexBlock3 (version 3 format identifier)</li>
<li>All index entries are successfully read and stored in the UT_array</li>
<li>Any subindex blocks (IndexBlock3 entries) are recursively processed via <aclass="el"href="#ac85ad03ba0f06b8799d7fe056b87a18e"title="Adds entries from a subindex block (version 3) to the main index entries array.">add_subindex_entries()</a></li>
<li>Memory allocation for the index entries array succeeds</li>
<li>The returned array contains all index entries from the main index and all subindexes</li>
</ul>
</td></tr>
<tr><tdclass="paramname">NULL</td><td>Index processing failed. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The image stream (ctx->imageStream) is NULL or invalid</li>
<li>Cannot read the <aclass="el"href="structIndexHeader3.html"title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a> structure from the image stream</li>
<li>The index identifier doesn't match IndexBlock3 (incorrect format or corruption)</li>
<li>Memory allocation fails for the UT_array structure</li>
<li>File I/O errors occur while reading index entries</li>
<li>Recursive subindex processing fails (errors in <aclass="el"href="#ac85ad03ba0f06b8799d7fe056b87a18e"title="Adds entries from a subindex block (version 3) to the main index entries array.">add_subindex_entries()</a>)</li>
<li><aclass="el"href="structIndexEntry.html"title="Single index entry describing a block's type, (optional) data classification, and file offset.">IndexEntry</a> array: May contain regular entries and subindex references (IndexBlock3 type)</li>
<li>Hierarchical support: Subindex entries are recursively processed to flatten the structure</li>
<li>No CRC validation is performed during processing (use verify_index_v3 for validation)</li>
<li>Supports scalable index organization for large image files</li>
</ul>
</dd>
<dd>
Subindex Processing:<ul>
<li>When an <aclass="el"href="structIndexEntry.html"title="Single index entry describing a block's type, (optional) data classification, and file offset.">IndexEntry</a> has blockType == IndexBlock3, it references a subindex</li>
<li>Subindexes are recursively processed using <aclass="el"href="#ac85ad03ba0f06b8799d7fe056b87a18e"title="Adds entries from a subindex block (version 3) to the main index entries array.">add_subindex_entries()</a></li>
<li>All entries from subindexes are flattened into the main index entries array</li>
<li>Supports arbitrary nesting depth of subindexes</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>Returns a newly allocated UT_array that must be freed by the caller using utarray_free()</li>
<li>On error, any partially allocated memory is cleaned up before returning NULL</li>
<li>Each <aclass="el"href="structIndexEntry.html"title="Single index entry describing a block's type, (optional) data classification, and file offset.">IndexEntry</a> is copied into the array (no reference to original stream data)</li>
<li>Memory usage scales with total entries across all subindexes</li>
</ul>
</dd>
<dd>
Version Compatibility:<ul>
<li>Supports only IndexBlock3 format (not IndexBlock or IndexBlock2)</li>
<li>Compatible with current generation AaruFormat image files</li>
<li>Backward compatible with images that don't use subindexes</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The caller is responsible for freeing the returned UT_array using utarray_free(). Failure to free the array will result in memory leaks.</dd>
<dd>
This function does not validate the CRC integrity of the index data. Use <aclass="el"href="#ad7ed9250463c320c7bc8d83689bcfefb"title="Verifies the integrity of an index block (version 3) in the image stream.">verify_index_v3()</a> to ensure index integrity before processing.</dd>
<dd>
Recursive subindex processing may cause significant memory usage and processing time for images with deeply nested or numerous subindexes.</dd>
<dd>
The function assumes ctx->header.indexOffset points to a valid index block. Invalid offsets may cause file access errors or reading incorrect data. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="index__v3_8c_source.html#l00098">98</a> of file <aclass="el"href="index__v3_8c_source.html">index_v3.c</a>.</p>
<pclass="reference">Referenced by <aclass="el"href="open_8c_source.html#l00223">aaruf_open()</a>, and <aclass="el"href="verify_8c_source.html#l00130">aaruf_verify_image()</a>.</p>
<p>Verifies the integrity of an index block (version 3) in the image stream. </p>
<p>Checks the CRC64 of the index block and all subindexes without decompressing them. This function performs comprehensive validation of the advanced version 3 index structure including header validation, data integrity verification, and version-specific CRC calculation. Note that this function validates only the main index block's CRC and does not recursively validate subindex CRCs, focusing on the primary index structure integrity.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context containing image stream and header information.</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 verified index integrity. This is returned when:<ul>
<li>The context and image stream are valid</li>
<li>The index header is successfully read from ctx->header.indexOffset</li>
<li>The index identifier matches IndexBlock3 (version 3 format)</li>
<li>Memory allocation for index entries succeeds</li>
<li>All index entries are successfully read from the image stream</li>
<li>CRC64 calculation completes successfully with version-specific endianness handling</li>
<li>The calculated CRC64 matches the expected CRC64 in the index header</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or stream. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The image stream (ctx->imageStream) is NULL or invalid</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_CANNOT_READ_HEADER</td><td>(-6) Index header reading failed. This occurs when:<ul>
<li>Cannot read the complete <aclass="el"href="structIndexHeader3.html"title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a> structure from the image stream</li>
<li>File I/O errors prevent accessing the header at ctx->header.indexOffset</li>
<li>Insufficient data available at the specified index offset</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_CANNOT_READ_INDEX</td><td>(-19) Index format or data access errors. This occurs when:<ul>
<li>The index identifier doesn't match IndexBlock3 (wrong format or corruption)</li>
<li>Cannot read all index entries from the image stream</li>
<li>File I/O errors during index entry reading</li>
<li>Index structure is corrupted or truncated</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 the index entries array</li>
<li>System memory exhaustion prevents loading index data for verification</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_INVALID_BLOCK_CRC</td><td>(-18) CRC64 validation failed. This occurs when:<ul>
<li>The calculated CRC64 doesn't match the expected CRC64 in the index header</li>
<li>Reads all main index entries into memory for CRC calculation</li>
<li>Calculates CRC64 over the complete main index entries array</li>
<li>Applies version-specific endianness conversion for compatibility</li>
<li>For imageMajorVersion <= AARUF_VERSION_V1: Uses <aclass="el"href="endian_8h.html#a0c0b427a2547aa727e2c5262a174e26b">bswap_64()</a> for byte order correction</li>
<li>Compares calculated CRC64 with the value stored in the <aclass="el"href="structIndexHeader3.html"title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a></li>
<li>Maintains compatibility with legacy endianness handling</li>
<li>Supports advanced index entry organization with subindex references</li>
<li>Only validates the main index block CRC - subindex CRCs are not recursively checked</li>
</ul>
</dd>
<dd>
Validation Scope:<ul>
<li>Validates main index header structure and identifier</li>
<li>Verifies data integrity of the primary index entries through CRC64 calculation</li>
<li>Does not validate individual <aclass="el"href="structIndexEntry.html"title="Single index entry describing a block's type, (optional) data classification, and file offset.">IndexEntry</a> contents or block references</li>
<li>Does not check for logical consistency of referenced blocks</li>
<li>Does not recursively validate subindex blocks (unlike hierarchical processing)</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>Allocates temporary memory for index entries during verification</li>
<li>Automatically frees allocated memory on both success and error conditions</li>
<li>Memory usage is proportional to the number of entries in the main index only</li>
</ul>
</dd>
<dd>
Subindex Validation Limitation:<ul>
<li>This function does not recursively validate subindex CRCs</li>
<li>Each subindex block contains its own CRC that would need separate validation</li>
<li>For complete integrity verification, subindex blocks should be validated individually</li>
<li>The main index CRC only covers the primary index entries, not the subindex content</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>This function reads only the main index into memory for CRC calculation. Subindex blocks are not loaded or validated by this function.</dd>
<dd>
The function assumes ctx->header.indexOffset points to a valid index location. Invalid offsets will cause file access errors or incorrect validation.</dd>
<dd>
CRC validation failure indicates potential data corruption in the main index and may suggest the image file is damaged or has been modified outside of library control.</dd>
<dd>
For complete integrity verification of hierarchical indexes, additional validation of subindex blocks may be required beyond this function's scope. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="index__v3_8c_source.html#l00408">408</a> of file <aclass="el"href="index__v3_8c_source.html">index_v3.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>
