Add top-level docs and update README

[netwatcher] / src / lib.rs

diff --git a/src/lib.rs b/src/lib.rs
index 6d22c98d391fb37b1f241d850349f69b29ee8297..dfc4395cfda75ad9bf7a81f33d887edc96c4a390 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,10 +1,52 @@
+//! # 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,
 };
 
 use std::{
     collections::{HashMap, HashSet},
     net::{IpAddr, Ipv4Addr, Ipv6Addr},
     ops::Sub,
 };
 

-use nix::errno::Errno;
+mod error;

 
 #[cfg_attr(windows, path = "list_win.rs")]
 #[cfg_attr(unix, path = "list_unix.rs")]
 
 #[cfg_attr(windows, path = "list_win.rs")]
 #[cfg_attr(unix, path = "list_unix.rs")]


@@ -20,6 +62,8 @@ mod watch;
 
 type IfIndex = u32;
 
 
 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 {
 /// Information about one network interface at a point in time.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Interface {


@@ -73,18 +117,6 @@ 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 {
-    CreateSocket(Errno),
-    Bind(Errno),
-    CreatePipe(Errno),
-    Getifaddrs(Errno),
-    GetInterfaceName(Errno),
-    FormatMacAddress,
-    Internal,
-}
-

 #[derive(Default, PartialEq, Eq)]
 struct List(HashMap<IfIndex, Interface>);
 
 #[derive(Default, PartialEq, Eq)]
 struct List(HashMap<IfIndex, Interface>);