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
f53092c9419c23941c845940125d0d3b580f415b
libaaruformat/docs/html/header_8h.html

238 lines
13 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: include/aaruformat/structs/header.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">&#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('header_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">header.h File Reference</div></div>
</div><!--header-->
<div class="contents">
<p>On-disk container header structures (v1 and v2) for Aaru images.
<a href="#details">More...</a></p>
<p><a href="header_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:AaruHeader" id="r_AaruHeader"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structAaruHeader.html">AaruHeader</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Version 1 container header placed at offset 0 for legacy / initial format. <a href="structAaruHeader.html#details">More...</a><br /></td></tr>
<tr class="memitem:AaruHeaderV2" id="r_AaruHeaderV2"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structAaruHeaderV2.html">AaruHeaderV2</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Version 2 container header with GUID, alignment shifts, and feature negotiation bitmaps. <a href="structAaruHeaderV2.html#details">More...</a><br /></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-define-members" class="groupheader"><a id="define-members" name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ab17964dacc36dca03ec5e75aa40a4502" id="r_ab17964dacc36dca03ec5e75aa40a4502"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ab17964dacc36dca03ec5e75aa40a4502">AARU_HEADER_APP_NAME_LEN</a>&#160;&#160;&#160;64</td></tr>
<tr class="memdesc:ab17964dacc36dca03ec5e75aa40a4502"><td class="mdescLeft">&#160;</td><td class="mdescRight">Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units). <br /></td></tr>
<tr class="memitem:a57c99b24137b82f12950e79ffbd2fb7a" id="r_a57c99b24137b82f12950e79ffbd2fb7a"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a57c99b24137b82f12950e79ffbd2fb7a">GUID_SIZE</a>&#160;&#160;&#160;16</td></tr>
<tr class="memdesc:a57c99b24137b82f12950e79ffbd2fb7a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Size in bytes of GUID / UUID-like binary identifier. <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:a92b4759381b275f18e8d66617bcefdfa" id="r_a92b4759381b275f18e8d66617bcefdfa"><td class="memItemLeft" align="right" valign="top">typedef struct AaruHeader&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a92b4759381b275f18e8d66617bcefdfa">AaruHeader</a></td></tr>
<tr class="memitem:a369effc2c0aea490cf0309c686ce54c6" id="r_a369effc2c0aea490cf0309c686ce54c6"><td class="memItemLeft" align="right" valign="top">typedef struct AaruHeaderV2&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a369effc2c0aea490cf0309c686ce54c6">AaruHeaderV2</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 container header structures (v1 and v2) for Aaru images. </p>
<p>These packed headers appear at the very beginning (offset 0) of every Aaru image file and advertise container format version, creator application, indexing offset and optional extended feature capability bitfields (v2+). All multi-byte integers are little-endian. Strings stored in the fixed-size application field are UTF‑16LE and zero padded (not necessarily NUL-terminated if fully filled). The GUID field (v2) allows derivative / child images to reference an origin.</p>
<p>Version progression:</p><ul>
<li>v1: <a class="el" href="structAaruHeader.html">AaruHeader</a> (no GUID, no alignment or shift metadata, no feature bitfields).</li>
<li>v2: <a class="el" href="structAaruHeaderV2.html">AaruHeaderV2</a> introduces GUID, block/data/table shift hints (mirroring DDT metadata), and three 64‑bit feature bitmaps to negotiate reader/writer compatibility.</li>
</ul>
<p>Compatibility handling (recommended logic for consumers):</p><ol type="1">
<li>If any bit set in featureIncompatible is not implemented by the reader: abort (cannot safely read/write).</li>
<li>Else if any bit set in featureCompatibleRo is not implemented: allow read‑only operations.</li>
<li>Bits only present in featureCompatible but not implemented MAY be ignored for both read/write while still preserving round‑trip capability (writer should not clear unknown bits when re‑saving).</li>
</ol>
<p>Alignment &amp; shift semantics (duplicated here for quick reference, see <a class="el" href="structDdtHeader2.html" title="Header preceding a version 2 hierarchical deduplication table.">DdtHeader2</a> for full details):</p><ul>
<li>blockAlignmentShift: underlying blocks are aligned to 2^blockAlignmentShift bytes.</li>
<li>dataShift: data pointer / DDT entry low bits encode offsets modulo 2^dataShift sectors/items.</li>
<li>tableShift: primary DDT entries span 2^tableShift logical sectors (0 implies single-level tables).</li>
</ul>
<p>Invariants:</p><ul>
<li>identifier == AARU_MAGIC (external constant; not defined here).</li>
<li>For v1: sizeof(AaruHeader) exact and indexOffset &gt; 0 (indexOffset == 0 =&gt; corrupt/unreadable image).</li>
<li>For v2: sizeof(AaruHeaderV2) exact; indexOffset &gt; 0; blockAlignmentShift, dataShift, tableShift within sane bounds (e.g. &lt; 63). Zero is permissible only for the shift fields (not for indexOffset).</li>
</ul>
<p>Security / robustness considerations:</p><ul>
<li>Always bounds-check indexOffset against file size before seeking.</li>
<li>Treat application field as untrusted UTF‑16LE; validate surrogate pairs if necessary.</li>
<li>Unknown feature bits MUST be preserved if a file is rewritten to avoid capability loss. </li>
</ul>
<p class="definition">Definition in file <a class="el" href="header_8h_source.html">header.h</a>.</p>
</div><a name="doc-define-members" id="doc-define-members"></a><h2 id="header-doc-define-members" class="groupheader">Macro Definition Documentation</h2>
<a id="ab17964dacc36dca03ec5e75aa40a4502" name="ab17964dacc36dca03ec5e75aa40a4502"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ab17964dacc36dca03ec5e75aa40a4502">&#9670;&#160;</a></span>AARU_HEADER_APP_NAME_LEN</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define AARU_HEADER_APP_NAME_LEN&#160;&#160;&#160;64</td>
</tr>
</table>
</div><div class="memdoc">
<p>Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units). </p>
<p class="definition">Definition at line <a class="el" href="header_8h_source.html#l00059">59</a> of file <a class="el" href="header_8h_source.html">header.h</a>.</p>
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>, and <a class="el" href="open_8c_source.html#l00125">aaruf_open()</a>.</p>
</div>
</div>
<a id="a57c99b24137b82f12950e79ffbd2fb7a" name="a57c99b24137b82f12950e79ffbd2fb7a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a57c99b24137b82f12950e79ffbd2fb7a">&#9670;&#160;</a></span>GUID_SIZE</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define GUID_SIZE&#160;&#160;&#160;16</td>
</tr>
</table>
</div><div class="memdoc">
<p>Size in bytes of GUID / UUID-like binary identifier. </p>
<p class="definition">Definition at line <a class="el" href="header_8h_source.html#l00060">60</a> of file <a class="el" href="header_8h_source.html">header.h</a>.</p>
Updated documentation.
2025-10-13 14:26:33 +01:00
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>.</p>
Add doxygen documentation
2025-10-11 01:35:43 +01:00
</div>
</div>
<a name="doc-typedef-members" id="doc-typedef-members"></a><h2 id="header-doc-typedef-members" class="groupheader">Typedef Documentation</h2>
<a id="a92b4759381b275f18e8d66617bcefdfa" name="a92b4759381b275f18e8d66617bcefdfa"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a92b4759381b275f18e8d66617bcefdfa">&#9670;&#160;</a></span>AaruHeader</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct AaruHeader AaruHeader</td>
</tr>
</table>
</div><div class="memdoc">
</div>
</div>
<a id="a369effc2c0aea490cf0309c686ce54c6" name="a369effc2c0aea490cf0309c686ce54c6"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a369effc2c0aea490cf0309c686ce54c6">&#9670;&#160;</a></span>AaruHeaderV2</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct AaruHeaderV2 AaruHeaderV2</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="header_8h.html">header.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>
Reference in New Issue Copy Permalink