ping-fox

Crates.ioping-fox
lib.rsping-fox
version0.1.0
sourcesrc
created_at2023-04-23 18:40:23.279602
updated_at2023-04-23 18:40:23.279602
descriptionA ping (ICMP) library - simple to use and no root or setuid required.
homepagehttps://github.com/rng-dynamics/ping-fox
repositoryhttps://github.com/rng-dynamics/ping-fox
max_upload_size
id846740
size77,754
(rng-dynamics)

documentation

README

ping-fox

GitHub Workflow Status (with branch) Coveralls branch

A ping (ICMP) library - simple to use and no root or setuid required.

Getting Started

In ping-fox a PingSentToken represents an evidence that a ping message has been sent. Each call to PingSender::send_to returns a PingSentToken which can be used to call PingReceiver::recieve. This makes sure that PingSender::recieve is never called without a previous call to PingSender::send_to.

The following example describes how to configure ping-fox and how to send and receive an echo messages and its response.

# Cargo.toml

[dependencies]
ping-fox = "0.1"

// .rs file

use ping_fox::{PingFoxConfig, PingReceive, PingReceiveData, PingSentToken, SocketType};
use std::net::Ipv4Addr;
use std::time::Duration;

// ### Configure the library:
// - `socket_type` can be `SocketType::RAW` or `SocketType::DGRAM`.
// - Use `SocketType::DGRAM` to avoid the need for elevated privileges.
let config = PingFoxConfig {
    socket_type: SocketType::DGRAM,
    timeout: Duration::from_secs(1),
    channel_size: 1,
};

// ### Create a ping sender and a ping receiver.
let (mut ping_sender, mut ping_receiver) = ping_fox::create(&config).unwrap();

// ### Call `PingSender::send_to`
let token: PingSentToken = ping_sender
    .send_to("127.0.0.1".parse::<Ipv4Addr>().unwrap())
    .unwrap();

// ### Use the `PingSentToken` to call `PingReceiver::receive`.
let ping_response = ping_receiver.receive(token).unwrap();

// ### Read the ping result.
match ping_response {
    PingReceive::Data(PingReceiveData {
        package_size,
        ip_addr,
        ttl,
        sequence_number,
        ping_duration,
    }) => {
        println!(
            "{package_size} bytes from {ip_addr}: \
              icmp_seq={sequence_number} ttl={ttl} \
              time={ping_duration:?}",
        );
    }
    PingReceive::Timeout => {
        println!("timeout");
    }
};

Examples

There are some examples in the example folder.

Running the tests

  • cargo run --lib will run the unit tests.
  • We can run unit and integration tests with cargo test, but it will need elevated privileges for some of the tests using a raw socket. If we do not have privileges, some tests will fail.

Built With

Contributing

Contributions are welcome. Please open an issue and we can discuss the specifics.

License

This project is licensed under the BSD-3-Clause license - see the LICENSE.md file for details

Commit count: 38

cargo fmt