mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 19:24:40 +00:00
226 lines
14 KiB
HTML
226 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
||
<meta name="generator" content="Doxygen 1.14.0"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>libaaruformat: include/aaruformat/structs/index.h File Reference</title>
|
||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="jquery.js"></script>
|
||
<script type="text/javascript" src="dynsections.js"></script>
|
||
<script type="text/javascript" src="clipboard.js"></script>
|
||
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="navtreedata.js"></script>
|
||
<script type="text/javascript" src="navtree.js"></script>
|
||
<script type="text/javascript" src="cookie.js"></script>
|
||
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
<script type="text/javascript" src="search/search.js"></script>
|
||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
</head>
|
||
<body>
|
||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
<div id="titlearea">
|
||
<table cellspacing="0" cellpadding="0">
|
||
<tbody>
|
||
<tr id="projectrow">
|
||
<td id="projectalign">
|
||
<div id="projectname">libaaruformat<span id="projectnumber"> 1.0</span>
|
||
</div>
|
||
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.14.0 -->
|
||
<script type="text/javascript">
|
||
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
||
</script>
|
||
<script type="text/javascript">
|
||
$(function() { codefold.init(); });
|
||
</script>
|
||
<script type="text/javascript" src="menudata.js"></script>
|
||
<script type="text/javascript" src="menu.js"></script>
|
||
<script type="text/javascript">
|
||
$(function() {
|
||
initMenu('',true,false,'search.php','Search',true);
|
||
$(function() { init_search(); });
|
||
});
|
||
</script>
|
||
<div id="main-nav"></div>
|
||
</div><!-- top -->
|
||
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
<div id="nav-tree">
|
||
<div id="nav-tree-contents">
|
||
<div id="nav-sync" class="sync"></div>
|
||
</div>
|
||
</div>
|
||
<div id="splitbar" style="-moz-user-select:none;"
|
||
class="ui-resizable-handle">
|
||
</div>
|
||
</div>
|
||
<script type="text/javascript">
|
||
$(function(){initNavTree('index_8h.html','',''); });
|
||
</script>
|
||
<div id="container">
|
||
<div id="doc-content">
|
||
<!-- window showing the filter options -->
|
||
<div id="MSearchSelectWindow"
|
||
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
</div>
|
||
|
||
<!-- iframe showing the search results (closed by default) -->
|
||
<div id="MSearchResultsWindow">
|
||
<div id="MSearchResults">
|
||
<div class="SRPage">
|
||
<div id="SRIndex">
|
||
<div id="SRResults"></div>
|
||
<div class="SRStatus" id="Loading">Loading...</div>
|
||
<div class="SRStatus" id="Searching">Searching...</div>
|
||
<div class="SRStatus" id="NoMatches">No Matches</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="header">
|
||
<div class="headertitle"><div class="title">index.h File Reference</div></div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
|
||
<p>On‑disk index block header and entry structures (versions 1, 2 and 3).
|
||
<a href="#details">More...</a></p>
|
||
|
||
<p><a href="index_8h_source.html">Go to the source code of this file.</a></p>
|
||
<table class="memberdecls">
|
||
<tr class="heading"><td colspan="2"><h2 id="header-nested-classes" class="groupheader"><a id="nested-classes" name="nested-classes"></a>
|
||
Data Structures</h2></td></tr>
|
||
<tr class="memitem:IndexHeader" id="r_IndexHeader"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structIndexHeader.html">IndexHeader</a></td></tr>
|
||
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Index header (version 1) for legacy images (identifier == IndexBlock). <a href="structIndexHeader.html#details">More...</a><br /></td></tr>
|
||
<tr class="memitem:IndexHeader2" id="r_IndexHeader2"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structIndexHeader2.html">IndexHeader2</a></td></tr>
|
||
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Index header (version 2) with 64‑bit entry counter (identifier == IndexBlock2). <a href="structIndexHeader2.html#details">More...</a><br /></td></tr>
|
||
<tr class="memitem:IndexHeader3" id="r_IndexHeader3"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structIndexHeader3.html">IndexHeader3</a></td></tr>
|
||
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3). <a href="structIndexHeader3.html#details">More...</a><br /></td></tr>
|
||
<tr class="memitem:IndexEntry" id="r_IndexEntry"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structIndexEntry.html">IndexEntry</a></td></tr>
|
||
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Single index entry describing a block's type, (optional) data classification, and file offset. <a href="structIndexEntry.html#details">More...</a><br /></td></tr>
|
||
</table><table class="memberdecls">
|
||
<tr class="heading"><td colspan="2"><h2 id="header-typedef-members" class="groupheader"><a id="typedef-members" name="typedef-members"></a>
|
||
Typedefs</h2></td></tr>
|
||
<tr class="memitem:af68e20e1f9ee3ea029ed4f69ea82c32f" id="r_af68e20e1f9ee3ea029ed4f69ea82c32f"><td class="memItemLeft" align="right" valign="top">typedef struct IndexHeader </td><td class="memItemRight" valign="bottom"><a class="el" href="#af68e20e1f9ee3ea029ed4f69ea82c32f">IndexHeader</a></td></tr>
|
||
<tr class="memitem:a5f7e5a06dff1100016015c4809277d2a" id="r_a5f7e5a06dff1100016015c4809277d2a"><td class="memItemLeft" align="right" valign="top">typedef struct IndexHeader2 </td><td class="memItemRight" valign="bottom"><a class="el" href="#a5f7e5a06dff1100016015c4809277d2a">IndexHeader2</a></td></tr>
|
||
<tr class="memitem:acae06d4f1500d591e6d86b9d52d29a84" id="r_acae06d4f1500d591e6d86b9d52d29a84"><td class="memItemLeft" align="right" valign="top">typedef struct IndexHeader3 </td><td class="memItemRight" valign="bottom"><a class="el" href="#acae06d4f1500d591e6d86b9d52d29a84">IndexHeader3</a></td></tr>
|
||
<tr class="memitem:a12d666b4c91b2de9ba60887f0783e98d" id="r_a12d666b4c91b2de9ba60887f0783e98d"><td class="memItemLeft" align="right" valign="top">typedef struct IndexEntry </td><td class="memItemRight" valign="bottom"><a class="el" href="#a12d666b4c91b2de9ba60887f0783e98d">IndexEntry</a></td></tr>
|
||
</table>
|
||
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
|
||
<div class="textblock"><p>On‑disk index block header and entry structures (versions 1, 2 and 3). </p>
|
||
<p>The index provides a directory of all blocks contained in an Aaru image. Each index block starts with a versioned header (<a class="el" href="structIndexHeader.html" title="Index header (version 1) for legacy images (identifier == IndexBlock).">IndexHeader</a> / <a class="el" href="structIndexHeader2.html" title="Index header (version 2) with 64‑bit entry counter (identifier == IndexBlock2).">IndexHeader2</a> / <a class="el" href="structIndexHeader3.html" title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a>) followed by a contiguous array of fixed‑size <a class="el" href="structIndexEntry.html">IndexEntry</a> records. Version 3 adds support for hierarchical (chained / nested) subindexes.</p>
|
||
<p>Version mapping by block identifier (see <a class="el" href="enums_8h.html#a54420623f26ab6bb61042b41cccf37a3">BlockType</a>):</p><ul>
|
||
<li>IndexBlock (v1) -> <a class="el" href="structIndexHeader.html">IndexHeader</a> followed by 16‑bit entry count entries.</li>
|
||
<li>IndexBlock2 (v2) -> <a class="el" href="structIndexHeader2.html">IndexHeader2</a> followed by 64‑bit entry count entries.</li>
|
||
<li>IndexBlock3 (v3) -> <a class="el" href="structIndexHeader3.html">IndexHeader3</a> with optional hierarchical subindex references.</li>
|
||
</ul>
|
||
<p>CRC coverage & endianness:</p><ul>
|
||
<li>The crc64 field stores a CRC64-ECMA over the entries array ONLY (header bytes are excluded).</li>
|
||
<li>For images with imageMajorVersion <= AARUF_VERSION_V1 a legacy writer byte-swapped the CRC; readers compensate (see verify_index_v1/v2/v3). The value in the header remains whatever was originally written.</li>
|
||
</ul>
|
||
<p>Hierarchical (v3) behavior:</p><ul>
|
||
<li>Entries whose blockType == IndexBlock3 refer to subindex blocks; readers recursively load and flatten.</li>
|
||
<li><a class="el" href="structIndexHeader3.html#a33743c206cb10cc1d8ff2c7f9e61ddcf" title="File offset of a previous IndexBlock3 header (0 if none / root segment).">IndexHeader3::previous</a> can point to a preceding index segment (for append / incremental scenarios) or 0.</li>
|
||
<li>CRC of the main index does NOT cover subindex contents; each subindex has its own header + CRC.</li>
|
||
</ul>
|
||
<p>Invariants / validation recommendations:</p><ul>
|
||
<li>identifier must equal the expected <a class="el" href="enums_8h.html#a54420623f26ab6bb61042b41cccf37a3" title="List of known block types contained in an Aaru image.">BlockType</a> variant for that version.</li>
|
||
<li>entries > 0 implies the entries array byte size == entries * sizeof(IndexEntry).</li>
|
||
<li>crc64 must match recomputed CRC64( entries array ) (after legacy byte swap handling if required).</li>
|
||
<li>For v3, if previous != 0 it should point to another IndexBlock3 header (optional best‑effort check).</li>
|
||
</ul>
|
||
<p>Notes:</p><ul>
|
||
<li>Structures are packed (1‑byte alignment). All multi-byte integers are little‑endian on disk.</li>
|
||
<li>The index does not store per-entry CRC; integrity relies on each individual block's own CRC plus the index CRC.</li>
|
||
<li>dataType in <a class="el" href="structIndexEntry.html">IndexEntry</a> is meaningful only for block types that carry typed data (e.g. DataBlock, DumpHardwareBlock, etc.).</li>
|
||
</ul>
|
||
<p>See also: <a class="el" href="internal_8h.html#a89ed93d216c4dce0ae5e2acccf8cc2b4" title="Verifies the integrity of an index block (version 1) in the image stream.">verify_index_v1()</a>, <a class="el" href="internal_8h.html#ae234e22b16b085d18614110630034db5" title="Verifies the integrity of an index block (version 2) in the image stream.">verify_index_v2()</a>, <a class="el" href="internal_8h.html#ad7ed9250463c320c7bc8d83689bcfefb" title="Verifies the integrity of an index block (version 3) in the image stream.">verify_index_v3()</a> for integrity procedures. </p>
|
||
|
||
<p class="definition">Definition in file <a class="el" href="index_8h_source.html">index.h</a>.</p>
|
||
</div><a name="doc-typedef-members" id="doc-typedef-members"></a><h2 id="header-doc-typedef-members" class="groupheader">Typedef Documentation</h2>
|
||
<a id="a12d666b4c91b2de9ba60887f0783e98d" name="a12d666b4c91b2de9ba60887f0783e98d"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a12d666b4c91b2de9ba60887f0783e98d">◆ </a></span>IndexEntry</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">typedef struct IndexEntry IndexEntry</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
</div>
|
||
</div>
|
||
<a id="af68e20e1f9ee3ea029ed4f69ea82c32f" name="af68e20e1f9ee3ea029ed4f69ea82c32f"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#af68e20e1f9ee3ea029ed4f69ea82c32f">◆ </a></span>IndexHeader</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">typedef struct IndexHeader IndexHeader</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
</div>
|
||
</div>
|
||
<a id="a5f7e5a06dff1100016015c4809277d2a" name="a5f7e5a06dff1100016015c4809277d2a"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#a5f7e5a06dff1100016015c4809277d2a">◆ </a></span>IndexHeader2</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">typedef struct IndexHeader2 IndexHeader2</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
</div>
|
||
</div>
|
||
<a id="acae06d4f1500d591e6d86b9d52d29a84" name="acae06d4f1500d591e6d86b9d52d29a84"></a>
|
||
<h2 class="memtitle"><span class="permalink"><a href="#acae06d4f1500d591e6d86b9d52d29a84">◆ </a></span>IndexHeader3</h2>
|
||
|
||
<div class="memitem">
|
||
<div class="memproto">
|
||
<table class="memname">
|
||
<tr>
|
||
<td class="memname">typedef struct IndexHeader3 IndexHeader3</td>
|
||
</tr>
|
||
</table>
|
||
</div><div class="memdoc">
|
||
|
||
</div>
|
||
</div>
|
||
</div><!-- contents -->
|
||
</div><!-- doc-content -->
|
||
<div id="page-nav" class="page-nav-panel">
|
||
<div id="page-nav-resize-handle"></div>
|
||
<div id="page-nav-tree">
|
||
<div id="page-nav-contents">
|
||
</div><!-- page-nav-contents -->
|
||
</div><!-- page-nav-tree -->
|
||
</div><!-- page-nav -->
|
||
</div><!-- container -->
|
||
<!-- start footer part -->
|
||
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
<ul>
|
||
<li class="navelem"><a href="dir_d44c64559bbebec7f509842c48db8b23.html">include</a></li><li class="navelem"><a href="dir_aeff2545c9dfcfc842fe9d84b123cb31.html">aaruformat</a></li><li class="navelem"><a href="dir_6387aeb6e475a334d8dc12d69f21999e.html">structs</a></li><li class="navelem"><a href="index_8h.html">index.h</a></li>
|
||
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0 </li>
|
||
</ul>
|
||
</div>
|
||
</body>
|
||
</html>
|