Document things

[netwatcher] / src / lib.rs

diff --git a/src/lib.rs b/src/lib.rs
index 46218d2ceec0469263dd2ca48e61d90402b8af43..7a8298ef647be7e99b178e97dcde113234607661 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -10,13 +10,12 @@ mod list;
 
 #[cfg_attr(windows, path = "watch_win.rs")]
 #[cfg_attr(target_vendor = "apple", path = "watch_mac.rs")]
 
 #[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;
 
 mod watch;
 

-#[cfg(unix)]
-mod util;
-

 type IfIndex = u32;
 
 type IfIndex = u32;
 

+/// Information about one network interface at a point in time.

 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Interface {
     pub index: u32,
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Interface {
     pub index: u32,


@@ -26,6 +25,7 @@ pub struct Interface {
 }
 
 impl Interface {
 }
 
 impl Interface {

+    /// Helper to iterate over only the IPv4 addresses on this interface.

     pub fn ipv4_ips(&self) -> impl Iterator<Item = &Ipv4Addr> {
         self.ips.iter().filter_map(|ip| match ip {
             IpAddr::V4(v4) => Some(v4),
     pub fn ipv4_ips(&self) -> impl Iterator<Item = &Ipv4Addr> {
         self.ips.iter().filter_map(|ip| match ip {
             IpAddr::V4(v4) => Some(v4),


@@ -33,6 +33,7 @@ impl Interface {
         })
     }
 
         })
     }
 

+    /// Helper to iterate over only the IPv6 addresses on this interface.

     pub fn ipv6_ips(&self) -> impl Iterator<Item = &Ipv6Addr> {
         self.ips.iter().filter_map(|ip| match ip {
             IpAddr::V4(_) => None,
     pub fn ipv6_ips(&self) -> impl Iterator<Item = &Ipv6Addr> {
         self.ips.iter().filter_map(|ip| match ip {
             IpAddr::V4(_) => None,


@@ -41,12 +42,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<IfIndex, Interface>,
     pub diff: UpdateDiff,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Update {
     pub interfaces: HashMap<IfIndex, Interface>,
     pub diff: UpdateDiff,
 }
 

+/// What changed between one `Update` and the next.

 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct UpdateDiff {
     pub added: Vec<IfIndex>,
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct UpdateDiff {
     pub added: Vec<IfIndex>,


@@ -54,6 +60,7 @@ pub struct UpdateDiff {
     pub modified: HashMap<IfIndex, InterfaceDiff>,
 }
 
     pub modified: HashMap<IfIndex, InterfaceDiff>,
 }
 

+/// 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,
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct InterfaceDiff {
     pub hw_addr_changed: bool,


@@ -61,6 +68,7 @@ pub struct InterfaceDiff {
     pub addrs_removed: Vec<IpAddr>,
 }
 
     pub addrs_removed: Vec<IpAddr>,
 }
 

+/// 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
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Error {
     // TODO: handle all cases with proper sources


@@ -113,14 +121,30 @@ 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,
 }
 
 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<HashMap<IfIndex, Interface>, Error> {
     list::list_interfaces().map(|list| list.0)
 }
 
 pub fn list_interfaces() -> Result<HashMap<IfIndex, Interface>, Error> {
     list::list_interfaces().map(|list| list.0)
 }
 

+/// 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.

 pub fn watch_interfaces<F: FnMut(Update) + 'static>(callback: F) -> Result<WatchHandle, Error> {
     watch::watch_interfaces(callback).map(|handle| WatchHandle { _inner: handle })
 }
 pub fn watch_interfaces<F: FnMut(Update) + 'static>(callback: F) -> Result<WatchHandle, Error> {
     watch::watch_interfaces(callback).map(|handle| WatchHandle { _inner: handle })
 }