libfreemkv

https://docs.rs/libfreemkv/1.1.0/libfreemkv/
Admin
libfreemkv is an open-source optical drive library designed for 4K UHD, Blu-ray, and DVD, providing...
Tokens:338,742
Snippets:3,623
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Getting File Metadata with and_then

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/error/type.Result.html

This example demonstrates using `and_then` to chain file system operations, specifically getting metadata and then the modification time. It shows how to handle both successful and failed operations, like accessing a non-existent path.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Box::new Example

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Demonstrates creating a boxed value using `Box::new` and comparing it with a value created using `Box::from`.

```rust
let x = 5;
let boxed = Box::new(5);

assert_eq!(Box::from(x), boxed);
```

--------------------------------

### Quick Start: Accessing and Scanning a Disc

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/index.html

This snippet demonstrates how to find an optical drive, initialize it, scan for disc titles, and print basic information about each title. It requires the `libfreemkv` crate.

```rust
use libfreemkv::{Drive, Disc, ScanOptions, find_drive};

let mut drive = find_drive().expect("no optical drive found");
drive.wait_ready().unwrap();
drive.init().unwrap();
let disc = Disc::scan(&mut drive, &ScanOptions::default()).unwrap();

for title in &disc.titles {
    println!("{} -- {} streams", title.duration_display(), title.streams.len());
}
```

--------------------------------

### Mapfile Format Example

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/mapfile/index.html

Illustrates the expected format of a ddrescue-compatible mapfile, including header and data line structures.

```text
# Rescue Logfile. Created by libfreemkv vX.Y.Z
# Current pos / status / pass / pass_time (ddrescue state machine — we only populate pos)
0x000000000  ?  1  0
#      pos        size  status
0x000000000  0x12345678    +
0x012345678  0x00001000    -
0x012346678  0x01234500    ?
```

--------------------------------

### Box::try_clone_from_ref_in Example

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Demonstrates cloning a Box<str, System> from a reference within a specified allocator.

```rust
let hello: Box<str, System> = Box::try_clone_from_ref_in("hello", System)?;
```

--------------------------------

### Clone Example for Arc<T, A>

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/decrypting/type.KeyFetch.html

Demonstrates cloning an `Arc` pointer, which increases the strong reference count and points to the same allocation.

```rust
use std::sync::Arc;

let five = Arc::new(5);

let _ = Arc::clone(&five);
```

--------------------------------

### Create an Empty ResolutionTrace

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/trace/struct.ResolutionTrace.html

Instantiates a new, empty ResolutionTrace with no steps recorded. Use this when starting a new resolution process.

```rust
pub fn new() -> Self
```

--------------------------------

### Get Metadata Partition Start Sector

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/struct.UdfFs.html

Retrieves the starting sector of the metadata partition for a UdfFs instance.

```rust
pub fn metadata_start(&self) -> u32
```

--------------------------------

### Get Physical Partition Start Sector

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/struct.UdfFs.html

Retrieves the starting sector of the physical partition for a UdfFs instance.

```rust
pub fn partition_start(&self) -> u32
```

--------------------------------

### Input/Output: Reading from ISO and Writing to MKV

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/index.html

This example shows how to use libfreemkv for input and output operations. It reads from an ISO file and writes to an MKV file, propagating read errors. Ensure the `input` and `output` functions are available and correctly configured.

```rust
let opts = libfreemkv::InputOptions::default();
let mut input = libfreemkv::input("iso://disc.iso", &opts)?;
let title = input.info().clone();
let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
// Propagate read errors instead of silently stopping on the first one.
while let Some(frame) = input.read()? {
    output.write(&frame)?;
}
output.finish()?;
```

--------------------------------

### take

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Creates an adapter which will read at most limit bytes from it.

```APIDOC
## fn take(self, limit: u64) -> Take<Self>

### Description
Creates an adapter which will read at most `limit` bytes from it.

### Parameters
* `limit` - (u64) - The maximum number of bytes to read.
```

--------------------------------

### Get HDR Format Short Name

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/diag/fn.hdr_str.html

Use this function to get the static string representation of an HdrFormat enum. No setup or imports are required beyond having the HdrFormat type available.

```rust
pub fn hdr_str(h: HdrFormat) -> &'static str
```

--------------------------------

### Get File Start LBA

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/struct.UdfFs.html

Locates the absolute starting Logical Block Address (LBA) of a file's first data extent on disc. This is crucial for the rip pipeline to find m2ts content sectors.

```rust
pub fn file_start_lba( 
    &self,
    reader: &mut dyn SectorSource,
    path: &str,
) -> Result<u32>
```

--------------------------------

