<p>Opens the specified image file and returns a pointer to the initialized aaruformat context. This function performs comprehensive validation of the image file format, reads and processes all index entries, initializes data structures for reading operations, and sets up caches for optimal performance. It supports multiple AaruFormat versions and handles various block types including data blocks, deduplication tables, metadata, and checksums.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">filepath</td><td>Path to the image file to open.</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">aaruformatContext*</td><td>Successfully opened and initialized context. The returned pointer contains:<ul>
<li>Validated AaruFormat headers and metadata</li>
<li>Processed index entries with all discoverable blocks</li>
<li>Loaded deduplication tables (DDT) for efficient sector access</li>
<li>Initialized block and header caches for performance</li>
<li>Open file stream ready for reading operations</li>
<li>Populated image information and geometry data</li>
<li>ECC context initialized for error correction support</li>
</ul>
</td></tr>
<tr><tdclass="paramname">NULL</td><td>Opening failed. The specific error can be determined by checking errno, which will be set to:<ul>
<li>AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) when memory allocation fails for:<ul>
<li>Context allocation</li>
<li>Readable sector tags bitmap allocation</li>
<li>Application version string allocation</li>
<li>Image version string allocation</li>
</ul>
</li>
<li>AARUF_ERROR_FILE_TOO_SMALL (-2) when file reading fails:<ul>
<li>Cannot read the AaruFormat header (file too small or corrupted)</li>
<li>Cannot read the extended header for version 2+ formats</li>
</ul>
</li>
<li>AARUF_ERROR_NOT_AARUFORMAT (-1) when format validation fails:<ul>
<li>File identifier doesn't match DIC_MAGIC or AARU_MAGIC</li>
<li>Automatically detects and handles different index formats (v1, v2, v3)</li>
<li>Backwards compatible with older DIC format identifiers</li>
<li>Handles both small and large deduplication tables</li>
</ul>
</dd>
<dd>
Block Processing:<ul>
<li>Processes all indexed blocks including data, DDT, geometry, metadata, tracks, CICM, dump hardware, and checksums</li>
<li>Non-critical block processing errors are logged but don't prevent opening</li>
<li>Critical errors (DDT processing failures) cause opening to fail</li>
<li>Unknown block types are logged but ignored</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>Allocates memory for various context structures and caches</li>
<li>On failure, all previously allocated memory is properly cleaned up</li>
<li>The returned context must be freed using <aclass="el"href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49"title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a></li>
</ul>
</dd>
<dd>
Performance Optimization:<ul>
<li>Initializes block and header caches based on sector size and available memory</li>
<li>Cache sizes are calculated to optimize memory usage and access patterns</li>
<li>ECC context is pre-initialized for Compact Disc support</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The function requires a valid user data deduplication table to be present. Images without a DDT will fail to open even if otherwise valid.</dd>
<dd>
File access is performed in binary read mode. The file must be accessible and not locked by other processes.</dd>
<dd>
Some memory allocations (version strings) are optional and failure doesn't prevent opening, but may affect functionality that depends on version information. </dd></dl>
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
<pclass="definition">Definition at line <aclass="el"href="open_8c_source.html#l00125">125</a> of file <aclass="el"href="open_8c_source.html">open.c</a>.</p>
<pclass="definition">Definition at line <aclass="el"href="open_8c_source.html#l00031">31</a> of file <aclass="el"href="open_8c_source.html">open.c</a>.</p>
<pclass="reference">References <aclass="el"href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, and <aclass="el"href="context_8h_source.html#l00263">aaruformat_context::readableSectorTags</a>.</p>
<pclass="reference">Referenced by <aclass="el"href="open_8c_source.html#l00125">aaruf_open()</a>.</p>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<divid="page-nav"class="page-nav-panel">
<divid="page-nav-resize-handle"></div>
<divid="page-nav-tree">
<divid="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<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>
