[−][src]Struct pcap::Capture
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>
[src]
pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Capture<Offline>, Error>
[src]
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>
[src]
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 unsafe fn from_raw_fd(fd: RawFd) -> Result<Capture<Offline>, Error>
[src]
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.
pub unsafe fn from_raw_fd_with_precision(
fd: RawFd,
precision: Precision
) -> Result<Capture<Offline>, Error>
[src]
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.
impl Capture<Inactive>
[src]
pub fn from_device<D: Into<Device>>(
device: D
) -> Result<Capture<Inactive>, Error>
[src]
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().unwrap(); 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");
pub fn open(self) -> Result<Capture<Active>, Error>
[src]
Activates an inactive capture created from Capture::from_device()
or returns
an error.
pub fn timeout(self, ms: i32) -> Capture<Inactive>
[src]
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) -> Capture<Inactive>
[src]
Set the time stamp type to be used by a capture device.
pub fn promisc(self, to: bool) -> Capture<Inactive>
[src]
Set promiscuous mode on or off. By default, this is off.
pub fn immediate_mode(self, to: bool) -> Capture<Inactive>
[src]
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
.
pub fn rfmon(self, to: bool) -> Capture<Inactive>
[src]
Set rfmon mode on or off. The default is maintained by pcap.
pub fn buffer_size(self, to: i32) -> Capture<Inactive>
[src]
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) -> Capture<Inactive>
[src]
Set the time stamp precision returned in captures.
pub fn snaplen(self, to: i32) -> Capture<Inactive>
[src]
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]
pub fn list_datalinks(&self) -> Result<Vec<Linktype>, Error>
[src]
List the datalink types that this captured device supports.
pub fn set_datalink(&mut self, linktype: Linktype) -> Result<(), Error>
[src]
Set the datalink type for the current capture handle.
pub fn get_datalink(&self) -> Linktype
[src]
Get the current datalink type for this capture handle.
pub fn savefile<P: AsRef<Path>>(&self, path: P) -> Result<Savefile, Error>
[src]
Create a Savefile
context for recording captured packets using this Capture
's
configurations.
pub unsafe fn savefile_raw_fd(&self, fd: RawFd) -> Result<Savefile, Error>
[src]
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.
pub fn savefile_append<P: AsRef<Path>>(
&self,
path: P
) -> Result<Savefile, Error>
[src]
&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.
pub fn direction(&self, direction: Direction) -> Result<(), Error>
[src]
Set the direction of the capture
pub fn next(&mut self) -> Result<Packet<'_>, Error>
[src]
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>
[src]
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>
[src]
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.
impl Capture<Active>
[src]
pub fn sendpacket<B: Borrow<[u8]>>(&mut self, buf: B) -> Result<(), Error>
[src]
Sends a packet over this capture handle's interface.
pub fn setnonblock(self) -> Result<Capture<Active>, Error>
[src]
Set the capture to be non-blocking. When this is set, next() may return an error indicating that there is no packet available to be read.
impl Capture<Dead>
[src]
pub fn dead(linktype: Linktype) -> Result<Capture<Dead>, Error>
[src]
Creates a "fake" capture handle for the given link type.
pub fn compile(&self, program: &str) -> Result<BpfProgram, Error>
[src]
Compiles the string into a filter program using pcap_compile
.
Trait Implementations
impl AsRawFd for Capture<Active>
[src]
impl<T: State + ?Sized> Drop for Capture<T>
[src]
impl<T: Activated> From<Capture<T>> for Capture<dyn Activated>
[src]
Auto Trait Implementations
impl<T: ?Sized> RefUnwindSafe for Capture<T> where
T: RefUnwindSafe,
[src]
T: RefUnwindSafe,
impl<T: ?Sized> Send for Capture<T> where
T: Send,
[src]
T: Send,
impl<T: ?Sized> Sync for Capture<T> where
T: Sync,
[src]
T: Sync,
impl<T: ?Sized> Unpin for Capture<T> where
T: Unpin,
[src]
T: Unpin,
impl<T: ?Sized> UnwindSafe for Capture<T> where
T: UnwindSafe,
[src]
T: UnwindSafe,
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,