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.

This typically occurs when the NDI SDK is not installed or cannot be loaded.

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

Frame capture timed out after multiple retry attempts.

This error includes detailed information about the retry attempts and total elapsed time, making it easier to diagnose frame capture issues and distinguish them from other timeout scenarios.

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)

Failed to spawn a blocking task on the async runtime.

This error occurs when the async runtime fails to spawn a blocking task, typically due to task cancellation or runtime shutdown. Unlike the previous behavior which panicked on tokio JoinError, this error allows callers to handle the failure gracefully.

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.