pub struct Capture<T: State + ?Sized> { /* private fields */ }
Expand description
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_packet()
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 mut cap = Capture::from_device(Device::lookup().unwrap().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_packet() {
println!("received packet! {:?}", packet);
}
Implementations§
source§impl Capture<Offline>
impl Capture<Offline>
sourcepub fn from_file<P: AsRef<Path>>(path: P) -> Result<Capture<Offline>, Error>
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.
sourcepub fn from_file_with_precision<P: AsRef<Path>>(
path: P,
precision: Precision
) -> Result<Capture<Offline>, Error>
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.
sourcepub unsafe fn from_raw_fd(fd: RawFd) -> Result<Capture<Offline>, Error>
pub unsafe fn from_raw_fd(fd: RawFd) -> Result<Capture<Offline>, Error>
Opens an offline capture handle from a pcap dump file, given a file descriptor.
Safety
Unsafe, because the returned Capture assumes it is the sole owner of the file descriptor.
sourcepub unsafe fn from_raw_fd_with_precision(
fd: RawFd,
precision: Precision
) -> Result<Capture<Offline>, Error>
pub unsafe fn from_raw_fd_with_precision( fd: RawFd, precision: Precision ) -> Result<Capture<Offline>, Error>
Opens an offline capture handle from a pcap dump file, given a file descriptor. Takes an additional precision argument specifying the time stamp precision desired.
Safety
Unsafe, because the returned Capture assumes it is the sole owner of the file descriptor.
sourcepub fn major_version(&self) -> i32
pub fn major_version(&self) -> i32
Get the major version number of the pcap dump file format.
sourcepub fn minor_version(&self) -> i32
pub fn minor_version(&self) -> i32
Get the minor version number of the pcap dump file format.
source§impl Capture<Inactive>
impl Capture<Inactive>
sourcepub fn from_device<D: Into<Device>>(
device: D
) -> Result<Capture<Inactive>, Error>
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()
.
Example
use pcap::*;
// Usage 1: Capture from a single owned device
let dev: Device = pcap::Device::lookup()
.expect("device lookup failed")
.expect("no device available");
let cap1 = Capture::from_device(dev);
// Usage 2: Capture from an element of device list.
let list: Vec<Device> = pcap::Device::list().unwrap();
let cap2 = Capture::from_device(list[0].clone());
// Usage 3: Capture from `&str` device name
let cap3 = Capture::from_device("eth0");
sourcepub fn open(self) -> Result<Capture<Active>, Error>
pub fn open(self) -> Result<Capture<Active>, Error>
Activates an inactive capture created from Capture::from_device()
or returns
an error.
sourcepub fn timeout(self, ms: i32) -> Capture<Inactive>
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.
sourcepub fn tstamp_type(self, tstamp_type: TimestampType) -> Capture<Inactive>
pub fn tstamp_type(self, tstamp_type: TimestampType) -> Capture<Inactive>
Set the time stamp type to be used by a capture device.
sourcepub fn promisc(self, to: bool) -> Capture<Inactive>
pub fn promisc(self, to: bool) -> Capture<Inactive>
Set promiscuous mode on or off. By default, this is off.
sourcepub fn immediate_mode(self, to: bool) -> Capture<Inactive>
pub fn immediate_mode(self, to: bool) -> Capture<Inactive>
Set immediate mode on or off. By default, this is off.
Note that in WinPcap immediate mode is set by passing a 0 argument to min_to_copy
.
Immediate mode will be unset if min_to_copy
is later called with a non-zero argument.
Immediate mode is unset by resetting min_to_copy
to the WinPcap default possibly changing
a previously set value. When using min_to_copy
, it is best to avoid immediate_mode
.
sourcepub fn rfmon(self, to: bool) -> Capture<Inactive>
pub fn rfmon(self, to: bool) -> Capture<Inactive>
Set rfmon mode on or off. The default is maintained by pcap.
sourcepub fn buffer_size(self, to: i32) -> Capture<Inactive>
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.
source§impl<T: Activated + ?Sized> Capture<T>
impl<T: Activated + ?Sized> Capture<T>
sourcepub fn list_datalinks(&self) -> Result<Vec<Linktype>, Error>
pub fn list_datalinks(&self) -> Result<Vec<Linktype>, Error>
List the datalink types that this captured device supports.
sourcepub fn set_datalink(&mut self, linktype: Linktype) -> Result<(), Error>
pub fn set_datalink(&mut self, linktype: Linktype) -> Result<(), Error>
Set the datalink type for the current capture handle.
sourcepub fn get_datalink(&self) -> Linktype
pub fn get_datalink(&self) -> Linktype
Get the current datalink type for this capture handle.
sourcepub fn savefile<P: AsRef<Path>>(&self, path: P) -> Result<Savefile, Error>
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.
sourcepub unsafe fn savefile_raw_fd(&self, fd: RawFd) -> Result<Savefile, Error>
pub unsafe 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 in "w"
mode.
Safety
Unsafe, because the returned Savefile assumes it is the sole owner of the file descriptor.
sourcepub fn savefile_append<P: AsRef<Path>>(
&self,
path: P
) -> Result<Savefile, Error>
pub fn savefile_append<P: AsRef<Path>>( &self, path: P ) -> Result<Savefile, Error>
Reopen a Savefile
context for recording captured packets using this Capture
’s
configurations. This is similar to savefile()
but does not create the file if it
does not exist and, if it does already exist, and is a pcap file with the same
byte order as the host opening the file, and has the same time stamp precision,
link-layer header type, and snapshot length as p, it will write new packets
at the end of the file.
sourcepub fn direction(&self, direction: Direction) -> Result<(), Error>
pub fn direction(&self, direction: Direction) -> Result<(), Error>
Set the direction of the capture
sourcepub fn next_packet(&mut self) -> Result<Packet<'_>, Error>
pub fn next_packet(&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.
Warning
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 to next_packet() method.
sourcepub fn iter<C: PacketCodec>(self, codec: C) -> PacketIter<T, C> ⓘ
pub fn iter<C: PacketCodec>(self, codec: C) -> PacketIter<T, C> ⓘ
Return an iterator that call Self::next_packet()
forever. Require a PacketCodec
sourcepub fn stream<C: PacketCodec>(
self,
codec: C
) -> Result<PacketStream<T, C>, Error>
pub fn stream<C: PacketCodec>( self, codec: C ) -> Result<PacketStream<T, C>, Error>
Returns this capture as a [futures::Stream
] of packets.
Errors
If this capture is set to be blocking, or if the network device
does not support select()
, an error will be returned.
sourcepub fn filter(&mut self, program: &str, optimize: bool) -> Result<(), Error>
pub fn filter(&mut self, program: &str, optimize: bool) -> Result<(), Error>
Sets the filter on the capture using the given BPF program string. Internally this is
compiled using pcap_compile()
. optimize
controls whether optimization on the resulting
code is performed
See http://biot.com/capstats/bpf.html for more information about this syntax.
sourcepub fn stats(&mut self) -> Result<Stat, Error>
pub fn stats(&mut self) -> Result<Stat, Error>
Get capture statistics about this capture. The values represent packet statistics from the start of the run to the time of the call.
See https://www.tcpdump.org/manpages/pcap_stats.3pcap.html for per-platform caveats about how packet statistics are calculated.
source§impl Capture<Active>
impl Capture<Active>
sourcepub fn sendpacket<B: Borrow<[u8]>>(&mut self, buf: B) -> Result<(), Error>
pub fn sendpacket<B: Borrow<[u8]>>(&mut self, buf: B) -> Result<(), Error>
Sends a packet over this capture handle’s interface.
sourcepub fn setnonblock(self) -> Result<Capture<Active>, Error>
pub fn setnonblock(self) -> Result<Capture<Active>, Error>
Set the capture to be non-blocking. When this is set, Self::next_packet()
may return an error indicating
that there is no packet available to be read.
source§impl Capture<Dead>
impl Capture<Dead>
sourcepub fn dead(linktype: Linktype) -> Result<Capture<Dead>, Error>
pub fn dead(linktype: Linktype) -> Result<Capture<Dead>, Error>
Creates a “fake” capture handle for the given link type.