### init

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Initializes a Drive instance at a given memory pointer.

```APIDOC
## unsafe fn init(init: <T as Pointable>::Init) -> usize

### Description
Initializes a with the given initializer.

### Method
POST (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
- **init** (<T as Pointable>::Init): The initializer for the Drive instance.

### Response
#### Success Response
- **usize**: The memory address where the Drive instance was initialized.
```

--------------------------------

### mkb_version

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/keys/fn.mkb_version.html

Get MKB version from Type and Version Record (type 0x10). Layout: 4-byte record header at `pos` (type + BE24 length), then the record body starts at `pos + 4`. The body holds the BE u32 Type field at body offset 0 (`pos + 4`), then the BE u32 version at body offset 4 (`pos + 8`).

```APIDOC
## Function mkb_version

### Description
Get MKB version from Type and Version Record (type 0x10). Layout: 4-byte record header at `pos` (type + BE24 length), then the record body starts at `pos + 4`. The body holds the BE u32 Type field at body offset 0 (`pos + 4`), then the BE u32 version at body offset 4 (`pos + 8`).

### Signature
```rust
pub fn mkb_version(mkb: &[u8]) -> Option<u32>
```
```

--------------------------------

### samples Method

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/keysource/trait.ResolveCtx.html

Retrieves up to 'n' encrypted on-disc content sample units. Used for server-side validation against real ciphertext.

```rust
fn samples(&self, n: usize) -> Result<Vec<Vec<u8>>, Error>;
```

--------------------------------

### Get Configuration Feature

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Queries a specific GET CONFIGURATION feature by its code. Returns the feature data (excluding the header) if available, otherwise None.

```rust
pub fn get_config_feature(&mut self, feature_code: u16) -> Option<Vec<u8>>
```

--------------------------------

### init

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/types/struct.DiscEntry.html

Initializes a with the given initializer.

```APIDOC
## unsafe fn init(init: <T as Pointable>::Init) -> usize

### Description
Initializes a with the given initializer.

### Method
unsafe fn

### Parameters
- `init` (<T as Pointable>::Init) - The initializer for the type.

### Returns
- `usize` - The pointer to the initialized memory.
```

--------------------------------

### Get Drive Status

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Queries the physical status of the drive, such as disc presence and tray state. This method uses GET EVENT STATUS NOTIFICATION and works regardless of the drive's firmware state.

```rust
pub fn drive_status(&mut self) -> DriveStatus
```

--------------------------------

### Manually create Box from raw pointer with system allocator

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

This example demonstrates manually allocating memory using the system allocator and then constructing a Box from the raw pointer. Ensure proper initialization of the memory before creating the Box.

```rust
#![feature(allocator_api, slice_ptr_get)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, System);
}
```

--------------------------------

### CountingStream Usage Example

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/pes/struct.CountingStream.html

Wrap an output stream with CountingStream to track bytes written. Query bytes_written() for progress. This example shows reading frames from an input and writing them to the CountingStream, calculating progress percentage.

```rust
let mut output = CountingStream::new(libfreemkv::output(dest, &title)?);
while let Ok(Some(frame)) = input.read() {
    output.write(&frame)?;
    let pct = output.bytes_written() as f64 / total as f64;
}
```

--------------------------------

### Drive::init

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Initializes the drive, performing unlock and firmware upload if necessary. This optional step enables features like UHD reads and speed control, but may affect compatibility with stock CSS authentication for DVDs.

```APIDOC
## Drive::init

### Description
Initialize drive — unlock + firmware upload. Optional. Adds features: removes riplock, enables UHD reads, speed control.
The LibreDrive/OEM firmware unlock is required for BD/UHD (AACS) reads, but it puts the drive in an extended-access state where stock CSS authentication no longer works — so a CSS-protected DVD can’t be read. For a DVD we therefore SKIP the unlock and run the drive in its normal stock mode; the DVD path then issues standard CSS commands, which a stock drive honors. BD/UHD and any non-DVD/unknown media keep today’s behavior.

### Method
`pub fn init(&mut self) -> Result<()>`

### Response
#### Success Response
- **()** - Indicates successful initialization.
#### Error Response
- **Result** - An error if initialization fails.

```

--------------------------------

### open

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/scsi/fn.open.html

Opens a SCSI transport for the given device path, automatically selecting the appropriate backend for the current platform.

```APIDOC
## open

### Description
Opens a SCSI transport for the given device path. Selects the right backend for the current platform.

### Function Signature
```rust
pub fn open(device: &Path) -> Result<Box<dyn ScsiTransport>>
```

### Parameters
#### Path Parameters
- **device** (*&Path*) - Required - The path to the SCSI device.

### Returns
- **Result<Box<dyn ScsiTransport>>** - A `Result` containing a boxed `ScsiTransport` trait object on success, or an error on failure.
```

