PcapPlusPlus  20.08+
pcpp::PfRingDevice Class Reference

#include <PfRingDevice.h>

Inheritance diagram for pcpp::PfRingDevice:
pcpp::IDevice pcpp::IFilterableDevice

Classes

struct  PfRingStats
 

Public Types

enum  ChannelDistribution { RoundRobin, PerFlow }
 

Public Member Functions

 ~PfRingDevice ()
 
MacAddress getMacAddress ()
 
int getInterfaceIndex ()
 
int getMtu ()
 
bool isHwClockEnabledForDevice ()
 
std::string getDeviceName () const
 
bool startCaptureSingleThread (OnPfRingPacketsArriveCallback onPacketsArrive, void *onPacketsArriveUserCookie)
 
bool startCaptureMultiThread (OnPfRingPacketsArriveCallback onPacketsArrive, void *onPacketsArriveUserCookie, CoreMask coreMask)
 
void stopCapture ()
 
bool openSingleRxChannel (uint8_t channelId)
 
bool openMultiRxChannels (const uint8_t *channelIds, int numOfChannelIds)
 
bool openMultiRxChannels (uint8_t numOfRxChannelsToOpen, ChannelDistribution dist)
 
uint8_t getNumOfOpenedRxChannels () const
 
uint8_t getTotalNumOfRxChannels () const
 
SystemCore getCurrentCoreId () const
 
void getThreadStatistics (SystemCore core, PfRingStats &stats) const
 
void getCurrentThreadStatistics (PfRingStats &stats) const
 
void getStatistics (PfRingStats &stats) const
 
bool isFilterCurrentlySet () const
 
bool sendPacket (const RawPacket &rawPacket)
 
bool sendPacket (const uint8_t *packetData, int packetDataLength)
 
bool sendPacket (const Packet &packet)
 
int sendPackets (const RawPacket *rawPacketsArr, int arrLength)
 
int sendPackets (const Packet **packetsArr, int arrLength)
 
int sendPackets (const RawPacketVector &rawPackets)
 
bool open ()
 
void close ()
 
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)
 

Detailed Description

A class representing a PF_RING port

Member Enumeration Documentation

◆ ChannelDistribution

An enum representing the type of packet distribution between different RX channels

Enumerator
RoundRobin 

Packets are distributed between channels in a round-robin manner

PerFlow 

Packets are distributed between channels per flow (each flow goes for different channel)

Constructor & Destructor Documentation

◆ ~PfRingDevice()

pcpp::PfRingDevice::~PfRingDevice ( )

A destructor for PfRingDevice class

Member Function Documentation

◆ clearFilter()

bool pcpp::PfRingDevice::clearFilter ( )
virtual

Remove a filter if currently set

Returns
True if filter was removed successfully or if no filter was set, false otherwise

Implements pcpp::IFilterableDevice.

◆ close()

void pcpp::PfRingDevice::close ( )
virtual

Closes all RX channels currently opened in device

Implements pcpp::IDevice.

◆ getCurrentCoreId()

SystemCore pcpp::PfRingDevice::getCurrentCoreId ( ) const

Gets the core used in the current thread context

Returns
The system core used in the current thread context

◆ getCurrentThreadStatistics()

void pcpp::PfRingDevice::getCurrentThreadStatistics ( PfRingStats stats) const

Get the statistics of the current thread/core (=RX channel)

Parameters
[out]statsA reference for the stats object where the stats are written. Current values will be overriden

◆ getDeviceName()

std::string pcpp::PfRingDevice::getDeviceName ( ) const
inline

Gets the interface name (e.g eth0, eth1, etc.)

Returns
The interface name

◆ getInterfaceIndex()

int pcpp::PfRingDevice::getInterfaceIndex ( )
inline

Get PF_RING interface index of the current device

Returns
PF_RING interface index of the current device

◆ getMacAddress()

MacAddress pcpp::PfRingDevice::getMacAddress ( )
inline

Get the MAC address of the current device

Returns
The MAC address of the current device

◆ getMtu()

int pcpp::PfRingDevice::getMtu ( )
inline

Get MTU of the current device

Returns
Upon success return the device MTU, 0 otherwise

◆ getNumOfOpenedRxChannels()

uint8_t pcpp::PfRingDevice::getNumOfOpenedRxChannels ( ) const
inline

