Struct IcmpEchoRequestor 

pub struct IcmpEchoRequestor { /* private fields */ }

Requestor for sending ICMP Echo Requests (ping) and receiving replies on Windows.

This implementation uses Windows-specific APIs (IcmpSendEcho2Ex and Icmp6SendEcho2) that provide unprivileged ICMP functionality without requiring administrator rights. The requestor is safe to clone and use across multiple threads and async tasks.

Examples

use ping_async::IcmpEchoRequestor;
use std::net::IpAddr;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let target = "8.8.8.8".parse::<IpAddr>().unwrap();
    let pinger = IcmpEchoRequestor::new(target, None, None, None)?;
     
    let reply = pinger.send().await?;
    println!("Reply: {:?}", reply);
     
    Ok(())
}

Implementations

impl IcmpEchoRequestor

pub fn new( target_addr: IpAddr, source_addr: Option<IpAddr>, ttl: Option<u8>, timeout: Option<Duration>, ) -> Result<Self>

Creates a new ICMP echo requestor for the specified target address.

Arguments

• target_addr - The IP address to ping (IPv4 or IPv6)
• source_addr - Optional source IP address to bind to. Must match the IP version of target_addr
• ttl - Optional Time-To-Live value. Defaults to PING_DEFAULT_TTL
• timeout - Optional timeout duration. Defaults to PING_DEFAULT_TIMEOUT

Errors

Returns an error if:

• The source address type doesn’t match the target address type (IPv4 vs IPv6)
• Windows ICMP handle creation fails (rare, typically indicates system resource issues)

Platform Notes

On Windows, this uses IcmpCreateFile() for IPv4 or Icmp6CreateFile() for IPv6. These APIs don’t require administrator privileges.

Examples

use ping_async::IcmpEchoRequestor;
use std::net::IpAddr;
use std::time::Duration;

// Basic usage with defaults
let pinger = IcmpEchoRequestor::new(
    "8.8.8.8".parse().unwrap(),
    None,
    None,
    None
)?;

// With custom timeout and TTL
let pinger = IcmpEchoRequestor::new(
    "2001:4860:4860::8888".parse().unwrap(),
    None,
    Some(64),
    Some(Duration::from_millis(500))
)?;

pub async fn send(&self) -> Result<IcmpEchoReply>

Sends an ICMP echo request and waits for a reply.

This method is async and will complete when either:

• An echo reply is received
• The configured timeout expires
• An error occurs

The requestor can be used multiple times and is safe to use concurrently from multiple async tasks.

Returns

Returns an IcmpEchoReply containing:

• The destination IP address
• The status of the ping operation
• The measured round-trip time

Errors

Returns an error if:

• The underlying Windows API call fails
• Internal communication channels fail unexpectedly

Note that timeout and unreachable conditions are returned as successful IcmpEchoReply with appropriate status values, not as errors.

Examples

use ping_async::{IcmpEchoRequestor, IcmpEchoStatus};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let pinger = IcmpEchoRequestor::new(
        "8.8.8.8".parse().unwrap(),
        None, None, None
    )?;
     
    let reply = pinger.send().await?;
     
    match reply.status() {
        IcmpEchoStatus::Success => {
            println!("Ping successful: {:?}", reply.round_trip_time());
        }
        IcmpEchoStatus::TimedOut => {
            println!("Ping timed out");
        }
        _ => {
            println!("Ping failed: {:?}", reply.status());
        }
    }
     
    Ok(())
}

Trait Implementations

impl Clone for IcmpEchoRequestor

fn clone(&self) -> IcmpEchoRequestor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.