--------------------------------

### type_id

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/types/struct.DiscEntry.html

Gets the `TypeId` of `self`.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
fn

### Parameters
- `self` (Self) - The instance to get the TypeId from.

### Returns
- `TypeId` - The unique identifier for the type of `self`.
```

--------------------------------

### Init

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/pes/struct.PesFrame.html

The type for initializers.

```APIDOC
## type Init = T

### Description
The type for initializers.

### Parameters
None

### Returns
- T: The type used for initializers.
```

--------------------------------

### Any for T

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/variants/struct.ProcessingKeyMatch.html

Provides the `type_id` method to get the `TypeId` of an object.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Parameters
None

### Returns
- `TypeId`: The unique identifier for the type of `self`.
```

--------------------------------

### from

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Creates a Drive instance from a given value of the same type. This is a direct conversion.

```APIDOC
## fn from(t: T) -> T

### Description
Returns the argument unchanged.

### Method
POST (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
- **t** (T): The value to be converted into a Drive instance.

### Response
#### Success Response
- **T**: A Drive instance created from the input value.
```

--------------------------------

### resolve_feature_start

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/dvdnav/fn.resolve_feature_start.html

Resolves the feature title's true start cell (0-based index into the title PGC's cell list) by following the disc's navigation. This allows playback to begin at the actual movie start, bypassing any introductory segments.

```APIDOC
## resolve_feature_start

### Description
Resolves the feature title's **true start cell** (0-based index into the title PGC’s cell list) by following the disc’s own navigation — First-Play → menu “Play” → title dispatch — the way a player reaches the movie. This is what lets the rip begin at the feature instead of at raw cell 0 when the disc’s nav enters the title past a leading logo/warning segment (e.g. a disc whose “Play” resolves to a later cell than cell 0).

Returns `None` when navigation cannot be resolved, so the caller falls back to the structural leading-cell filter (today’s behaviour, ≈ cell 0 / 0:00).

TODO(#40): the IFO/PCI parsing + nav executor (built on `vmcmd`) land incrementally. Until the executor is complete this returns `None`, so wiring it in is behaviour-neutral; improvements to the resolver take effect here without touching the call site.

### Function Signature
```rust
pub fn resolve_feature_start(
    reader: &mut dyn SectorSource,
    udf: &UdfFs,
    vtsn: u16,
    vts_ttn: u16,
) -> Option<usize>
```

### Parameters
#### Path Parameters
- **reader** (`&mut dyn SectorSource`) - Required - A mutable reference to a `SectorSource` trait object for reading disc sectors.
- **udf** (`&UdfFs`) - Required - A reference to the `UdfFs` structure representing the UDF file system.
- **vtsn** (`u16`) - Required - The Video Title Set Number.
- **vts_ttn** (`u16`) - Required - The Video Title Set Title Number.

### Returns
- `Option<usize>` - Returns `Some(usize)` containing the 0-based index of the true start cell if navigation can be resolved, otherwise returns `None`.
```

--------------------------------

### Resolve Feature Start Function Signature

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/dvdnav/fn.resolve_feature_start.html

This is the function signature for resolve_feature_start. It takes a mutable SectorSource reader, a UdfFs reference, and two u16 values representing the VTSN and VTS_TTN. It returns an Option<usize> which is the 0-based index of the feature's start cell.

```rust
pub fn resolve_feature_start(
    reader: &mut dyn SectorSource,
    udf: &UdfFs,
    vtsn: u16,
    vts_ttn: u16,
) -> Option<usize>
```

--------------------------------

### PipelinedPesStream::headers_ready Method

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/mux/pipelined_stream/struct.PipelinedPesStream.html

Indicates whether codec initialization data is available for all video tracks. Callers should buffer input frames until this returns true.

```rust
fn headers_ready(&self) -> bool
```

--------------------------------

### impl<T> Any for T

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/struct.Chapter.html

Provides the `type_id` method to get the `TypeId` of a type.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`fn`

### Parameters
None

### Response
- `TypeId`: The unique identifier for the type.
```

--------------------------------

### Create LocalFileSink with Size Hint

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/io/sink/struct.LocalFileSink.html

Creates a LocalFileSink and attempts to pre-allocate disk space for the file. This can help reduce fragmentation on Linux by reserving extents upfront. Failures in pre-allocation are non-fatal.

```rust
pub fn with_size_hint(path: &Path, size_bytes: u64) -> Result<Self>
```

--------------------------------

### type_id

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/io/byte_prefetcher/struct.BytePrefetcher.html

Gets the `TypeId` of `self`. This method is part of the blanket implementation of `Any`.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
N/A (Method within a trait implementation)

### Parameters
None

### Response
#### Success Response
- **TypeId**: The unique identifier for the type of `self`.
```

