rpi_host/
error.rs

1//! Error types for WiFi operations.
2//!
3//! This module provides the [`WifiError`] enum which represents all possible
4//! errors that can occur when managing WiFi connections, and the [`WifiResult`]
5//! type alias for convenience.
6//!
7//! # Example
8//!
9//! ```no_run
10//! use rpi_host::{WifiManager, WifiError};
11//!
12//! fn connect_to_network() -> Result<(), WifiError> {
13//!     let wifi = WifiManager::new()?;
14//!
15//!     match wifi.connect("MyNetwork", Some("password")) {
16//!         Ok(()) => println!("Connected!"),
17//!         Err(WifiError::ConnectionFailed { ssid, reason }) => {
18//!             println!("Failed to connect to {}: {}", ssid, reason);
19//!         }
20//!         Err(e) => return Err(e),
21//!     }
22//!
23//!     Ok(())
24//! }
25//! ```
26
27use std::io;
28use thiserror::Error;
29
30/// Errors that can occur when managing WiFi connections.
31///
32/// This enum covers all error conditions that may arise during WiFi operations,
33/// from command execution failures to connectivity issues.
34///
35/// # Error Categories
36///
37/// - **System errors**: [`CommandExecution`][Self::CommandExecution], [`NmcliError`][Self::NmcliError]
38/// - **Configuration errors**: [`InterfaceNotFound`][Self::InterfaceNotFound], [`InvalidConfiguration`][Self::InvalidConfiguration]
39/// - **Connection errors**: [`ConnectionFailed`][Self::ConnectionFailed], [`HotspotCreationFailed`][Self::HotspotCreationFailed]
40/// - **State errors**: [`WifiDisabled`][Self::WifiDisabled], [`NoInternetConnectivity`][Self::NoInternetConnectivity]
41#[derive(Error, Debug)]
42pub enum WifiError {
43    /// NetworkManager command failed to execute.
44    ///
45    /// This typically indicates that `nmcli` is not installed or not in PATH.
46    #[error("Failed to execute nmcli command: {0}")]
47    CommandExecution(#[from] io::Error),
48
49    /// nmcli command returned an error.
50    ///
51    /// Contains the error message from NetworkManager.
52    #[error("nmcli error: {message}")]
53    NmcliError {
54        /// The error message from nmcli
55        message: String,
56    },
57
58    /// The specified wireless interface was not found.
59    ///
60    /// Verify the interface name with `nmcli device status`.
61    #[error("Wireless interface '{0}' not found")]
62    InterfaceNotFound(String),
63
64    /// Failed to connect to the specified network.
65    ///
66    /// Common causes include incorrect password, network out of range,
67    /// or authentication failures.
68    #[error("Failed to connect to network '{ssid}': {reason}")]
69    ConnectionFailed {
70        /// The SSID that failed to connect
71        ssid: String,
72        /// The reason for the failure
73        reason: String,
74    },
75
76    /// Failed to create hotspot.
77    ///
78    /// This can occur if the hardware doesn't support AP mode,
79    /// or if another connection is interfering.
80    #[error("Failed to create hotspot: {0}")]
81    HotspotCreationFailed(String),
82
83    /// No internet connectivity detected.
84    ///
85    /// The device is connected to a network but cannot reach the internet.
86    #[error("No internet connectivity")]
87    NoInternetConnectivity,
88
89    /// Invalid configuration provided.
90    ///
91    /// For example, a hotspot password shorter than 8 characters.
92    #[error("Invalid configuration: {0}")]
93    InvalidConfiguration(String),
94
95    /// The requested operation is not supported.
96    ///
97    /// Some operations may not be available on certain hardware.
98    #[error("Operation not supported: {0}")]
99    NotSupported(String),
100
101    /// WiFi is disabled on the system.
102    ///
103    /// Enable WiFi with [`WifiManager::enable_wifi`][crate::WifiManager::enable_wifi]
104    /// or via `nmcli radio wifi on`.
105    #[error("WiFi is disabled")]
106    WifiDisabled,
107
108    /// A connection profile with this name already exists.
109    #[error("Connection '{0}' already exists")]
110    ConnectionExists(String),
111
112    /// Timeout waiting for operation to complete.
113    ///
114    /// Consider increasing the timeout or checking network conditions.
115    #[error("Operation timed out: {0}")]
116    Timeout(String),
117
118    /// Failed to parse nmcli output.
119    ///
120    /// This may indicate an incompatible NetworkManager version.
121    #[error("Failed to parse nmcli output: {0}")]
122    ParseError(String),
123}
124
125/// Result type alias for WiFi operations.
126///
127/// This is equivalent to `Result<T, WifiError>` and is used throughout the library.
128///
129/// # Example
130///
131/// ```no_run
132/// use rpi_host::{WifiManager, WifiResult};
133///
134/// fn my_wifi_function() -> WifiResult<String> {
135///     let wifi = WifiManager::new()?;
136///     let status = wifi.status()?;
137///     Ok(status.connection_name.unwrap_or_else(|| "Not connected".to_string()))
138/// }
139/// ```
140pub type WifiResult<T> = Result<T, WifiError>;
rpi_host/error.rs

rpi_host/
error.rs
