Crate netwatcher

Expand description

§netwatcher

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.

Sync and async APIs are available, with no extra dependencies for sync users. If you are using tokio, enable feature tokio. For async-io, enable async-io. Other reactors may be used by implementing the appropriate traits.

§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 {}", i.name);
    for ip_record in &i.ips {
        println!("IP: {}/{}", ip_record.ip, ip_record.prefix_len);
    }
}

§Watch options

Sync callback: watch_interfaces_with_callback
Sync blocking: watch_interfaces_blocking
Async: watch_interfaces_async::<T>

§Sync callback watch

Deliver change notifications to a callback.

let handle = netwatcher::watch_interfaces_with_callback(|update| {
    // All watch types will fire immediately with initial interface state
    println!("Is initial update: {}", update.is_initial);
    println!("Current interface map: {:#?}", update.interfaces);

    // Interfaces may appear or disappear entirely.
    for ifindex in &update.diff.added {
        println!("ifindex {} was added", ifindex);
    }
    for ifindex in &update.diff.removed {
        println!("ifindex {} was removed", ifindex);
    }

    // Existing interfaces may gain or lose IPs.
    for (ifindex, diff) in &update.diff.modified {
        let interface = &update.interfaces[ifindex];
        for addr in &diff.addrs_added {
            println!("{} gained {}/{}", interface.name, addr.ip, addr.prefix_len);
        }
        for addr in &diff.addrs_removed {
            println!("{} lost {}/{}", interface.name, addr.ip, addr.prefix_len);
        }
    }
})
.unwrap();

// Keep `handle` alive as long as you want callbacks.
// ...
drop(handle);

§Sync blocking watch

Park the current thread until a change notification is available.

let mut watch = netwatcher::watch_interfaces_blocking().unwrap();

loop {
    let update = watch.changed();
    println!("Initial update: {}", update.is_initial);
    println!("Current interface map: {:#?}", update.interfaces);
}

§Async watch

.await interface changes. This requires a small amount of integration with your async runtime. You will probably want to enable a crate feature such as tokio or async-io to use the provided adapter.

use netwatcher::async_adapter::Tokio;

let runtime = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .build()
    .unwrap();

runtime.block_on(async {
    let mut watch = netwatcher::watch_interfaces_async::<Tokio>().unwrap();

    loop {
        let update = watch.changed().await;
        println!("Initial update: {}", update.is_initial);
        println!("Current interface map: {:#?}", update.interfaces);
    }
});

Modules§

async_adapter

Structs§

AsyncWatch: A handle that yields Updates asynchronously when network interfaces change.
BlockingWatch: A handle that yields Updates synchronously when network interfaces change.
Interface: Information about one network interface at a point in time.
InterfaceDiff: What changed within a single interface between updates, if it was present in both.
IpRecord: An IP address paired with its prefix length (network mask).
Update: Information delivered when a network interface snapshot changes.
UpdateDiff: What changed between one Update and the next.
WatchHandle: A handle to keep alive as long as you wish to receive callbacks.

Enums§

Error: Errors in netwatcher or in one of the underlying platform integrations.

Functions§

list_interfaces: Retrieve information about all enabled network interfaces and their IP addresses.
watch_interfaces_async: Retrieve interface information and watch for changes asynchronously using the given runtime adapter.
watch_interfaces_blocking: Retrieve interface information and watch for changes synchronously.
watch_interfaces_with_callback: Retrieve interface information and watch for changes, which will be delivered via callback.