kawaiifi 0.2.0

Wi-Fi scanning library for Linux, macOS, and Windows.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

mod error;

#[cfg(target_os = "linux")]
mod linux;

#[cfg(target_os = "macos")]
mod macos;

#[cfg(target_os = "windows")]
mod windows;

pub use error::Error;

#[cfg(target_os = "linux")]
pub use linux::{BusType, Interface};

#[cfg(target_os = "macos")]
pub use macos::Interface;

#[cfg(target_os = "macos")]
pub(crate) use macos::parse_bssid;

#[cfg(target_os = "windows")]
pub use windows::Interface;

/// Returns the first available Wi-Fi interface.
///
/// The interface is selected from the platform's enumeration order. That order
/// is platform-defined and is not guaranteed to remain stable.
///
/// Returns `Ok(Some(interface))` when an interface is available and `Ok(None)`
/// when enumeration succeeds but no Wi-Fi interfaces are found.
///
/// # Errors
///
/// Returns an [`InterfaceError`](crate::InterfaceError) if the system's Wi-Fi
/// interfaces cannot be enumerated. Currently, enumeration errors are reported
/// on Linux; the macOS and Windows implementations return `Ok`.
///
/// # Examples
///
/// ```
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// match kawaiifi::default_interface()? {
///     Some(interface) => println!("Found interface: {interface:?}"),
///     None => println!("No Wi-Fi interfaces found"),
/// }
/// # Ok(())
/// # }
/// ```
pub fn default_interface() -> Result<Option<Interface>, crate::InterfaceError> {
    Ok(interfaces()?.into_iter().next())
}

/// Returns all available Wi-Fi interfaces on the system.
///
/// An empty vector indicates that enumeration succeeded but no Wi-Fi
/// interfaces were found. The order of the returned interfaces is
/// platform-defined and is not guaranteed to remain stable.
///
/// # Errors
///
/// Returns an [`InterfaceError`](crate::InterfaceError) if the system's Wi-Fi
/// interfaces cannot be enumerated. Currently, enumeration errors are reported
/// on Linux; the macOS and Windows implementations return `Ok`.
///
/// # Examples
///
/// ```
/// # fn example() -> Result<(), kawaiifi::InterfaceError> {
/// let interfaces = kawaiifi::interfaces()?;
/// println!("Found {} Wi-Fi interface(s)", interfaces.len());
/// # Ok(())
/// # }
/// ```
#[cfg(target_os = "linux")]
pub fn interfaces() -> Result<Vec<Interface>, crate::InterfaceError> {
    linux::interfaces()
}

/// Returns all available Wi-Fi interfaces on the system.
///
/// An empty vector indicates that enumeration succeeded but no Wi-Fi
/// interfaces were found. The order of the returned interfaces is
/// platform-defined and is not guaranteed to remain stable.
///
/// # Errors
///
/// Returns an [`InterfaceError`](crate::InterfaceError) if the system's Wi-Fi
/// interfaces cannot be enumerated. Currently, enumeration errors are reported
/// on Linux; the macOS and Windows implementations return `Ok`.
///
/// # Examples
///
/// ```
/// # fn example() -> Result<(), kawaiifi::InterfaceError> {
/// let interfaces = kawaiifi::interfaces()?;
/// println!("Found {} Wi-Fi interface(s)", interfaces.len());
/// # Ok(())
/// # }
/// ```
#[cfg(target_os = "macos")]
pub fn interfaces() -> Result<Vec<Interface>, crate::InterfaceError> {
    Ok(macos::interfaces())
}

/// Returns all available Wi-Fi interfaces on the system.
///
/// An empty vector indicates that enumeration succeeded but no Wi-Fi
/// interfaces were found. The order of the returned interfaces is
/// platform-defined and is not guaranteed to remain stable.
///
/// # Errors
///
/// Returns an [`InterfaceError`](crate::InterfaceError) if the system's Wi-Fi
/// interfaces cannot be enumerated. Currently, enumeration errors are reported
/// on Linux; the macOS and Windows implementations return `Ok`.
///
/// # Examples
///
/// ```
/// # fn example() -> Result<(), kawaiifi::InterfaceError> {
/// let interfaces = kawaiifi::interfaces()?;
/// println!("Found {} Wi-Fi interface(s)", interfaces.len());
/// # Ok(())
/// # }
/// ```
#[cfg(target_os = "windows")]
pub fn interfaces() -> Result<Vec<Interface>, crate::InterfaceError> {
    Ok(windows::interfaces())
}