Struct ReadOptions 

pub struct ReadOptions { /* private fields */ }

Sector format, retry policy, and read speed options for track, streaming, and sector-range reads.

The defaults read audio sectors using the default retry policy and leave the drive’s current read speed unchanged. Use the builder methods to override only the options you need.

Implementations

impl ReadOptions

pub fn with_format(self, format: SectorReadFormat) -> Self

Select the sector format requested from the drive.

Examples found in repository

examples/save_data_track.rs (line 99)

fn stream_track_to_file(
    reader: &CdReader,
    toc: &Toc,
    track_no: u8,
    format: SectorReadFormat,
    path: &Path,
) -> Result<u64, Box<dyn std::error::Error>> {
    let options = ReadOptions::default().with_format(format);
    let mut stream = reader.open_track_stream_with_options(toc, track_no, &options)?;

    let total_sectors = stream.total_sectors();
    let mut writer = BufWriter::new(File::create(path)?);
    let mut written = 0u64;

    while let Some(chunk) = stream.next_chunk()? {
        writer.write_all(&chunk)?;
        written += chunk.len() as u64;

        let done = stream.current_sector();
        let pct = done as f32 / total_sectors as f32 * 100.0;
        eprint!("\r  {done}/{total_sectors} sectors ({pct:5.1}%)");
    }
    eprintln!("\r  {total_sectors}/{total_sectors} sectors (100.0%)");

    writer.flush()?;
    Ok(written)
}

examples/read_data_track.rs (line 33)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = CdReader::open_default()?;
    let toc = reader.read_toc()?;

    let data_track = toc
        .tracks
        .iter()
        .find(|t| !t.is_audio)
        .ok_or("no data track on this disc (need a mixed-mode / enhanced CD)")?;

    let pvd_lba = data_track.start_lba + PVD_SECTOR_OFFSET;
    println!(
        "Data track #{} starts at LBA {}; reading PVD at LBA {}\n",
        data_track.number, data_track.start_lba, pvd_lba
    );

    let mut options = ReadOptions::default().with_format(SectorReadFormat::Mode1Raw);

    // --- raw read (2352 B) -------------------------------------------------
    let raw = reader.read_sector_range(pvd_lba, 1, &options)?;
    if raw.len() != 2352 {
        return Err(format!("raw read returned {} bytes, expected 2352", raw.len()).into());
    }

    let sync_ok = raw[0] == 0x00 && raw[1..11].iter().all(|&b| b == 0xFF) && raw[11] == 0x00;
    let mode = raw[15];
    println!("raw sync pattern : {}", pass(sync_ok));
    println!("raw sector mode  : Mode {mode}");

    // User data sits after sync(12) + header(4) for Mode 1, and additionally
    // after an 8-byte subheader for Mode 2 Form 1.
    let user_offset = match mode {
        1 => 16,
        2 => 24,
        other => return Err(format!("unexpected sector mode {other}").into()),
    };
    let raw_user = &raw[user_offset..user_offset + 2048];

    let iso_ok = raw_user[0] == 0x01 && &raw_user[1..6] == b"CD001";
    println!("ISO 9660 'CD001' : {}", pass(iso_ok));

    // --- cooked read (2048 B) ---------------------------------------------
    // The cooked format is specifically Mode 1, so only cross-check it there.
    if mode == 1 {
        options = options.with_format(SectorReadFormat::Mode1Cooked);
        let cooked = reader.read_sector_range(pvd_lba, 1, &options)?;
        if cooked.len() != 2048 {
            return Err(
                format!("cooked read returned {} bytes, expected 2048", cooked.len()).into(),
            );
        }
        let matches_raw = cooked == raw_user;
        println!("cooked == raw[16..]: {}", pass(matches_raw));

        if sync_ok && iso_ok && matches_raw {
            println!("\nALL CHECKS PASSED — cooked and raw data reads are correct.");
            return Ok(());
        }
    } else {
        println!(
            "\nData track is Mode {mode} (e.g. CD-Extra / Mode 2 Form 1). The cooked path \
             targets Mode 1, so only the raw checks apply here."
        );
        if sync_ok && iso_ok {
            println!("Raw read verified against on-disc ISO structure.");
            return Ok(());
        }
    }

    Err("one or more verification checks FAILED — see output above".into())
}

pub fn with_retry(self, retry: RetryConfig) -> Self

Set the retry policy applied to each read command.

Examples found in repository

examples/custom_retry.rs (line 31)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let output_dir = common::fresh_output_dir("custom_retry")?;
    let reader = CdReader::open_default()?;
    let toc = reader.read_toc()?;

    let first_audio = toc
        .tracks
        .iter()
        .find(|t| t.is_audio)
        .ok_or("no audio tracks found")?;

    // More attempts, longer backoff, and sector reduction down to 1
    // for maximum resilience on scratched media.
    let retry = RetryConfig::default()
        .with_max_attempts(8)
        .with_initial_backoff(Duration::from_millis(50))
        .with_max_backoff(Duration::from_secs(1))
        .with_chunk_reduction(true)
        .with_min_sectors_per_read(1);
    let options = ReadOptions::default().with_retry(retry);

    println!(
        "Reading track {} with aggressive retry...",
        first_audio.number
    );
    let data = reader.read_track_with_options(&toc, first_audio.number, &options)?;

    let wav = create_wav(data);
    let output_path = output_dir.join(format!("track{:02}.wav", first_audio.number));
    std::fs::write(&output_path, wav)?;
    println!("Saved {}", output_path.display());

    Ok(())
}

pub fn with_read_speed(self, read_speed: ReadSpeed) -> Self

Set the read speed to request from the drive. See ReadSpeed for details. Streaming reads apply this request once when the stream is opened.

Note

For simplicity, this crate doesn’t restore the previous speed setting.

Examples found in repository

examples/read_speed.rs (line 36)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = CdReader::open_default()?;
    let toc = reader.read_toc()?;

    let first_audio = toc
        .tracks
        .iter()
        .find(|track| track.is_audio)
        .ok_or("no audio tracks found")?;

    // Keep "unchanged" immediately after 1x so it tests whether the previous speed
    // request remains in effect when no new speed command is sent.
    let speed_tests = [
        ("1x", ReadSpeed::CustomMultiplier(1)),
        ("unchanged (after 1x)", ReadSpeed::Unchanged),
        ("10x", ReadSpeed::CustomMultiplier(10)),
        ("30x", ReadSpeed::CustomMultiplier(30)),
        ("optimal", ReadSpeed::Optimal),
    ];

    println!(
        "Reading audio track {} {} times\n",
        first_audio.number,
        speed_tests.len()
    );

    let mut timings = Vec::with_capacity(speed_tests.len());

    for (label, read_speed) in speed_tests {
        let options = ReadOptions::default().with_read_speed(read_speed);

        println!("Reading at {label}...");
        let started = Instant::now();
        let data = reader.read_track_with_options(&toc, first_audio.number, &options)?;
        let elapsed = started.elapsed();

        println!(
            "Read {} bytes in {:.3} seconds\n",
            data.len(),
            elapsed.as_secs_f64()
        );
        timings.push((label, elapsed));
    }

    println!("Timing summary:");
    for (label, elapsed) in timings {
        println!("  {label:<22} {:>10.3} seconds", elapsed.as_secs_f64());
    }

    Ok(())
}

Trait Implementations

impl Clone for ReadOptions

fn clone(&self) -> ReadOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ReadOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ReadOptions

fn default() -> Self

Returns the “default value” for a type.