Struct pcap::Capture

pub struct Capture<T: State + ?Sized> { /* 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.

Capture<Dead> is created via Capture::dead(). This allows you to create a pcap format dump file without needing an active capture.

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>

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.

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

Opens an offline capture handle from a pcap dump file, given a path. Takes an additional precision argument specifying the time stamp precision desired.

fn from_raw_fd(fd: RawFd) -> Result<Capture<Offline>, Error>

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

impl Capture<Inactive>

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 tstamp_type(self, tstamp_type: TimestampType) -> Capture<Inactive>

Set the time stamp type to be used by a capture device.

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

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

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

Set rfmon mode on or off. The default is maintained by pcap.

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 precision(self, precision: Precision) -> Capture<Inactive>

Set the time stamp precision returned in captures.

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>

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

fn list_datalinks(&self) -> Result<Vec<Linktype>, Error>

List the datalink types that this captured device supports.

fn set_datalink(&mut self, linktype: Linktype) -> Result<(), Error>

Set the datalink type for the current capture handle.

fn get_datalink(&self) -> Linktype

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 savefile_raw_fd(&self, fd: RawFd) -> Result<Savefile, Error>

Create a Savefile context for recording captured packets using this Capture's configurations. The output is written to a raw file descriptor which is opened

fn direction(&self, direction: Direction) -> Result<(), Error>

Set the direction of the capture

fn next(&mut self) -> Result<Packet, 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>

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

Sends a packet over this capture handle's interface.

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

impl Capture<Dead>

fn dead(linktype: Linktype) -> Result<Capture<Dead>, Error>

Creates a "fake" capture handle for the given link type.

Trait Implementations

impl AsRawFd for Capture<Active>

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

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

fn drop(&mut self)

A method called when the value goes out of scope.

impl<T: Activated> From<Capture<T>> for Capture<Activated>

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

Performs the conversion.