PcapPlusPlus
22.11
|
#include <PcapLiveDevice.h>
Classes | |
struct | DeviceConfiguration |
Public Types | |
enum | LiveDeviceType { LibPcapDevice, WinPcapDevice, RemoteDevice } |
enum | DeviceMode { Normal = 0, Promiscuous = 1 } |
enum | PcapDirection { PCPP_INOUT = 0, PCPP_IN, PCPP_OUT } |
Public Member Functions | |
virtual | ~PcapLiveDevice () |
virtual LiveDeviceType | getDeviceType () const |
std::string | getName () const |
std::string | getDesc () const |
bool | getLoopback () const |
virtual uint32_t | getMtu () const |
virtual LinkLayerType | getLinkType () const |
const std::vector< pcap_addr_t > & | getAddresses () const |
virtual MacAddress | getMacAddress () const |
IPv4Address | getIPv4Address () const |
IPv6Address | getIPv6Address () const |
IPv4Address | getDefaultGateway () const |
const std::vector< IPv4Address > & | getDnsServers () const |
virtual bool | startCapture (OnPacketArrivesCallback onPacketArrives, void *onPacketArrivesUserCookie) |
virtual bool | startCapture (OnPacketArrivesCallback onPacketArrives, void *onPacketArrivesUserCookie, int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate, void *onStatsUpdateUserCookie) |
virtual bool | startCapture (int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate, void *onStatsUpdateUserCookie) |
virtual bool | startCapture (RawPacketVector &capturedPacketsVector) |
virtual int | startCaptureBlockingMode (OnPacketArrivesStopBlocking onPacketArrives, void *userCookie, int timeout) |
void | stopCapture () |
bool | captureActive () |
bool | doMtuCheck (int packetPayloadLength) |
bool | sendPacket (RawPacket const &rawPacket, bool checkMtu=false) |
bool | sendPacket (const uint8_t *packetData, int packetDataLength, int packetPayloadLength) |
bool | sendPacket (const uint8_t *packetData, int packetDataLength, bool checkMtu=false, pcpp::LinkLayerType linkType=pcpp::LINKTYPE_ETHERNET) |
bool | sendPacket (Packet *packet, bool checkMtu=true) |
virtual int | sendPackets (RawPacket *rawPacketsArr, int arrLength, bool checkMtu=false) |
virtual int | sendPackets (Packet **packetsArr, int arrLength, bool checkMtu=true) |
virtual int | sendPackets (const RawPacketVector &rawPackets, bool checkMtu=false) |
bool | open () |
bool | open (const DeviceConfiguration &config) |
void | close () |
PcapLiveDevice * | clone () |
virtual void | getStatistics (IPcapDevice::PcapStats &stats) const |
Public Member Functions inherited from pcpp::IPcapDevice | |
virtual bool | setFilter (std::string filterAsString) |
bool | clearFilter () |
Public Member Functions inherited from pcpp::IDevice | |
bool | isOpened () |
Public Member Functions inherited from pcpp::IFilterableDevice | |
virtual bool | setFilter (GeneralFilter &filter) |
Additional Inherited Members | |
Static Public Member Functions inherited from pcpp::IPcapDevice | |
static std::string | getPcapLibVersionInfo () |
static bool | matchPacketWithFilter (GeneralFilter &filter, RawPacket *rawPacket) |
A class that wraps a network interface (each of the interfaces listed in ifconfig/ipconfig). This class wraps the libpcap capabilities of capturing packets from the network, filtering packets and sending packets back to the network. This class is relevant for Linux applications only. On Windows the WinPcapLiveDevice (which inherits this class) is used. Both classes are almost similar in capabilities, the main difference between them is adapting some capabilities to the specific OS. This class cannot be instantiated by the user (it has a private constructor), as network interfaces aren't dynamic. Instances of this class (one instance per network interface) are created by PcapLiveDeviceList singleton on application startup and the user can get access to them by using PcapLiveDeviceList public methods such as PcapLiveDeviceList::getPcapLiveDeviceByIp()
Main capabilities of this class:
Set direction for capturing packets (you can read more here: https://www.tcpdump.org/manpages/pcap.3pcap.html#lbAI)
Enumerator | |
---|---|
PCPP_INOUT | Capture traffics both incoming and outgoing |
PCPP_IN | Only capture incoming traffics |
PCPP_OUT | Only capture outgoing traffics |
|
virtual |
A destructor for this class
bool pcpp::PcapLiveDevice::captureActive | ( | ) |
Check if a capture thread is running
PcapLiveDevice* pcpp::PcapLiveDevice::clone | ( | ) |
Clones the current device class
|
virtual |
bool pcpp::PcapLiveDevice::doMtuCheck | ( | int | packetPayloadLength | ) |
Checks whether the packetPayloadLength is larger than the device MTU. Logs an error if check fails
[in] | packetPayloadLength | The length of the IP layer of the packet |
|
inline |
IPv4Address pcpp::PcapLiveDevice::getDefaultGateway | ( | ) | const |
|
inline |
|
inlinevirtual |
Reimplemented in pcpp::PcapRemoteDevice, and pcpp::WinPcapLiveDevice.
const std::vector<IPv4Address>& pcpp::PcapLiveDevice::getDnsServers | ( | ) | const |
IPv4Address pcpp::PcapLiveDevice::getIPv4Address | ( | ) | const |
IPv6Address pcpp::PcapLiveDevice::getIPv6Address | ( | ) | const |
|
inlinevirtual |
|
inline |
|
inlinevirtual |
Reimplemented in pcpp::PcapRemoteDevice.
|
inlinevirtual |
Reimplemented in pcpp::PcapRemoteDevice.
|
inline |
|
virtual |
Get statistics from the device
[out] | stats | An object containing the stats |
Implements pcpp::IPcapDevice.
Reimplemented in pcpp::PcapRemoteDevice.
|
virtual |
Open the device using libpcap pcap_open_live. Opening the device only makes the device ready for use, it doesn't start packet capturing. For packet capturing the user should call startCapture(). This implies that calling this method is a must before calling startCapture() (otherwise startCapture() will fail with a "device not open" error). The device is opened in promiscuous mode
Implements pcpp::IDevice.
Reimplemented in pcpp::PcapRemoteDevice.
bool pcpp::PcapLiveDevice::open | ( | const DeviceConfiguration & | config | ) |
Enables to open a device in a non-default configuration. Configuration has parameters like packet buffer timeout & size, open in promiscuous/non-promiscuous mode, etc. Please check DeviceConfiguration for more details
[in] | config | The requested configuration |
bool pcpp::PcapLiveDevice::sendPacket | ( | RawPacket const & | rawPacket, |
bool | checkMtu = false |
||
) |
Send a RawPacket to the network
[in] | rawPacket | A reference to the raw packet to send. This method treats the raw packet as read-only, it doesn't change anything in it |
[in] | checkMtu | Whether the length of the packet's payload should be checked against the MTU. If enabled this comes with a small performance penalty. Default value is false to avoid performance overhead. Set to true if you don't know whether packets fit the live device's MTU and you can afford the overhead. |
bool pcpp::PcapLiveDevice::sendPacket | ( | const uint8_t * | packetData, |
int | packetDataLength, | ||
int | packetPayloadLength | ||
) |
Send a buffer containing packet raw data (including all layers) to the network. This particular version of the sendPacket method should only be used if you already have access to the size of the network layer of the packet, since it allows you to check the payload size (see packetPayloadLength parameter) MTU of the live device without incurring a parsing overhead. If the packetPayloadLength is unknown, please use a different implementation of the sendPacket method.
[in] | packetData | The buffer containing the packet raw data |
[in] | packetDataLength | The length of the buffer (this is the entire packet, including link layer) |
[in] | packetPayloadLength | The length of the payload for the data link layer. This includes all data apart from the header for the data link layer. |
bool pcpp::PcapLiveDevice::sendPacket | ( | const uint8_t * | packetData, |
int | packetDataLength, | ||
bool | checkMtu = false , |
||
pcpp::LinkLayerType | linkType = pcpp::LINKTYPE_ETHERNET |
||
) |
Send a buffer containing packet raw data (including all layers) to the network
[in] | packetData | The buffer containing the packet raw data |
[in] | packetDataLength | The length of the buffer |
[in] | checkMtu | Whether the length of the packet's payload should be checked against the MTU. If enabled this comes with a small performance penalty. Default value is false to avoid performance overhead. Set to true if you don't know whether packets fit the live device's MTU and you can afford the overhead. |
[in] | linkType | Only used if checkMtu is true. Defines the layer type for parsing the first layer of the packet. Used for parsing the packet to perform the MTU check. Default value is pcpp::LINKTYPE_ETHERNET. Ensure this parameter matches the linktype of the packet if checkMtu is true. |
bool pcpp::PcapLiveDevice::sendPacket | ( | Packet * | packet, |
bool | checkMtu = true |
||
) |
Send a parsed Packet to the network
[in] | packet | A pointer to the packet to send. This method treats the packet as read-only, it doesn't change anything in it |
[in] | checkMtu | Whether the length of the packet's payload should be checked against the MTU. Default value is true, since the packet being passed in has already been parsed, so checking the MTU does not incur significant processing overhead. |
|
virtual |
Send an array of RawPacket objects to the network
[in] | rawPacketsArr | The array of RawPacket objects to send. This method treats all packets as read-only, it doesn't change anything in them |
[in] | arrLength | The length of the array |
[in] | checkMtu | Whether to check the size of the packet payload against MTU size. Incurs a parsing overhead. Default value is false to avoid performance overhead. Set to true if you don't know whether packets fit the live device's MTU and you can afford the overhead. |
|
virtual |
Send an array of pointers to Packet objects to the network
[in] | packetsArr | The array of pointers to Packet objects to send. This method treats all packets as read-only, it doesn't change anything in them |
[in] | arrLength | The length of the array |
[in] | checkMtu | Whether to check the size of the packet payload against MTU size. Default value is true, since the packets being passed in has already been parsed, so checking the MTU does not incur significant processing overhead. |
|
virtual |
Send a vector of pointers to RawPacket objects to the network
[in] | rawPackets | The array of pointers to RawPacket objects to send. This method treats all packets as read-only, it doesn't change anything in them |
[in] | checkMtu | Whether to check the size of the packet payload against MTU size. Incurs a parsing overhead. Default value is false to avoid performance overhead. Set to true if you don't know whether packets fit the live device's MTU and you can afford the overhead. |
|
virtual |
Start capturing packets on this network interface (device). Each time a packet is captured the onPacketArrives callback is called. The capture is done on a new thread created by this method, meaning all callback calls are done in a thread other than the caller thread. Capture process will stop and this capture thread will be terminated when calling stopCapture(). This method must be called after the device is opened (i.e the open() method was called), otherwise an error will be returned.
[in] | onPacketArrives | A callback that is called each time a packet is captured |
[in] | onPacketArrivesUserCookie | A pointer to a user provided object. This object will be transferred to the onPacketArrives callback each time it is called. This cookie is very useful for transferring objects that give context to the capture callback, for example: objects that counts packets, manages flow state or manages the application state according to the packet that was captured |
|
virtual |
Start capturing packets on this network interface (device) with periodic stats collection. Each time a packet is captured the onPacketArrives callback is called. In addition, each intervalInSecondsToUpdateStats seconds stats are collected from the device and the onStatsUpdate callback is called. Both the capture and periodic stats collection are done on new threads created by this method, each on a different thread, meaning all callback calls are done in threads other than the caller thread. Capture process and stats collection will stop and threads will be terminated when calling stopCapture(). This method must be called after the device is opened (i.e the open() method was called), otherwise an error will be returned.
[in] | onPacketArrives | A callback that is called each time a packet is captured |
[in] | onPacketArrivesUserCookie | A pointer to a user provided object. This object will be transferred to the onPacketArrives callback each time it is called. This cookie is very useful for transferring objects that give context to the capture callback, for example: objects that counts packets, manages flow state or manages the application state according to the packet that was captured |
[in] | intervalInSecondsToUpdateStats | The interval in seconds to activate periodic stats collection |
[in] | onStatsUpdate | A callback that will be called each time intervalInSecondsToUpdateStats expires and stats are collected. This callback will contain the collected stats |
[in] | onStatsUpdateUserCookie | A pointer to a user provided object. This object will be transferred to the onStatsUpdate callback each time it is called |
Reimplemented in pcpp::WinPcapLiveDevice.
|
virtual |
Start capturing packets on this network interface (device) with periodic stats collection only. This means that packets arriving to the network interface aren't delivered to the user but only counted. Each intervalInSecondsToUpdateStats seconds stats are collected from the device and the onStatsUpdate callback is called with the updated counters. The periodic stats collection is done on a new thread created by this method, meaning all callback calls are done in threads other than the caller thread. Stats collection will stop and threads will be terminated when calling stopCapture(). This method must be called after the device is opened (i.e the open() method was called), otherwise an error will be returned.
[in] | intervalInSecondsToUpdateStats | The interval in seconds to activate periodic stats collection |
[in] | onStatsUpdate | A callback that will be called each time intervalInSecondsToUpdateStats expires and stats are collected. This callback will contain the collected stats |
[in] | onStatsUpdateUserCookie | A pointer to a user provided object. This object will be transferred to the onStatsUpdate callback each time it is called |
Reimplemented in pcpp::WinPcapLiveDevice.
|
virtual |
Start capturing packets on this network interface (device). All captured packets are added to capturedPacketsVector, so at the end of the capture (when calling stopCapture()) this vector contains pointers to all captured packets in the form of RawPacket. The capture is done on a new thread created by this method, meaning capturedPacketsVector is updated from another thread other than the caller thread (so user should avoid changing or iterating this vector while capture is on). Capture process will stop and this capture thread will be terminated when calling stopCapture(). This method must be called after the device is opened (i.e the open() method was called), otherwise an error will be returned.
[in] | capturedPacketsVector | A reference to a RawPacketVector, meaning a vector of pointer to RawPacket objects |
Reimplemented in pcpp::WinPcapLiveDevice.
|
virtual |
Start capturing packets on this network interface (device) in blocking mode, meaning this method blocks and won't return until the user frees the blocking (via onPacketArrives callback) or until a user defined timeout expires. Whenever a packets is captured the onPacketArrives callback is called and lets the user handle the packet. In each callback call the user should return true if he wants to release the block or false if it wants it to keep blocking. Regardless of this callback a timeout is defined when start capturing. When this timeout expires the method will return.
Please notice that stopCapture() isn't needed here because when the method returns (after timeout or per user decision) capturing on the device is stopped
[in] | onPacketArrives | A callback given by the user for handling incoming packets. After handling each packet the user needs to return a boolean value. True value indicates stop capturing and stop blocking and false value indicates continue capturing and blocking |
[in] | userCookie | A pointer to a user provided object. This object will be transferred to the onPacketArrives callback each time it is called. This cookie is very useful for transferring objects that give context to the capture callback, for example: objects that counts packets, manages flow state or manages the application state according to the packet that was captured |
[in] | timeout | A timeout in seconds for the blocking to stop even if the user didn't return "true" in the onPacketArrives callback If this timeout is set to 0 or less the timeout will be ignored, meaning the method will keep blocking until the user frees it via the onPacketArrives callback |
void pcpp::PcapLiveDevice::stopCapture | ( | ) |
Stop a currently running packet capture. This method terminates gracefully both packet capture thread and periodic stats collection thread (both if exist)