--------------------------------

### Get Device Path

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Retrieves the device path associated with the drive.

```rust
pub fn device_path(&self) -> &str
```

--------------------------------

### Initialize Drive

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Initializes the drive, which includes unlocking and potentially uploading firmware. This optional step enables features like UHD reads and speed control. It handles compatibility between stock CSS authentication for DVDs and the extended-access state required for BD/UHD media.

```rust
pub fn init(&mut self) -> Result<()>
```

--------------------------------

### impl<T> Any for T

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/read_error/enum.SenseFamily.html

Provides the `type_id` method to get the unique identifier of a type.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Parameters
None

### Returns
- `TypeId`: The unique type identifier.
```

--------------------------------

### Manually create Box from NonNull pointer with system allocator

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

This example shows how to manually allocate memory using the system allocator, cast it to a NonNull pointer, and then construct a Box. Proper initialization of the memory is crucial before creating the Box.

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let non_null = System.allocate(Layout::new::<i32>())?.cast::<i32>();
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null_in(non_null, System);
}
```

--------------------------------

### decrypt_threads

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/decrypt/index.html

Get the current effective number of threads used for decryption.

```APIDOC
## decrypt_threads

### Description
Current effective decrypt thread count. Resolution order:
1. The most recent `set_decrypt_threads` call with `n > 0`.
2. `FREEMKV_THREADS` env var, if set and `> 0`.
3. Default: all available cores.

### Method
(Not specified, assumed to be a function call within the library)

### Parameters
(None)

### Request Example
(Not specified in the source text)

### Response
(Not specified in the source text)
```

--------------------------------

### type_id

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/boil/struct.MediaKey.html

Gets the TypeId of the object. This method is part of the Any trait implementation.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`
```

--------------------------------

### ScsiSense::is_not_ready Check

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/scsi/struct.ScsiSense.html

Checks if the sense key is NOT READY (2), which can indicate issues like medium not present or the drive becoming ready.

```rust
pub fn is_not_ready(&self) -> bool
```

--------------------------------

### Box::new_uninit_in

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Constructs a new box with uninitialized contents in the provided allocator. This is a nightly-only experimental API.

```APIDOC
## pub fn new_uninit_in(alloc: A) -> Box<MaybeUninit<T>, A>

### Description
Constructs a new box with uninitialized contents in the provided allocator.

### Method
`new_uninit_in`

### Parameters
#### Path Parameters
- **alloc** (A) - Required - The allocator to use for memory allocation.

### Response
#### Success Response
- **Box<MaybeUninit<T>, A>** - A new box with uninitialized contents allocated using the provided allocator.

### Notes
This is a nightly-only experimental API. (`allocator_api`)
```

--------------------------------

### type_id

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/file/struct.FileSectorSink.html

Gets the `TypeId` of `self`. This method is part of the blanket implementation of `Any` for all types.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
(Implicitly called via trait method)

### Parameters
None

### Response
#### Success Response
- **TypeId**: The unique identifier for the type of `self`.
```

--------------------------------

### deref_mut

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Dereferences a Drive pointer to get a mutable reference to the Drive instance.

```APIDOC
## unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

### Description
Mutably dereferences the given pointer.