Gets the number of RX channels currently open. RX channels aren't necessary interface's RX queues because in some cases the user asks to open several channels on the same queue. For example: if the user uses openMultiRxChannels() and asks to open 8 channels but interface has only 4 RX queues, 2 channels will be opened for each RX queue

Returns
Number of opened RX channels

◆ getStatistics()

void pcpp::PfRingDevice::getStatistics ( PfRingStats stats) const

Get the statistics for the entire device. If more than 1 RX channel is opened, this method aggregates the stats of all channels

Parameters
[out]statsA reference for the stats object where the stats are written. Current values will be overriden

◆ getThreadStatistics()

void pcpp::PfRingDevice::getThreadStatistics ( SystemCore  core,
PfRingStats stats 
) const

Get the statistics of a specific thread/core (=RX channel)

Parameters
[in]coreThe requested core
[out]statsA reference for the stats object where the stats are written. Current values will be overriden

◆ getTotalNumOfRxChannels()

uint8_t pcpp::PfRingDevice::getTotalNumOfRxChannels ( ) const

Gets the total number of RX channels (RX queues) this interface has

Returns
The number of RX channels (queues) for this interface

◆ isFilterCurrentlySet()

bool pcpp::PfRingDevice::isFilterCurrentlySet ( ) const

Return true if filter is currently set

Returns
True if filter is currently set, false otherwise

◆ isHwClockEnabledForDevice()

bool pcpp::PfRingDevice::isHwClockEnabledForDevice ( )
inline

Return true if device supports hardware timestamping. If it does, this feature will be automatically set for this device. You can read more about this in PF_RING documentation

Returns
True if device supports hardware timestamping, false otherwise

◆ open()

bool pcpp::PfRingDevice::open ( )
virtual

Opens the entire device (including all RX channels/queues on this interface). All packets will be received on a single thread without core affinity

Returns
True if this action succeeds, false otherwise

Implements pcpp::IDevice.

◆ openMultiRxChannels() [1/2]

bool pcpp::PfRingDevice::openMultiRxChannels ( const uint8_t *  channelIds,
int  numOfChannelIds 
)

Opens a set of RX channels (=RX queues) on this interface, identified by their IDs. All packets will be received on a single thread without core affinity. If one of the channel IDs requested doesn't exist on this interface, the method will fail (return false)

Parameters
[in]channelIdsAn array of channel IDs
[in]numOfChannelIdsThe channel ID array size
Returns
True if this action succeeds, false otherwise

◆ openMultiRxChannels() [2/2]

bool pcpp::PfRingDevice::openMultiRxChannels ( uint8_t  numOfRxChannelsToOpen,
ChannelDistribution  dist 
)

Opens numOfRxChannelsToOpen RX channels. If numOfRxChannelsToOpen is larger than available RX queues for this interface than a number of RX channels will be opened on each RX queue. For example: if the user asks for 10 RX channels but the interface has only 4 RX queues, then 3 RX channels will be opened for RX-queue0 and RX-queue2, and 2 RX channels will be opened for RX-queue2 and RX-queue3. Packets will be distributed between different RX queues on per-flow manner, but within multiple RX channels in the same RX queue packet will be distributed according to distribution requested by "dist"

Parameters
[in]numOfRxChannelsToOpenNumber of RX channels to open
[in]distDistribution method
Returns
True if this action succeeds, false otherwise

◆ openSingleRxChannel()

bool pcpp::PfRingDevice::openSingleRxChannel ( uint8_t  channelId)

Opens a single RX channel (=RX queue) on this interface. All packets will be received on a single thread without core affinity. If the channel ID requested doesn't exist on this interface, the method will fail (return false)

Parameters
[in]channelIdThe requested channel ID
Returns
True if this action succeeds, false otherwise

◆ sendPacket() [1/3]

bool pcpp::PfRingDevice::sendPacket ( const RawPacket rawPacket)

Send a raw packet. This packet must be fully specified (the MAC address up) and it will be transmitted as-is without any further manipulation. This method doesn't change or manipulate the data in any way (hence the "const" declaration). Note this method flushes the TX queues after the data is sent. So if you want to send several packets In the burst please use sendPackets()

Parameters
[in]rawPacketThe raw packet to send
Returns
True if raw packet was sent completely, false otherwise

