Enum Error 

#[non_exhaustive]
pub enum Error {
    InitializationFailed(String),
    NullPointer(String),
    InvalidUtf8(String),
    InvalidCString(NulError),
    CaptureFailed(String),
    InvalidFrame(String),
    PtzCommandFailed(String),
    InvalidConfiguration(String),
    Io(Error),
    Timeout(String),
    FrameTimeout {
        attempts: usize,
        elapsed: Duration,
    },
    SourceUnavailable {
        source_name: String,
    },
    Disconnected {
        reason: String,
    },
    NoSourcesFound {
        criteria: String,
    },
    SpawnFailed(String),
}

The main error type for NDI operations.

This enum represents all possible errors that can occur when using the grafton-ndi library. It provides detailed error messages and automatic conversion from common error types.

This enum is marked #[non_exhaustive] so that new error variants can be added as the NDI SDK surface evolves without constituting a breaking change. Match arms should include a wildcard _ pattern.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

InitializationFailed(String)

NDI runtime initialization failed.

The SDK rejected initialization, a handle could not be created, or the runtime handle reference count was exhausted. A missing shared library can instead prevent the application from loading before Rust code runs.

NullPointer(String)

A null pointer was returned by the NDI SDK.

Indicates an internal NDI error or invalid operation.

InvalidUtf8(String)

Invalid UTF-8 data in a string from the NDI SDK.

InvalidCString(NulError)

Failed to create a C string due to null bytes.

CaptureFailed(String)

Frame capture operation failed.

InvalidFrame(String)

Frame data is invalid or corrupted.

PtzCommandFailed(String)

PTZ (Pan-Tilt-Zoom) camera control command failed.

InvalidConfiguration(String)

Configuration parameters are invalid.

This can occur when builder validation fails or conflicting options are set.

Io(Error)

I/O operation failed.

Timeout(String)

Operation timed out with generic context.

This is a general timeout error. For frame capture timeouts with retry information, see Error::FrameTimeout.

FrameTimeout

The capture wait budget expired without a frame.

Includes the number of capture attempts and elapsed time in the retry loop. The attempt count can be zero or one; retries are not guaranteed. For async capture, elapsed excludes time queued before that loop begins.

Example

match some_operation() {
    Err(Error::FrameTimeout { attempts, elapsed }) => {
        eprintln!("Frame timeout after {} attempts in {:?}", attempts, elapsed);
        // Could implement retry logic based on attempts count
    }
    Err(e) => eprintln!("Other error: {}", e),
    Ok(_) => println!("Success"),
}

Fields

attempts: usize

Number of capture attempts made before timing out

elapsed: Duration

Total elapsed time during capture attempts

SourceUnavailable

NDI source became unavailable during operation.

This error indicates that an NDI source that was previously available has gone offline or become unreachable. This is different from Error::NoSourcesFound which indicates that no matching sources were ever discovered.

Example

match some_operation() {
    Err(Error::SourceUnavailable { source_name }) => {
        eprintln!("Lost connection to source: {}", source_name);
        // Could attempt to reconnect or switch to backup source
    }
    Err(e) => eprintln!("Other error: {}", e),
    Ok(_) => println!("Success"),
}

Fields

source_name: String

Name or identifier of the source that became unavailable

Disconnected

Receiver disconnected from its NDI source.

This error indicates that an active receiver lost its connection to the source. The reason field provides additional context about why the disconnection occurred.

Example

match some_operation() {
    Err(Error::Disconnected { reason }) => {
        eprintln!("Receiver disconnected: {}", reason);
        // Could implement automatic reconnection logic
    }
    Err(e) => eprintln!("Other error: {}", e),
    Ok(_) => println!("Success"),
}

Fields

reason: String

Reason for the disconnection

NoSourcesFound

No NDI sources found matching the specified criteria.

This error is returned when source discovery completes but no sources match the requested criteria (e.g., host/IP filter, group filter).

Example

match some_operation() {
    Err(Error::NoSourcesFound { criteria }) => {
        eprintln!("No sources found matching: {}", criteria);
        // Could widen search criteria or wait longer
    }
    Err(e) => eprintln!("Other error: {}", e),
    Ok(_) => println!("Success"),
}

Fields

criteria: String

The search criteria that yielded no results

SpawnFailed(String)

An async blocking operation could not run or finish normally.

Covers a missing Tokio runtime context, task cancellation or join failure, and a panic caught while executing a blocking operation. Dropping a future discards its result; cancellation does not deliver an error to that caller.

Example

use grafton_ndi::Error;

fn handle_error(err: Error) {
    match err {
        Error::SpawnFailed(reason) => {
            eprintln!("Async spawn failed: {}", reason);
            // Could retry or gracefully shutdown
        }
        e => eprintln!("Other error: {}", e),
    }
}

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<NulError> for Error

fn from(source: NulError) -> Self

Converts to this type from the input type.