### Method
GET (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
- **ptr** (usize): The memory address of the Drive instance.

### Response
#### Success Response
- **&'a mut T**: A mutable reference to the Drive instance.
```

--------------------------------

### deref

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Dereferences a Drive pointer to get an immutable reference to the Drive instance.

```APIDOC
## unsafe fn deref<'a>(ptr: usize) -> &'a T

### Description
Dereferences the given pointer.

### Method
GET (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
- **ptr** (usize): The memory address of the Drive instance.

### Response
#### Success Response
- **&'a T**: An immutable reference to the Drive instance.
```

--------------------------------

### init

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/struct.SubtitleStream.html

Initializes a with the given initializer. Part of the `Pointable` trait.

```APIDOC
## unsafe fn init(init: <T as Pointable>::Init) -> usize

### Description
Initializes a with the given initializer.

### Method
`init`

### Parameters
- **init** (<T as Pointable>::Init): The initializer for the type.

### Response
#### Success Response (200)
- **usize**: The pointer to the initialized memory.
```

--------------------------------

### Create FviSink with Basic Source Info

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/mux/struct.FviSink.html

Creates an FviSink at the specified path, assembling the header from the provided DiscTitle's primary video stream. Use this when you have basic source path and title information.

```rust
pub fn create( path: &Path, title: &DiscTitle, source_path: String, source_title: usize, ) -> Result<Self>
```

--------------------------------

### type_id

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Gets the TypeId of the Drive instance. This is useful for runtime type identification.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
GET (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
None

### Response
#### Success Response
- **TypeId**: The unique identifier for the type of the Drive instance.
```

--------------------------------

### LocalFileSink::with_size_hint

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/io/sink/struct.LocalFileSink.html

Creates a LocalFileSink similar to `create`, but also attempts to pre-allocate disk space for the file. This can improve performance for large files by reducing fragmentation.

```APIDOC
## LocalFileSink::with_size_hint

### Description
Like `Self::create` but additionally calls the per-OS preallocate path with `size_bytes`. On Linux this is `fallocate(FALLOC_FL_KEEP_SIZE)` so the on-disk extents are reserved up front (reducing fragmentation for big sequential muxer output); on other OSes it is a no-op today. Failures from the preallocate call are non-fatal — the file is still returned, just without the size reservation.

### Signature
```rust
pub fn with_size_hint(path: &Path, size_bytes: u64) -> Result<Self>
```

### Parameters
* `path`: A reference to the `Path` representing the file to open.
* `size_bytes`: The suggested size in bytes to pre-allocate for the file.
```

--------------------------------

### DecryptingSectorSource::with_key_fetch

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/decrypting/struct.DecryptingSectorSource.html

Installs a KeyFetch callback to handle decryption of units with unknown keys.

```APIDOC
## DecryptingSectorSource::with_key_fetch

### Description
Install a `KeyFetch` callback: when a read holds scrambled AACS units that no current key decrypts, the decorator hands those units to `cb` and adds any keys it returns to the pool, then re-decrypts. Only meaningful for `DecryptKeys::Aacs`; ignored otherwise. The library makes no network call — `cb` is the application’s seam to its key source.

### Method
`with_key_fetch`

### Parameters
- `self` (DecryptingSectorSource<S>) - The current DecryptingSectorSource instance.
- `cb` (KeyFetch) - The KeyFetch callback to install.
```

--------------------------------

### Pointable::deref

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/struct.Clip.html

Dereferences the given pointer to get an immutable reference to the data. This is an unsafe operation.

```APIDOC
## unsafe fn deref<'a>(ptr: usize) -> &'a T

### Description
Dereferences the given pointer.

### Signature
unsafe fn deref<'a>(ptr: usize) -> &'a T
```

--------------------------------

### Mapfile::open_or_create

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/mapfile/struct.Mapfile.html

Loads a mapfile if it exists, otherwise creates a new one.

```APIDOC
## Mapfile::open_or_create

### Description
Load if the file exists, otherwise create a fresh mapfile.

### Method
`pub fn open_or_create(path: &Path, total_size: u64, version: &str) -> Result<Self>`

### Parameters
#### Path Parameters
- **path** (`&Path`) - Required - The path for the mapfile.
- **total_size** (`u64`) - Required - The total size of the mapfile.
- **version** (`&str`) - Required - The version string for the mapfile.

### Response
#### Success Response
- **Self** (`Result<Self>`) - The `Mapfile` instance, either loaded or newly created.
```

--------------------------------

### type_id

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/keys/struct.ResolveContext.html

Gets the `TypeId` of `self`. This method is part of the blanket implementation of `Any` for types that are `'static + ?Sized`.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Returns
- `TypeId`: The unique identifier for the type of `self`.
```

--------------------------------

### Box::try_new_uninit

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Attempts to construct a new Box with uninitialized contents, returning an error on allocation failure. Nightly-only.

```APIDOC
## Box::try_new_uninit

### Description
Constructs a new box with uninitialized contents on the heap, returning an error if the allocation fails. This is a nightly-only experimental API.

### Method
Associated function

### Response
- **Result<Box<MaybeUninit<T>>, AllocError>** - Ok containing the Box if allocation succeeds, or an Err with an `AllocError` if it fails.

### Example
```rust
#![feature(allocator_api)]

let mut five = Box::<u32>::try_new_uninit()?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```
```

--------------------------------

### Open or Create a Mapfile

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/mapfile/struct.Mapfile.html

Attempts to load a mapfile from the given path. If the file does not exist, it creates a new mapfile.

```rust
pub fn open_or_create(
 path: &Path,
 total_size: u64,
 version: &str,
) -> Result<Self>
```

--------------------------------

### Dereference Pointer

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/handshake/struct.AacsAuth.html

Dereferences a raw pointer to get an immutable reference to the object. This is an unsafe operation.

```rust
unsafe fn deref<'a>(ptr: usize) -> &'a T
```

--------------------------------

### Get TypeId of Self

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/handshake/struct.AacsAuth.html

Retrieves the `TypeId` of the current instance. This is useful for runtime type identification.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Drive::open

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Opens a connection to an optical disc drive. This function initializes the drive session and prepares it for further operations.

```APIDOC
## Drive::open

### Description
Opens a connection to an optical disc drive.

### Method
`pub fn open(device: &Path) -> Result<Self>`

### Parameters
#### Path Parameters
- **device** (*&Path*) - Required - The path to the drive device.

### Response
#### Success Response
- **Self** (*Drive*) - An initialized Drive struct representing the opened drive session.
#### Error Response
- **Result** - An error if the drive could not be opened.
```

--------------------------------

### Consume Box to Get Inner Value

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Use `into_inner` to consume a `Box` and retrieve the wrapped value.

```rust
#![feature(box_into_inner)]

let c = Box::new(5);

assert_eq!(Box::into_inner(c), 5);
```

--------------------------------

### DemuxSink::create

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/mux/struct.DemuxSink.html

Creates a new DemuxSink. This function initializes the sink by creating the specified directory and opening individual files for each selected track.

```APIDOC
## DemuxSink::create

### Description
Creates a new DemuxSink. This function initializes the sink by creating the specified directory and opening individual files for each selected track.

### Signature
```rust
pub fn create( dir: &Path, title: &DiscTitle, opts: &DemuxOptions, ) -> Result<Self>
```

### Parameters
* **dir** (`&Path`) - The directory where the output files will be created.
* **title** (`&DiscTitle`) - Metadata about the disc.
* **opts** (`&DemuxOptions`) - Options for the demuxing process.

### Returns
* `Result<Self>` - Returns a `DemuxSink` instance on success, or an error if creation fails.
```

--------------------------------

### PartialEq Implementation

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/dvdnav/vmcmd/struct.Command.html

Provides methods for comparing two Command instances for equality.

```APIDOC
### impl PartialEq for Command

#### fn eq(&self, other: &Command) -> bool

Tests for `self` and `other` values to be equal, and is used by `==`.
```

```APIDOC
#### fn ne(&self, other: &Rhs) -> bool

Tests for `!=`.
```

--------------------------------

### capacity_sectors Method

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/trait.SectorSource.html

A provided method to get the total capacity in sectors. Returns 0 if the capacity is unknown.

```rust
fn capacity_sectors(&self) -> u32 { ... }
```

--------------------------------

### get_config_010c

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/scsi/fn.get_config_010c.html

Sends a GET CONFIGURATION command for feature 0x010C (Firmware Information) and returns the configuration data.

```APIDOC
## get_config_010c

### Description
Sends a GET CONFIGURATION command for feature 0x010C (Firmware Information) using the provided SCSI transport. This function is used to retrieve firmware information from a device.

### Function Signature
```rust
pub fn get_config_010c(scsi: &mut dyn ScsiTransport) -> Result<Vec<u8>>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Assuming scsi_transport is an initialized mutable reference to a ScsiTransport implementation
let firmware_info = libfreemkv::scsi::get_config_010c(&mut scsi_transport)?;
```

### Response
#### Success Response
- **Vec<u8>** - A vector of bytes containing the firmware information if the command is successful.

#### Response Example
```json
// Example response (actual content will vary based on device firmware)
[72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]
```

#### Error Handling
- **Result** - Returns an error if the SCSI command fails or if there's an issue with the transport.
```

--------------------------------

### new_in

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Allocates memory in the given allocator then places `x` into it. This is a nightly-only experimental API.

```APIDOC
## new_in

### Description
Allocates memory in the given allocator then places `x` into it. This doesn’t actually allocate if `T` is zero-sized.

### Method
Associated function (Nightly-only experimental API)

### Parameters
- **x** (*T*) - The value to place into the new Box.
- **alloc** (*A*) - The allocator to use for memory allocation.

### Response
- **Box<T, A>** - A new Box containing `x` allocated with the specified allocator.
```

--------------------------------

### DiscTitle::size_gb() - Get size in Gigabytes

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/struct.DiscTitle.html

Calculates and returns the total size of the DiscTitle in Gigabytes (GB).

```rust
pub fn size_gb(&self) -> f64
```

--------------------------------

### Initialize OpeningCapture

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/diag/struct.OpeningCapture.html

Creates a new OpeningCapture instance, opening a side file for captured frames. Returns None if the diagnostic target is off or the file cannot be created, ensuring the rip process is not interrupted.

```rust
pub fn new(output_path: &Path, track_count: usize) -> Option<Self>
```

--------------------------------

### Mutably Dereference Pointer

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/handshake/struct.AacsAuth.html

Dereferences a raw pointer to get a mutable reference to the object. This is an unsafe operation.

```rust
unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T
```

--------------------------------

### From Implementation

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Provides a way to create a Box from a value.

```APIDOC
## From Implementation

### `impl<T> From<T> for Box<T>`

Available on **non-`no_global_oom_handling`** only.

#### `fn from(t: T) -> Box<T>`

Converts a `T` into a `Box<T>`. The conversion allocates on the heap and moves `t` from the stack into it.

##### §Examples
```
let x = 5;
let boxed = Box::new(5);

assert_eq!(Box::from(x), boxed);
```
```

--------------------------------

### Drive::is_ready

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Checks if the drive is currently in a ready state.

```APIDOC
## Drive::is_ready

### Description
Checks if the drive is currently in a ready state.

### Method
`pub fn is_ready(&self) -> bool`

### Response
#### Success Response
- **bool** - `true` if the drive is ready, `false` otherwise.

```

--------------------------------

### stream_position

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Returns the current seek position from the start of the stream. This method is part of the Seek trait implementation for Box<S>.

```APIDOC
## stream_position

### Description
Returns the current seek position from the start of the stream.

### Signature
`fn stream_position(&mut self) -> Result<u64, Error>`

### Returns
A `Result` containing the current stream position or an error.

### Context
Implemented for `Box<S>` where `S: Seek + ?Sized`.
```

--------------------------------

### SectorRange Struct Definition

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/verify/struct.SectorRange.html

Defines the structure for a SectorRange, including start LBA, count, status, and byte offset.

```rust
pub struct SectorRange {
    pub start_lba: u32,
    pub count: u32,
    pub status: SectorStatus,
    pub byte_offset: u64,
}
```

--------------------------------

### Bidirectional PES Stream Pipeline Example

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/mux/index.html

Demonstrates how to read from an input stream (e.g., a disc image) and write to an output stream (e.g., an MKV file) using the bidirectional PES stream interface. This loop continues as long as frames can be read from the input.

```rust
let mut input = input("iso://Disc.iso", &opts)?;
let title = input.info().clone();
let mut output = output("mkv://Movie.mkv", &title)?;
while let Ok(Some(frame)) = input.read() {
    output.write(&frame)?;
}
output.finish()?;
```

--------------------------------

### Check if Drive is Ready

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Checks if the drive is currently in a ready state.

```rust
pub fn is_ready(&self) -> bool
```

--------------------------------

### walk_processing_key

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/variants/index.html

Walks an MKB to find the first Processing Key (Kp) and associated `uv` slot that is covered by the device keys.

```APIDOC
## walk_processing_key

### Description
Walk an MKB and return the first `(Kp, uv, cvalue)` that `device_keys` covers. Returns `None` if no DK walks any uv.

### Function Signature
`walk_processing_key(records: &MkbRecords, device_keys: &[DeviceKey]) -> Option<(&[u8; 16], u16, u32)>`

### Parameters
* `records` - The MKB records to walk.
* `device_keys` - A slice of device keys to check against.

### Returns
- `Some((Kp, uv, cvalue))` if a matching Processing Key is found.
- `None` if no matching Processing Key is found.
```

--------------------------------

### MediaKey PartialEq Implementation

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/boil/struct.MediaKey.html

Enables equality comparison between two MediaKey instances.

```rust
fn eq(&self, other: &MediaKey) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

--------------------------------

### Create a New Mapfile

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/mapfile/struct.Mapfile.html

Creates a new mapfile at the specified path with a given total size and version. This operation writes to disk immediately.

```rust
pub fn create(path: &Path, total_size: u64, version: &str) -> Result<Self>
```

--------------------------------

### Result Termination Implementation

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.Batch.html

Provides a way to get a status code representation of a Result value, which is then returned to the operating system.

```rust
impl<T, E> Termination for Result<T, E>
where T: Termination,
      E: Debug
```

--------------------------------

### Box::new_uninit

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.EventFn.html

Constructs a new Box with uninitialized contents. Useful for deferred initialization.

```APIDOC
## Box::new_uninit

### Description
Constructs a new box with uninitialized contents. This method is useful when you need to defer the initialization of the boxed value.

### Method
Associated function

### Response
- **Box<MaybeUninit<T>>** - A Box containing uninitialized memory.

### Example
```rust
let mut five = Box::<u32>::new_uninit();
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```
```

--------------------------------

### Extracting Ok Value with `into_ok`

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/prefetched/type.Batch.html

Use `into_ok` to get the contained `Ok` value. This method panics if the result is `Err`.

```rust
let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### SCSI_GET_CONFIGURATION Constant Definition

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/scsi/constant.SCSI_GET_CONFIGURATION.html

Defines the byte value for the SCSI_GET_CONFIGURATION command. This constant is used when initiating a GET CONFIGURATION command in SCSI.

```rust
pub const SCSI_GET_CONFIGURATION: u8 = 0x46;
```

--------------------------------

### Accept Connection from Listener

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/mux/struct.NetworkStream.html

Accepts one connection from an already-bound listener and reads from it. This allows a caller to bind first (learning the actual port for an ephemeral `:0` bind) and then hand the listener in, closing the bind/drop/re-bind race that `listen(addr)` would otherwise have.

```rust
pub fn accept_from(listener: TcpListener) -> Result<Self>
```

--------------------------------

### Get Halt Flag

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/drive/struct.Drive.html

Retrieves a clone of the halt flag. Setting this flag to true can interrupt ongoing Drive::read() operations.

```rust
pub fn halt_flag(&self) -> Arc<AtomicBool>
```

--------------------------------

### vid Method

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/keysource/trait.ResolveCtx.html

Returns the Volume ID, or None if no authenticated handshake ran. VID-dependent derivation is impossible when None.

```rust
fn vid(&self) -> Option<Vid>;
```

--------------------------------

### Get Total Mapfile Size

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/mapfile/struct.Mapfile.html

Returns the total size of the mapfile in bytes. This represents the end byte of the last entry in the mapfile.

```rust
pub fn total_size(&self) -> u64
```

--------------------------------

### accept_from

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/mux/struct.NetworkStream.html

Accepts a single TCP connection from an already-bound listener and reads from it. This allows for more control over the listener binding process.

```APIDOC
## accept_from

### Description
Accept one connection from an already-bound listener and read from it. Lets a caller bind first (learning the actual port for an ephemeral `:0` bind) and hand the listener in, closing the bind/drop/re-bind race that `listen(addr)` would otherwise have.

### Method
`pub fn accept_from(listener: TcpListener) -> Result<Self>`

### Parameters
#### Path Parameters
- **listener** (TcpListener) - Required - The pre-bound TcpListener to accept a connection from.

### Response
#### Success Response (Result<Self>)
- **Self** - A new NetworkStream instance connected for reading.
```

--------------------------------

### Open FileSectorSource

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/io/file_sector_source/struct.FileSectorSource.html

Opens an existing ISO file for reading. The capacity is determined by the file size, and it returns an error if the file exceeds the 32-bit LBA address space. It also provides a sequential access hint to the kernel.

```rust
pub fn open(path: &Path) -> Result<Self>
```

--------------------------------

### Get All Map Entries

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/disc/mapfile/struct.Mapfile.html

Returns a slice containing all map entries. These entries are sorted by position and are guaranteed to be disjoint and non-overflowing after loading.

```rust
pub fn entries(&self) -> &[MapEntry]
```

--------------------------------

### derive_media_key_and_pk_from_dk

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/aacs/keys/fn.derive_media_key_and_pk_from_dk.html

Derives the Media Key (mk) and Processing Key (pk) from a provided MKB and a slice of DeviceKey structures. It returns an Option containing a tuple of two [u8; 16] arrays, representing the mk and pk respectively, or None if the derivation fails.

```APIDOC
## derive_media_key_and_pk_from_dk

### Description
Derive both the Media Key and the intermediate Processing Key from an MKB using device keys (subset-difference tree).

### Signature
```rust
pub fn derive_media_key_and_pk_from_dk(
    mkb: &[u8],
    device_keys: &[DeviceKey],
) -> Option<([u8; 16], [u8; 16])>
```

### Parameters
* `mkb`: A byte slice representing the Media Key Block.
* `device_keys`: A slice of `DeviceKey` structures used in the derivation process.

### Returns
An `Option` containing a tuple `([u8; 16], [u8; 16])` if the derivation is successful, where the first element is the Media Key and the second is the Processing Key. Returns `None` if the derivation fails.
```

--------------------------------

### set_unit_base Method

Source: https://docs.rs/libfreemkv/1.1.0/libfreemkv/sector/trait.SectorSource.html

Sets the base LBA for AACS unit-alignment. This is used by `DecryptingSectorSource` to correctly gate encrypted regions relative to the start of a clip.

```rust
fn set_unit_base(&mut self, _lba: u32) { ... }
```
Tokens:
Raw