X-Git-Url: https://code.octet-stream.net/netwatcher/blobdiff_plain/cc3e849e9ff8568609f160d4bcdb83966ffdb6c5..cc86d4310fa2b8af2675e82004facc1d90ef6922:/src/lib.rs diff --git a/src/lib.rs b/src/lib.rs index 47c5ae1..dfc4395 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,22 +1,70 @@ +//! # netwatcher +//! +//! `netwatcher` is a cross-platform library for enumerating network interfaces and their +//! IP addresses, featuring the ability to watch for changes to those interfaces +//! _efficiently_. It uses platform-specific methods to detect when interface changes +//! have occurred instead of polling, which means that you find out about changes more +//! quickly and there is no CPU or wakeup overhead when nothing is happening. +//! +//! ## List example +//! +//! ``` +//! /// Returns a HashMap from ifindex (a `u32`) to an `Interface` struct +//! let interfaces = netwatcher::list_interfaces().unwrap(); +//! for i in interfaces.values() { +//! println!("interface {} has {} IPs", i.name, i.ips.len()); +//! } +//! ``` +//! +//! ## Watch example +//! +//! ``` +//! let handle = netwatcher::watch_interfaces(|update| { +//! // This callback will fire once immediately with the existing state +//! +//! // Update includes the latest snapshot of all interfaces +//! println!("Current interface map: {:#?}", update.interfaces); +//! +//! // The `UpdateDiff` describes changes since previous callback +//! // You can choose whether to use the snapshot, diff, or both +//! println!("ifindexes added: {:?}", update.diff.added); +//! println!("ifindexes removed: {:?}", update.diff.removed); +//! for (ifindex, if_diff) in update.diff.modified { +//! println!("Interface index {} has changed", ifindex); +//! println!("Added IPs: {:?}", if_diff.addrs_added); +//! println!("Removed IPs: {:?}", if_diff.addrs_removed); +//! } +//! }); +//! // keep `handle` alive as long as you want callbacks +//! // ... +//! drop(handle); +//! ``` + use std::{ collections::{HashMap, HashSet}, net::{IpAddr, Ipv4Addr, Ipv6Addr}, ops::Sub, }; +mod error; + #[cfg_attr(windows, path = "list_win.rs")] -#[cfg_attr(target_vendor = "apple", path = "list_mac.rs")] +#[cfg_attr(unix, path = "list_unix.rs")] mod list; #[cfg_attr(windows, path = "watch_win.rs")] #[cfg_attr(target_vendor = "apple", path = "watch_mac.rs")] +#[cfg_attr( + any(target_os = "linux", target_os = "android"), + path = "watch_linux.rs" +)] mod watch; -#[cfg(target_vendor = "apple")] -mod util; - type IfIndex = u32; +pub use error::Error; + +/// Information about one network interface at a point in time. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Interface { pub index: u32, @@ -26,6 +74,7 @@ pub struct Interface { } impl Interface { + /// Helper to iterate over only the IPv4 addresses on this interface. pub fn ipv4_ips(&self) -> impl Iterator { self.ips.iter().filter_map(|ip| match ip { IpAddr::V4(v4) => Some(v4), @@ -33,6 +82,7 @@ impl Interface { }) } + /// Helper to iterate over only the IPv6 addresses on this interface. pub fn ipv6_ips(&self) -> impl Iterator { self.ips.iter().filter_map(|ip| match ip { IpAddr::V4(_) => None, @@ -41,12 +91,17 @@ impl Interface { } } +/// Information delivered via callback when a network interface change is detected. +/// +/// This contains up-to-date information about all interfaces, plus a diff which +/// details which interfaces and IP addresses have changed since the last callback. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Update { pub interfaces: HashMap, pub diff: UpdateDiff, } +/// What changed between one `Update` and the next. #[derive(Debug, Clone, PartialEq, Eq, Default)] pub struct UpdateDiff { pub added: Vec, @@ -54,6 +109,7 @@ pub struct UpdateDiff { pub modified: HashMap, } +/// What changed within a single interface between updates, if it was present in both. #[derive(Debug, Clone, PartialEq, Eq, Default)] pub struct InterfaceDiff { pub hw_addr_changed: bool, @@ -61,12 +117,6 @@ pub struct InterfaceDiff { pub addrs_removed: Vec, } -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum Error { - // TODO: handle all cases with proper sources - Internal, -} - #[derive(Default, PartialEq, Eq)] struct List(HashMap); @@ -113,14 +163,39 @@ impl List { } } +/// A handle to keep alive as long as you wish to receive callbacks. +/// +/// If the callback is executing at the time the handle is dropped, drop will block until +/// the callback is finished and it's guaranteed that it will not be called again. +/// +/// Do not drop the handle from within the callback itself. It will probably deadlock. pub struct WatchHandle { _inner: watch::WatchHandle, } +/// Retrieve information about all enabled network interfaces and their IP addresses. +/// +/// This is a once-off operation. If you want to detect changes over time, see `watch_interfaces`. pub fn list_interfaces() -> Result, Error> { list::list_interfaces().map(|list| list.0) } -pub fn watch_interfaces(callback: F) -> Result { +/// Retrieve interface information and watch for changes, which will be delivered via callback. +/// +/// If setting up the watch is successful, this returns a `WatchHandle` which must be kept for +/// as long as the provided callback should operate. +/// +/// The callback will fire once immediately with an initial interface list, and a diff as if +/// there were originally no interfaces present. +/// +/// This function will return an error if there is a problem configuring the watcher, or if there +/// is an error retrieving the initial interface list. +/// +/// We assume that if listing the interfaces worked the first time, then it will continue to work +/// for as long as the watcher is running. If listing interfaces begins to fail later, those +/// failures will be swallowed and the callback will not be called for that change event. +pub fn watch_interfaces( + callback: F, +) -> Result { watch::watch_interfaces(callback).map(|handle| WatchHandle { _inner: handle }) }