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);
}

Implementations

impl Capture<Offline>

pub 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.

pub 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.

pub 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>

pub 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().

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

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

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

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

pub fn tstamp_type(
    self,
    tstamp_type: TimestampType
) -> Result<Capture<Inactive>, Error>

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

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

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

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

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

pub 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.

pub fn precision(self, precision: Precision) -> Result<Capture<Inactive>, Error>

Set the time stamp precision returned in captures.

pub 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.

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

impl<T: Activated + ?Sized> Capture<T>

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

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

List the datalink types that this captured device supports.

pub fn get_datalink(&self) -> Linktype

Get the current datalink type for this capture handle.

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

Set the datalink type for the current capture handle.

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

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

pub fn savefile_raw_fd(&self, fd: c_int) -> 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

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

Set the direction of the capture

pub 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.

pub 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.

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

impl Capture<Active>

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

Sends a packet over this capture handle's interface.

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

impl Capture<Dead>

pub 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>

pub fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

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

pub fn drop(&mut self)

Executes the destructor for this type.

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

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

Performs the conversion.