code.octet-stream.net Git - netwatcher/blob - README.md

   1 # netwatcher
   2
   3 [![Crates.io Version](https://img.shields.io/crates/v/netwatcher)](https://crates.io/crates/netwatcher)
   4 [![docs.rs](https://img.shields.io/docsrs/netwatcher)](https://docs.rs/netwatcher)
   5
   6 `netwatcher` is a cross-platform Rust 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.
   7
   8 ## Current platform support
   9
  10 | Platform | Min Version | List | Watch | Notes                                                                                 |
  11 |----------|-------------|------|-------|---------------------------------------------------------------------------------------|
  12 | Windows  | -           | ✅    | ✅     |                                                                                       |
  13 | Mac      | 10.14       | ✅    | ✅     |                                                                                       |
  14 | Linux    | -           | ✅    | ✅     | Creates a background thread                                                           |
  15 | iOS      | 12.0        | ✅    | ✅     |                                                                                       |
  16 | Android  | -           | ✅    | ❌     | Linux-style watch fails on Android 11+ due to privacy restrictions. Alternatives WIP. |
  17
  18 ## Usage
  19
  20 ### Listing interfaces
  21
  22 ```rust
  23 /// Returns a HashMap from ifindex (a `u32`) to an `Interface` struct
  24 let interfaces = netwatcher::list_interfaces().unwrap();
  25 for i in interfaces.values() {
  26     println!("interface {} has {} IPs", i.name, i.ips.len());
  27 }
  28 ```
  29
  30 ### Watching for changes to interfaces
  31
  32 ```rust
  33 let handle = netwatcher::watch_interfaces(|update| {
  34     // This callback will fire once immediately with the existing state
  35
  36     // Update includes the latest snapshot of all interfaces
  37     println!("Current interface map: {:#?}", update.interfaces);
  38
  39     // The `UpdateDiff` describes changes since previous callback
  40     // You can choose whether to use the snapshot, diff, or both
  41     println!("ifindexes added: {:?}", update.diff.added);
  42     println!("ifindexes removed: {:?}", update.diff.removed);
  43     for (ifindex, if_diff) in update.diff.modified {
  44         println!("Interface index {} has changed", ifindex);
  45         println!("Added IPs: {:?}", if_diff.addrs_added);
  46         println!("Removed IPs: {:?}", if_diff.addrs_removed);
  47     }
  48 });
  49 // keep `handle` alive as long as you want callbacks
  50 // ...
  51 drop(handle);
  52 ```
  53
  54 ## Licence
  55
  56 Apache License Version 2.0 - see `LICENSE`.