Crate netwatcher 

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.