◆ sendPacket() [2/3]

bool pcpp::PfRingDevice::sendPacket ( const uint8_t *  packetData,
int  packetDataLength 
)

Send raw data. This data must be a valid and fully specified packet (the MAC address up); it will be transmitted as-is without any further manipulation. This method doesn't change or manipulate the data in any way (hence the "const" declaration). Note this method flushes the TX queues after the data is sent. So if you want to send several packets in the burst please use sendPackets()

Parameters
[in]packetDataThe raw data to send
[in]packetDataLengththe length of packetData
Returns
True if raw packet was sent completely, false otherwise

◆ sendPacket() [3/3]

bool pcpp::PfRingDevice::sendPacket ( const Packet packet)

Send a packet. This packet must be fully specified (the MAC address up) and it will be transmitted as-is without any further manipulation. This method doesn't change or manipulate the data in any way (hence the "const" declaration). Note this method flushes the TX queues after the data is sent. So if you want to send several packets In the burst please use sendPackets()

Parameters
[in]packetThe packet to send
Returns
True if raw packet was sent completely, false otherwise

◆ sendPackets() [1/3]

int pcpp::PfRingDevice::sendPackets ( const RawPacket rawPacketsArr,
int  arrLength 
)

Send raw packets. All raw packets must be fully specified (the MAC address up) and it will be transmitted as-is without any further manipulation. This method doesn't change or manipulate the raw packets data in any way (hence the "const" declaration). This method flushes the TX queues only when the last packet is sent

Parameters
[in]rawPacketsArrThe RawPacket array
[in]arrLengthRawPacket array length
Returns
Number of packets that were sent completely

◆ sendPackets() [2/3]

int pcpp::PfRingDevice::sendPackets ( const Packet **  packetsArr,
int  arrLength 
)

Send packets. All packets must be fully specified (the MAC address up) and it will be transmitted as-is without any further manipulation. This method doesn't change or manipulate the packets data in any way (hence the "const" declaration). This method flushes the TX queues only when the last packet is sent

Parameters
[in]packetsArrAn array of pointers to Packet objects
[in]arrLengthPacket pointers array length
Returns
Number of packets that were sent completely

◆ sendPackets() [3/3]

int pcpp::PfRingDevice::sendPackets ( const RawPacketVector rawPackets)

Send all raw packets pointed by the RawPacketVector. All packets must be fully specified (the MAC address up) and it will be transmitted as-is without any further manipulation. This method doesn't change or manipulate the packets data in any way (hence the "const" declaration). This method flushes the TX queues only when the last packet is sent

Parameters
[in]rawPacketsThe raw packet vector
Returns
Number of raw packets that were sent completely

◆ setFilter()

bool pcpp::PfRingDevice::setFilter ( std::string  filterAsString)
virtual

Sets a BPF filter to the device

Parameters
[in]filterAsStringThe BPF filter in string format

Implements pcpp::IFilterableDevice.

◆ startCaptureMultiThread()

bool pcpp::PfRingDevice::startCaptureMultiThread ( OnPfRingPacketsArriveCallback  onPacketsArrive,
void *  onPacketsArriveUserCookie,
CoreMask  coreMask 
)

Start multi-threaded (multi-core) capturing with callback. Works with openMultiRxChannels(). This method will return an error if the number of opened channels is different than the number of threads/cores requested

Parameters
[in]onPacketsArriveA callback to call whenever a packet arrives
[in]onPacketsArriveUserCookieA cookie that will be delivered to onPacketsArrive callback on every packet
[in]coreMaskThe cores to be used as mask. For example:
Returns
True if this action succeeds, false otherwise

◆ startCaptureSingleThread()

bool pcpp::PfRingDevice::startCaptureSingleThread ( OnPfRingPacketsArriveCallback  onPacketsArrive,
void *  onPacketsArriveUserCookie 
)

Start single-threaded capturing with callback. Works with open() or openSingleRxChannel().

Parameters
[in]onPacketsArriveA callback to call whenever a packet arrives
[in]onPacketsArriveUserCookieA cookie that will be delivered to onPacketsArrive callback on every packet
Returns
True if this action succeeds, false otherwise

◆ stopCapture()

void pcpp::PfRingDevice::stopCapture ( )

Stops capturing packets (works will all type of startCapture*)