Struct pcap::Capture [−] [src]

pub struct Capture<T: State + ?Sized> {
    // some fields omitted
}

This is a pcap capture handle which is an abstraction over the pcap_t provided by pcap. There are many ways to instantiate and interact with a pcap handle, so phantom types are used to express these behaviors.

Capture<Inactive> is created via Capture::from_device(). This handle is inactive, so you cannot (yet) obtain packets from it. However, you can configure things like the buffer size, snaplen, timeout, and promiscuity before you activate it.

Capture<Active> is created by calling .open() on a Capture<Inactive>. This activates the capture handle, allowing you to get packets with .next() or apply filters with .filter().

Capture<Offline> is created via Capture::from_file(). This allows you to read a pcap format dump file as if you were opening an interface -- very useful for testing or analysis.

Example:

let cap = Capture::from_device(Device::lookup().unwrap()) // open the "default" interface
              .unwrap() // assume the device exists and we are authorized to open it
              .open() // activate the handle
              .unwrap(); // assume activation worked

while let Ok(packet) = cap.next() {
    println!("received packet! {:?}", packet);
}

Methods

impl Capture<Offline>
[src]

fn from_file<P: AsRef<Path>>(path: P) -> Result<Capture<Offline>, Error>

Opens an offline capture handle from a pcap dump file, given a path.

impl Capture<Inactive>
[src]

fn from_device<D: Into<Device>>(device: D) -> Result<Capture<Inactive>, Error>

Opens a capture handle for a device. You can pass a Device or an &str device name here. The handle is inactive, but can be activated via .open().

fn open(self) -> Result<Capture<Active>, Error>

Activates an inactive capture created from Capture::from_device() or returns an error.

fn timeout(self, ms: i32) -> Capture<Inactive>

Set the read timeout for the Capture. By default, this is 0, so it will block indefinitely.

fn promisc(self, to: bool) -> Capture<Inactive>

Set promiscuous mode on or off. By default, this is off.

fn buffer_size(self, to: i32) -> Capture<Inactive>

Set the buffer size for incoming packet data.

The default is 1000000. This should always be larger than the snaplen.

fn snaplen(self, to: i32) -> Capture<Inactive>

Set the snaplen size (the maximum length of a packet captured into the buffer). Useful if you only want certain headers, but not the entire packet.

The default is 65535

impl<T: Activated + ?Sized> Capture<T>
[src]

Activated captures include Capture<Active> and Capture<Offline>.

List the datalink types that this captured device supports.

Set the datalink type for the current capture handle.

Get the current datalink type for this capture handle.

fn savefile<P: AsRef<Path>>(&self, path: P) -> Result<Savefile, Error>

Create a Savefile context for recording captured packets using this Capture's configurations.

fn next<'a>(&'a mut self) -> Result<Packet<'a>, Error>

Blocks until a packet is returned from the capture handle or an error occurs.

pcap captures packets and places them into a buffer which this function reads from. This buffer has a finite length, so if the buffer fills completely new packets will be discarded temporarily. This means that in realtime situations, you probably want to minimize the time between calls of this next() method.

fn filter(&mut self, program: &str) -> Result<(), Error>

Adds a filter to the capture using the given BPF program string. Internally this is compiled using pcap_compile().

See http://biot.com/capstats/bpf.html for more information about this syntax.

fn stats(&mut self) -> Result<Stat, Error>

impl Capture<Active>
[src]

fn sendpacket<'a>(&mut self, buf: &'a [u8]) -> Result<(), Error>

Sends a packet over this capture handle's interface.

Trait Implementations

impl<T: State + ?Sized> Drop for Capture<T>
[src]

fn drop(&mut self)

A method called when the value goes out of scope. Read more

impl<T: Activated> From<Capture<T>> for Capture<Activated>
[src]

fn from(cap: Capture<T>) -> Capture<Activated>

Performs the conversion.