use core::fmt;
#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
InvalidConfig {
field: &'static str,
reason: &'static str,
},
DeviceNotFound,
UnsupportedTuner,
PllUnlocked,
ConfigurationUnknown,
DeviceClosed,
Busy,
Unsupported,
StreamClosed {
reason: &'static str,
},
Usb(nusb::Error),
Transfer(nusb::transfer::TransferError),
Operation {
operation: &'static str,
source: Box<Error>,
},
Protocol {
operation: &'static str,
reason: &'static str,
},
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ErrorKind {
InvalidConfig,
NotFound,
DeviceClosed,
DeviceDisconnected,
Busy,
Unsupported,
Usb,
StreamClosed,
Other,
}
impl Error {
pub(crate) const fn invalid_config(field: &'static str, reason: &'static str) -> Self {
Self::InvalidConfig { field, reason }
}
pub(crate) const fn stream_closed(reason: &'static str) -> Self {
Self::StreamClosed { reason }
}
pub(crate) const fn protocol(operation: &'static str, reason: &'static str) -> Self {
Self::Protocol { operation, reason }
}
pub(crate) fn at(self, operation: &'static str) -> Self {
Self::Operation {
operation,
source: Box::new(self),
}
}
pub fn kind(&self) -> ErrorKind {
match self {
Self::InvalidConfig { .. } => ErrorKind::InvalidConfig,
Self::DeviceNotFound => ErrorKind::NotFound,
Self::UnsupportedTuner => ErrorKind::Unsupported,
Self::PllUnlocked | Self::ConfigurationUnknown => ErrorKind::Other,
Self::DeviceClosed => ErrorKind::DeviceClosed,
Self::Busy => ErrorKind::Busy,
Self::Unsupported => ErrorKind::Unsupported,
Self::StreamClosed { .. } => ErrorKind::StreamClosed,
Self::Usb(err) => match err.kind() {
nusb::ErrorKind::Disconnected => ErrorKind::DeviceDisconnected,
nusb::ErrorKind::Busy => ErrorKind::Busy,
nusb::ErrorKind::NotFound => ErrorKind::NotFound,
nusb::ErrorKind::Unsupported => ErrorKind::Unsupported,
_ => ErrorKind::Usb,
},
Self::Transfer(nusb::transfer::TransferError::Disconnected) => {
ErrorKind::DeviceDisconnected
}
Self::Transfer(_) => ErrorKind::Usb,
Self::Operation { source, .. } => source.kind(),
Self::Protocol { .. } => ErrorKind::Other,
}
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidConfig { field, reason } => {
write!(f, "invalid configuration for {field}: {reason}")
}
Self::DeviceNotFound => f.write_str("no matching RTL-SDR device found"),
Self::UnsupportedTuner => f.write_str("unsupported tuner (R820T/R828D required)"),
Self::PllUnlocked => f.write_str("tuner PLL did not lock"),
Self::ConfigurationUnknown => {
f.write_str("configuration is unknown; reapply a complete configuration or reopen")
}
Self::DeviceClosed => f.write_str("RTL-SDR device is closed"),
Self::Busy => f.write_str("RTL-SDR device or USB resource is busy"),
Self::Unsupported => f.write_str("operation is unsupported"),
Self::StreamClosed { reason } => write!(f, "stream closed: {reason}"),
Self::Usb(err) => write!(f, "USB error: {err}"),
Self::Transfer(err) => write!(f, "USB transfer error: {err}"),
Self::Operation { operation, source } => write!(f, "{operation}: {source}"),
Self::Protocol { operation, reason } => write!(f, "{operation}: {reason}"),
}
}
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Usb(err) => Some(err),
Self::Transfer(err) => Some(err),
Self::Operation { source, .. } => Some(source),
_ => None,
}
}
}
impl From<nusb::Error> for Error {
fn from(value: nusb::Error) -> Self {
Self::Usb(value)
}
}
impl From<nusb::transfer::TransferError> for Error {
fn from(value: nusb::transfer::TransferError) -> Self {
Self::Transfer(value)
}
}
pub type Result<T> = core::result::Result<T, Error>;
#[cfg(test)]
mod tests {
use std::error::Error as _;
use super::{Error, ErrorKind};
#[test]
fn transfer_errors_preserve_their_source_and_are_not_configuration_errors() {
let err = Error::from(nusb::transfer::TransferError::InvalidArgument);
assert!(matches!(
&err,
Error::Transfer(nusb::transfer::TransferError::InvalidArgument)
));
assert_eq!(err.kind(), ErrorKind::Usb);
assert!(err.source().is_some());
}
#[test]
fn transfer_disconnects_have_their_own_error_category() {
let err = Error::from(nusb::transfer::TransferError::Disconnected);
assert_eq!(err.kind(), ErrorKind::DeviceDisconnected);
assert!(err.source().is_some());
}
#[test]
fn configuration_errors_expose_the_field_and_reason() {
let err = Error::invalid_config("frequency_hz", "must be nonzero");
assert!(matches!(
&err,
Error::InvalidConfig {
field: "frequency_hz",
reason: "must be nonzero"
}
));
assert_eq!(err.kind(), ErrorKind::InvalidConfig);
}
#[test]
fn operation_context_preserves_source_category() {
let err =
Error::from(nusb::transfer::TransferError::Fault).at("applying receiver configuration");
assert_eq!(err.kind(), ErrorKind::Usb);
assert!(
err.to_string()
.starts_with("applying receiver configuration: USB transfer error:")
);
assert!(err.source().is_some());
}
#[test]
fn operation_context_preserves_disconnect_category() {
let err =
Error::from(nusb::transfer::TransferError::Disconnected).at("reading receiver samples");
assert_eq!(err.kind(), ErrorKind::DeviceDisconnected);
assert!(err.source().is_some());
}
#[test]
fn closed_device_has_its_own_error_category() {
assert_eq!(Error::DeviceClosed.kind(), ErrorKind::DeviceClosed);
assert_eq!(Error::DeviceClosed.to_string(), "RTL-SDR device is closed");
}
}