<trclass="memdesc:a375a516fdf6f81e997365d93b21f6708"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Parse and integrate a Tracks block from the image stream into the context. <br/></td></tr>
<trclass="memdesc:a2ce65757ca5209f17d467c51ba7d445d"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Retrieve the array of track descriptors contained in an opened AaruFormat image. <br/></td></tr>
<trclass="memitem:a518d8d68debf1b9a24af3eb6bc2f9e49"id="r_a518d8d68debf1b9a24af3eb6bc2f9e49"><tdclass="memItemLeft"align="right"valign="top">int32_t </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="#a518d8d68debf1b9a24af3eb6bc2f9e49">aaruf_set_tracks</a> (void *context, <aclass="el"href="structTrackEntry.html">TrackEntry</a> *tracks, const int count)</td></tr>
<trclass="memdesc:a518d8d68debf1b9a24af3eb6bc2f9e49"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Replace (or clear) the in-memory track table for an AaruFormat image context. <br/></td></tr>
<p>Retrieve the array of track descriptors contained in an opened AaruFormat image. </p>
<p>Provides the caller with a contiguous array of all track entries found in the image. The function follows a two-step usage pattern allowing callers to query the required buffer size before performing the actual copy.</p>
<p>Usage pattern:</p><ul>
<li>First call with buffer == NULL (or *length smaller than required). The function sets *length to the required size and returns AARUF_ERROR_BUFFER_TOO_SMALL.</li>
<li>Allocate a buffer of at least *length bytes and call again. On success, the function copies all <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures and returns AARUF_STATUS_OK with *length set to the bytes copied.</li>
</ul>
<p>The returned data is a raw copy of internal <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures (host endianness). The caller does not assume ownership of internal memory; only the caller-provided buffer should be freed by the caller.</p>
context is a valid pointer to an aaruformatContext previously returned by an open function.<ul>
<li></li>
</ul>
</dd>
<dd>
context->magic == AARU_MAGIC.<ul>
<li></li>
</ul>
</dd>
<dd>
<aclass="el"href="#a375a516fdf6f81e997365d93b21f6708"title="Parse and integrate a Tracks block from the image stream into the context.">process_tracks_block()</a> has run (implicitly done during image open) populating trackEntries.</dd></dl>
<p>Thread safety:</p><ul>
<li>Read-only access; safe for concurrent calls on different contexts.</li>
<li>Concurrent calls on the same context are safe only if no other thread is modifying/destroying it.</li>
<li>Validation failures: return specific error codes and log through <aclass="el"href="log_8h.html#a053d6037d543b84ce59308ce71d15cd1">FATAL()</a>/TRACE().</li>
<li>No partial copies are performed.</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Opaque pointer that MUST point to a valid aaruformatContext. </td></tr>
<tr><tdclass="paramname">buffer</td><td>Destination buffer for a copy of all <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures, or NULL to query size. </td></tr>
<tr><tdclass="paramname">length</td><td>In/Out: On entry capacity of buffer (ignored if buffer == NULL). On return required or copied size in bytes. Must not be NULL.</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>int32_t API status code. </dd></dl>
<li>Invoke aaruf_get_tracks(ctx, buffer, &size) again; on AARUF_STATUS_OK iterate over (size / sizeof(TrackEntry)) entries.</li>
<li>Free the buffer and close the image when done. </li>
</ol>
<pclass="definition">Definition at line <aclass="el"href="optical_8c_source.html#l00281">281</a> of file <aclass="el"href="optical_8c_source.html">optical.c</a>.</p>
<p>Replace (or clear) the in-memory track table for an AaruFormat image context. </p>
<p>Copies an array of caller-provided <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures into the internal context, replacing any previously stored track metadata. A CRC64 is recomputed over the new table and stored in the associated <aclass="el"href="structTracksHeader.html"title="Header for an optical tracks block listing track entries.">TracksHeader</a>. Passing a count of 0 clears existing track information.</p>
<p>Typical usage:</p><ul>
<li>Prepare an array of <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures describing each track (filled by the caller).</li>
<li>Call <aclass="el"href="#a518d8d68debf1b9a24af3eb6bc2f9e49"title="Replace (or clear) the in-memory track table for an AaruFormat image context.">aaruf_set_tracks()</a> with the array and the track count to load them into the context.</li>
<li>Subsequently the table can be retrieved with <aclass="el"href="#a2ce65757ca5209f17d467c51ba7d445d"title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a>.</li>
</ul>
<p>Memory ownership:</p><ul>
<li>The function allocates (or frees when clearing) internal storage sized to (count * sizeof(TrackEntry)).</li>
<li>The caller retains ownership of the input array (if any) and may free or reuse it after the call.</li>
</ul>
<p>Validation performed:</p><ul>
<li><codeclass="param">context</code> must be non-NULL and reference aaruformatContext with magic == AARU_MAGIC.</li>
<li><codeclass="param">tracks</code> must be non-NULL when <codeclass="param">count</code>> 0.</li>
<li><codeclass="param">count</code> must be >= 0. (Negative values produce AARUF_ERROR_INVALID_TRACK_FORMAT.)</li>
<li>(Implementation detail) count is truncated to uint16_t for header storage; values > UINT16_MAX will silently wrap. Callers should ensure count <= 65535. This behavior may change in a future version.</li>
</ul>
<p>Concurrency & thread-safety:</p><ul>
<li>Not thread-safe. Mutates shared context state. External synchronization is required if multiple threads access the same context.</li>
</ul>
<p>Side effects:</p><ul>
<li>Frees any existing internal track table before allocating the new one.</li>
<li>When clearing (count == 0) sets header to zero and frees internal table.</li>
</ul>
<p>Error handling & atomicity:</p><ul>
<li>On allocation failure the previous track table is already freed (non-atomic replace) and the header is zeroed (no partial new state left). Caller must repopulate.</li>
<li>No partial copies: either all tracks are stored or none.</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Opaque pointer that MUST point to a valid aaruformatContext returned by an open/create call. </td></tr>
<tr><tdclass="paramname">tracks</td><td>Pointer to an array of <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures to copy. Must not be NULL if count > 0. Ignored (may be NULL) when count == 0. </td></tr>
<tr><tdclass="paramname">count</td><td>Number of <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> elements in <codeclass="param">tracks</code>. If 0, existing tracks are cleared. Must be >= 0 and (recommended) <= UINT16_MAX.</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>int32_t API status code indicating success or the nature of the failure. </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>Success (tracks replaced or cleared). </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td><codeclass="param">context</code> is NULL or not a recognized libaaruformat context. </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_INVALID_TRACK_FORMAT</td><td>Invalid input (tracks NULL with count > 0, or count < 0). </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>Memory allocation failed while copying tracks.</td></tr>
</table>
</dd>
</dl>
<dlclass="section warning"><dt>Warning</dt><dd>Not thread-safe. Do not invoke concurrently with readers/writers of the same context. </dd></dl>
<dlclass="section note"><dt>Note</dt><dd>After success, <aclass="el"href="#a2ce65757ca5209f17d467c51ba7d445d"title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a> can be used to read back the stored table. </dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#a2ce65757ca5209f17d467c51ba7d445d"title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a></dd></dl>
<li>Prepare an array of <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> structures (N elements) and fill the fields.</li>
<li>Call aaruf_set_tracks(ctx, array, N) to store them; check for AARUF_STATUS_OK.</li>
<li>To clear all tracks later call aaruf_set_tracks(ctx, NULL, 0).</li>
<li>Use <aclass="el"href="#a2ce65757ca5209f17d467c51ba7d445d"title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a> afterwards to retrieve them if needed. </li>
</ol>
<pclass="definition">Definition at line <aclass="el"href="optical_8c_source.html#l00392">392</a> of file <aclass="el"href="optical_8c_source.html">optical.c</a>.</p>
<p>Parse and integrate a Tracks block from the image stream into the context. </p>
<p>This function seeks to the byte offset specified by the supplied <codeclass="param">entry</code>, reads a <aclass="el"href="structTracksHeader.html"title="Header for an optical tracks block listing track entries.">TracksHeader</a> followed by the declared number of <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> records, validates the block through its CRC64, and populates multiple fields in the provided <codeclass="param">ctx:</code></p>
<li>ctx->trackEntries (raw array with ALL tracks in on-disk order)</li>
<li>ctx->dataTracks (array filtered to data track sequences in [1..99])</li>
<li>ctx->numberOfDataTracks</li>
<li>ctx->imageInfo.ImageSize (incremented by sizeof(TrackEntry) * entries)</li>
<li>ctx->imageInfo.HasPartitions / HasSessions (both set true unconditionally on success path before filtering)</li>
</ul>
<p>It also performs a legacy endian correction of the computed CRC for images whose major version is <= AARUF_VERSION_V1 (historical writer quirk).</p>
<p>The function is intended for internal library use during image opening / indexing and is NOT part of the stable public API (no versioning guarantees). Callers outside the library should use the higher-level image open helpers that trigger this parsing implicitly.</p>
<p>Error & early-return behavior (no exception mechanism, all via logging + early return):</p><ul>
<li>NULL <codeclass="param">ctx</code> or NULL ctx->imageStream: Logs FATAL and returns immediately; context left untouched.</li>
<li>Seek failure: FATAL + return; context left untouched.</li>
<li><aclass="el"href="structTracksHeader.html"title="Header for an optical tracks block listing track entries.">TracksHeader</a> read short: tracksHeader zeroed, TRACE logged, return.</li>
<li>CRC mismatch: TRACE logged and return; (NOTE: at this point trackEntries remain allocated and tracksHeader retains the just-read values, but caller receives no explicit status.)</li>
</ul>
<p>Memory management:</p><ul>
<li>Allocates ctx->trackEntries with malloc() sized to entries * sizeof(TrackEntry).</li>
<li>Allocates ctx->dataTracks only if at least one filtered data track is found; otherwise sets it to NULL.</li>
<li>On certain failure paths (short reads) allocated memory is freed; on CRC mismatch memory is kept.</li>
<li>Pre-existing ctx->trackEntries or ctx->dataTracks are NOT freed before overwriting pointers, so repeated calls without prior cleanup will leak memory. The function is therefore expected to be called exactly once per context lifetime. This constraint should be observed by library code.</li>
</ul>
<p>Filtering rule for ctx->dataTracks:</p><ul>
<li>Any <aclass="el"href="structTrackEntry.html"title="Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).">TrackEntry</a> with sequence in inclusive range [1, 99] is considered a data track (historical convention in format) and copied into ctx->dataTracks preserving original order.</li>
</ul>
<p>Thread safety:</p><ul>
<li>Not thread-safe: mutates shared state in <codeclass="param">ctx</code> without synchronization.</li>
<li>Must not be called concurrently with readers/writers referencing the same context.</li>
<li>imageInfo flags (HasPartitions, HasSessions) set true</li>
</ul>
</dd></dl>
<p>Limitations / Caveats:</p><ul>
<li>No explicit status code: callers infer success by inspecting ctx->tracksHeader.entries and presence of ctx->trackEntries after invocation.</li>
<li>In case of CRC mismatch trackEntries are retained though not guaranteed trustworthy; caller may wish to discard them or trigger re-read.</li>
<li>Potential memory leak if invoked multiple times without freeing previous arrays.</li>
</ul>
<p>Logging strategy:</p><ul>
<li>FATAL used for unrecoverable structural or resource errors.</li>
<li>TRACE used for informational / soft failures (e.g., CRC mismatch, identifier mismatch, short read).</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Mutable pointer to an aaruformatContext receiving parsed track metadata. </td></tr>
<tr><tdclass="paramname">entry</td><td>Pointer to the index entry describing this Tracks block (offset required; size not strictly used beyond informational logging and sequential reading).</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>void This function does not return a status code; errors are reported via logging side effects.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>Not idempotent and not leak-safe if called more than once for a context. </dd>
<dd>
Absence of a returned status requires defensive post-call validation by the caller. </dd>
<dd>
CRC mismatch leaves possibly invalid data in ctx->trackEntries.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#a2ce65757ca5209f17d467c51ba7d445d"title="Retrieve the array of track descriptors contained in an opened AaruFormat image.">aaruf_get_tracks()</a></dd>
<dd>
<aclass="el"href="#a518d8d68debf1b9a24af3eb6bc2f9e49"title="Replace (or clear) the in-memory track table for an AaruFormat image context.">aaruf_set_tracks()</a></dd></dl>
<pclass="definition">Definition at line <aclass="el"href="optical_8c_source.html#l00111">111</a> of file <aclass="el"href="optical_8c_source.html">optical.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>
