Crate netwatcher 

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

Watch options

• watch_interfaces_with_callback: simplest callback-based API. On Linux and Apple platforms this creates a background thread.
• watch_interfaces_blocking: waits in the current thread until there is an interface change.
• watch_interfaces_async::<T>: allows you to .await interface changes by integrating

Callback watch example

let handle = netwatcher::watch_interfaces_with_callback(|update| {
    println!("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);

Blocking watch example

changed() waits forever if nothing changes, so it is intended for a thread or program that has no other work to do until an interface change arrives.

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 example

You will probably want to enable a crate feature such as tokio or async-io in order to use the adapter appropriate for your async runtime.

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.