X-Git-Url: https://code.octet-stream.net/netwatcher/blobdiff_plain/846b618fe219c44dfc7b3a13aadace2198442c9c..e29a1fae66084be615adffec6b32f477c8c16277:/src/lib.rs diff --git a/src/lib.rs b/src/lib.rs index 9f82092..cb3a117 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,15 +1,21 @@ use std::{ - collections::HashMap, + collections::{HashMap, HashSet}, net::{IpAddr, Ipv4Addr, Ipv6Addr}, + ops::Sub, }; -#[cfg_attr(windows, path = "imp_win.rs")] -#[cfg_attr(target_vendor = "apple", path = "imp_mac.rs")] -mod imp; -mod util; +#[cfg_attr(windows, path = "list_win.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(target_os = "linux", path = "watch_linux.rs")] +mod watch; type IfIndex = u32; +/// Information about one network interface at a point in time. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Interface { pub index: u32, @@ -19,6 +25,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), @@ -26,6 +33,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, @@ -34,40 +42,118 @@ 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, } -#[derive(Debug, Clone, PartialEq, Eq)] +/// What changed between one `Update` and the next. +#[derive(Debug, Clone, PartialEq, Eq, Default)] pub struct UpdateDiff { pub added: Vec, pub removed: Vec, pub modified: HashMap, } -#[derive(Debug, Clone, PartialEq, Eq)] +/// 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, pub addrs_added: Vec, pub addrs_removed: Vec, } +/// Errors in netwatcher or in one of the underlying platform integratinos. #[derive(Debug, Clone, PartialEq, Eq)] pub enum Error { + // TODO: handle all cases with proper sources Internal, } -pub fn list_interfaces() -> Result, Error> { - imp::list_interfaces() +#[derive(Default, PartialEq, Eq)] +struct List(HashMap); + +impl List { + fn diff_from(&self, prev: &List) -> UpdateDiff { + let prev_index_set: HashSet = prev.0.keys().cloned().collect(); + let curr_index_set: HashSet = self.0.keys().cloned().collect(); + let added = curr_index_set.sub(&prev_index_set).into_iter().collect(); + let removed = prev_index_set.sub(&curr_index_set).into_iter().collect(); + let mut modified = HashMap::new(); + for index in curr_index_set.intersection(&prev_index_set) { + if prev.0[index] == self.0[index] { + continue; + } + let prev_addr_set: HashSet<&IpAddr> = prev.0[index].ips.iter().collect(); + let curr_addr_set: HashSet<&IpAddr> = self.0[index].ips.iter().collect(); + let addrs_added: Vec = curr_addr_set + .sub(&prev_addr_set) + .iter() + .cloned() + .cloned() + .collect(); + let addrs_removed: Vec = prev_addr_set + .sub(&curr_addr_set) + .iter() + .cloned() + .cloned() + .collect(); + let hw_addr_changed = prev.0[index].hw_addr != self.0[index].hw_addr; + modified.insert( + *index, + InterfaceDiff { + hw_addr_changed, + addrs_added, + addrs_removed, + }, + ); + } + UpdateDiff { + added, + removed, + modified, + } + } +} + +/// 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, } -pub struct 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) -> WatchHandle { - // stop current worker thread - // post this into a thread that will use it - drop(callback); - WatchHandle +/// 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 }) }