PcapPlusPlus  22.11
pcpp::KniDevice Class Reference

#include <KniDevice.h>

Inheritance diagram for pcpp::KniDevice:
pcpp::IDevice

Classes

struct  KniDeviceConfiguration
 KNI device initialization data. Used to create new KNI device. Usage of callbacks member or oldCallbacks member is defined by result of KniDeviceList::callbackVersion. More...
 
struct  KniIoctlCallbacks
 New callbacks for KNI device events. This structure MUST be used ONLY when KniDeviceList::callbackVersion returns KniDeviceList::KniCallbackVersion::CALLBACKS_NEW. Or if You are sure that DPDK version used is 17.11 or higher. If some callback is not provided (NULL) the request will always succeeds if other is not specified in callback description. More...
 
struct  KniOldIoctlCallbacks
 Old callbacks for KNI device events. This structure MUST be used ONLY when KniDeviceList::callbackVersion returns KniDeviceList::KniCallbackVersion::CALLBACKS_OLD. Or if You are sure that DPDK version used is lower than 17.11. If some callback is not provided (NULL) the request will always succeeds. More...
 

Public Types

enum  KniLinkState { LINK_NOT_SUPPORTED = -2, LINK_ERROR = -1, LINK_DOWN = 0, LINK_UP = 1 }
 
enum  KniInfoState { INFO_CACHED = 0, INFO_RENEW = 1 }
 
enum  KniPromiscuousMode { PROMISC_DISABLE = 0, PROMISC_ENABLE = 1 }
 

Public Member Functions

bool isInitialized () const
 
std::string getName () const
 
uint16_t getPort () const
 
KniLinkState getLinkState (KniInfoState state=INFO_CACHED)
 Obtains link status of KNI device. If called with INFO_CACHED - returns cached data about link state (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain link information and caches it (VERY SLOW but ACCURATE). More...
 
MacAddress getMacAddress (KniInfoState state=INFO_CACHED)
 Obtains MAC address of KNI device. If called with INFO_CACHED - returns cached data about MAC address (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain MAC address and caches it (VERY SLOW but ACCURATE). More...
 
uint16_t getMtu (KniInfoState state=INFO_CACHED)
 Obtains MTU of KNI device. If called with INFO_CACHED - returns cached data about MTU (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain MTU and caches it (VERY SLOW but ACCURATE). More...
 
KniPromiscuousMode getPromiscuous (KniInfoState state=INFO_CACHED)
 Obtains information about promiscuous mode of KNI device. If called with INFO_CACHED - returns cached data about promiscuous mode (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain promiscuous mode and caches it (VERY SLOW but ACCURATE). More...
 
bool setLinkState (KniLinkState state)
 Sets link state of KNI device. Firstly the link information is updated as by call to getLinkState(INFO_RENEW). Then link state is set only if obtained state differs from provided. New link state of KNI device is cached. More...
 
bool setMacAddress (MacAddress mac)
 Sets MAC address of KNI device. Unconditionally changes MAC of KNI device. If MAC is updated successfully then it is cached. More...
 
bool setMtu (uint16_t mtu)
 Sets MTU of KNI device. Unconditionally changes MTU of KNI device. If MTU is updated successfully then it is cached. More...
 
bool setPromiscuous (KniPromiscuousMode mode)
 Sets promiscuous mode of KNI device. Firstly the promiscuous mode information is updated as by call to getPromiscuous(INFO_RENEW). Then promiscuous mode is set only if obtained mode differs from provided. New promiscuous mode of KNI device is cached. More...
 
KniLinkState updateLinkState (KniLinkState state)
 Updates link state of KNI device. Unconditionally updates link state of KNI device via call to DPDK librte_kni API. FASTER THAN setLinkState(state) but may not be supported or may fail. If link state is updated successfully then it is cached. More...
 
bool handleRequests ()
 Handle requests from Linux kernel synchronously in calling thread. When one of events which is needed application attention occurres it must be handled by calling this function (or by running RequestHandlerThread for this device). Until the request is handled the Linux kernel thread that manages this KNI is blocked. If it is not handled by application in 3 seconds the request is reported to kernel as failed one. Current known requests are: More...
 
bool startRequestHandlerThread (long sleepSeconds, long sleepNanoSeconds=0)
 Starts new thread (using pthread) to asynchronously handle KNI device requests. See description of handleRequests() about requests. New thread is detached using pthread_detach. This thread can be stopped explicitly by calling stopRequestHandlerThread() or implicitly on KNI device destruction. Linux nanosleep() function is used for sleeping. More...
 
void stopRequestHandlerThread ()
 Explicitly stops request thread for this device if it was running. See description of handleRequests() about requests. More...
 
uint16_t receivePackets (MBufRawPacketVector &rawPacketsArr)
 Receive raw packets from kernel. More...
 
uint16_t receivePackets (MBufRawPacket **rawPacketsArr, uint16_t rawPacketArrLength)
 Receive raw packets from kernel. Please notice that in terms of performance, this is the best method to use for receiving packets because out of all receivePackets overloads this method requires the least overhead and is almost as efficient as receiving packets directly through DPDK. So if performance is a critical factor in your application, please use this method. More...
 
uint16_t receivePackets (Packet **packetsArr, uint16_t packetsArrLength)
 Receive parsed packets from kernel. More...
 
uint16_t sendPackets (MBufRawPacket **rawPacketsArr, uint16_t arrLength)
 Send an array of MBufRawPacket to kernel. Please notice the following:
More...
 
uint16_t sendPackets (Packet **packetsArr, uint16_t arrLength)
 Send an array of parsed packets to kernel. Please notice the following:
More...
 
uint16_t sendPackets (MBufRawPacketVector &rawPacketsVec)
 Send a vector of MBufRawPacket pointers to kernel. Please notice the following:
More...
 
uint16_t sendPackets (RawPacketVector &rawPacketsVec)
 Send a vector of RawPacket pointers to kernel. Please notice the following:
More...
 
bool sendPacket (RawPacket &rawPacket)
 Send a raw packet to kernel. Please notice that if the raw packet isn't of type MBufRawPacket, a new temp MBufRawPacket will be created and the data will be copied to it. This is necessary to allocate an mbuf which will store the data to be sent. If performance is a critical factor please make sure you send a raw packet of type MBufRawPacket. Please also notice that the mbuf used or allocated in this method isn't freed by this method, it will be transparently freed by DPDK. More...
 
bool sendPacket (MBufRawPacket &rawPacket)
 Send a MBufRawPacket to kernel. Please notice that the mbuf used in this method isn't freed by this method, it will be transparently freed by DPDK. More...
 
bool sendPacket (Packet &packet)
 Send a parsed packet to kernel. Please notice that the mbuf used or allocated in this method isn't freed by this method, it will be transparently freed by DPDK. More...
 
bool startCapture (OnKniPacketArriveCallback onPacketArrives, void *onPacketArrivesUserCookie)
 Start capturing packets asynchronously on this KNI interface. Each time a burst of packets 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. Capturing thread will be terminated automatically on KNI device destruction or when close() is called. More...
 
int startCaptureBlockingMode (OnKniPacketArriveCallback onPacketArrives, void *onPacketArrivesUserCookie, int timeout)
 Start capturing packets synchronously on this KNI interface in blocking mode. Blocking mode means that this method block and won't return until the user frees the blocking (via onPacketArrives callback) or until a user defined timeout expires. Whenever a burst of 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 stop 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. More...
 
void stopCapture ()
 
bool open ()
 
void close ()
 Close the KNI device. When device is closed it's not possible to work with it. Stops asynchronous packet capture if it is running.
 
- Public Member Functions inherited from pcpp::IDevice
bool isOpened ()
 

Detailed Description

This class represents special kind of DPDK devices called KNI - Kernel Network Interface that are used to exchange DPDK mbuf packets with Linux kernel network stack. This devices have only one RX and one TX queue so MT receiving or MT sending is not safe but simultaneous receiving and sending packets is MT safe. The RX queue of KNI device is pointed from kernel to application and TX queue is pointed in opposite direction - from application to kernel. So receive* methods will obtain packets from kernel and send* methods will send them to kernel.
The lifecycle of the KNI device is as follows:

  • KniDeviceConfiguration structure is created by user and filled with device settings;
  • The KniDeviceList::getInstance method is called to initialize the KNI module and obtain the KniDeviceList singleton;
  • KniDeviceList::createDevice method of the singleton is called to allocate new KNI device;
  • Device then must be opened by calling KniDevice::open;
  • During lifetime the application must handle the requests from kernel either by calling KniDevice::handleRequests to handle them synchronously or by starting separate thread to do this by calling KniDevice::startRequestHandlerThread;
  • During lifetime the packets may be send to/received from KNI device via calls to synchronous API (send/receive methods) or asynchronously by running capturing thread using KniDevice::startCapture;
  • KNI device will be destroyed or implicitly on application exit. User must assure that NO OTHER linux application is using KNI device when and after it is being destroyed otherwise Linux kernel may crush dramatically.

Member Enumeration Documentation

◆ KniInfoState

Various information related constants for KNI device

Enumerator
INFO_CACHED 

Used to identify intent to obtain cached version of KNI device information

INFO_RENEW 

Used to identify intent to renew/update KNI device information

◆ KniLinkState

Various link related constants for KNI device

Enumerator
LINK_NOT_SUPPORTED 

Returned by KNI functions if DPDK version used don't support link setup capability

LINK_ERROR 

Returned by KNI functions if link changing function meets an error

LINK_DOWN 

Used to put link status on KNI device DOWN

LINK_UP 

Used to put link status on KNI device UP

◆ KniPromiscuousMode

Promiscuous mode related constants for KNI device

Enumerator
PROMISC_DISABLE 

Used to DISABLE promiscuous mode on KNI device

PROMISC_ENABLE 

Used to ENABLE promiscuous mode on KNI device

Member Function Documentation

◆ getLinkState()

KniLinkState pcpp::KniDevice::getLinkState ( KniInfoState  state = INFO_CACHED)

Obtains link status of KNI device. If called with INFO_CACHED - returns cached data about link state (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain link information and caches it (VERY SLOW but ACCURATE).

Parameters
[in]stateDefines information relevance level
Returns
LINK_UP, LINK_DOWN, LINK_NOT_SUPPORTED if device is not initialized, some times LINK_ERROR

◆ getMacAddress()

MacAddress pcpp::KniDevice::getMacAddress ( KniInfoState  state = INFO_CACHED)

Obtains MAC address of KNI device. If called with INFO_CACHED - returns cached data about MAC address (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain MAC address and caches it (VERY SLOW but ACCURATE).

Parameters
[in]stateDefines information relevance level
Returns
Known MAC address of KNI interface

◆ getMtu()

uint16_t pcpp::KniDevice::getMtu ( KniInfoState  state = INFO_CACHED)

Obtains MTU of KNI device. If called with INFO_CACHED - returns cached data about MTU (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain MTU and caches it (VERY SLOW but ACCURATE).

Parameters
[in]stateDefines information relevance level
Returns
Known MTU of KNI interface

◆ getName()

std::string pcpp::KniDevice::getName ( ) const
inline

Obtains name of KNI device in form of C++ string

◆ getPort()

uint16_t pcpp::KniDevice::getPort ( ) const
inline

Obtains port ID of KNI device

◆ getPromiscuous()

KniPromiscuousMode pcpp::KniDevice::getPromiscuous ( KniInfoState  state = INFO_CACHED)

Obtains information about promiscuous mode of KNI device. If called with INFO_CACHED - returns cached data about promiscuous mode (SUPER FAST may be INACCURATE). If called with INFO_RENEW - makes system call to Linux to obtain promiscuous mode and caches it (VERY SLOW but ACCURATE).

Parameters
[in]stateDefines information relevance level
Returns
Known promiscuous mode of KNI interface

◆ handleRequests()

bool pcpp::KniDevice::handleRequests ( )

Handle requests from Linux kernel synchronously in calling thread. When one of events which is needed application attention occurres it must be handled by calling this function (or by running RequestHandlerThread for this device). Until the request is handled the Linux kernel thread that manages this KNI is blocked. If it is not handled by application in 3 seconds the request is reported to kernel as failed one. Current known requests are:

  • change link state: ip l set [interface] up/down
  • change mtu: ip l set dev [interface] mtu [mtu_count]
  • change mac: ip l set [interface] address [new_mac]
  • change promiscuous mode: ip l set [interface] promisc on/off
    Warning
    Functions setLinkState, setMacAddress, setMtu and setPromiscuous will generate this requests.
    Note
    Callbacks provided for this KNI device will be called synchronously in calling thread during execution of this function
    Returns
    true if no error happened during request handling false otherwise

◆ isInitialized()

bool pcpp::KniDevice::isInitialized ( ) const
inline

Indicates whether the KNI device was initialized successfully

◆ open()

bool pcpp::KniDevice::open ( )
virtual

Takes appropriate actions for opening KNI device.

Returns
true if the device was opened successfully, false if device is already opened, or KNI device configuration and startup failed

Implements pcpp::IDevice.

◆ receivePackets() [1/3]

uint16_t pcpp::KniDevice::receivePackets ( MBufRawPacketVector rawPacketsArr)

Receive raw packets from kernel.

Parameters
[out]rawPacketsArrA vector where all received packets will be written into
Returns
The number of packets received. If an error occurred 0 will be returned and the error will be printed to log

◆ receivePackets() [2/3]

uint16_t pcpp::KniDevice::receivePackets ( MBufRawPacket **  rawPacketsArr,
uint16_t  rawPacketArrLength 
)

Receive raw packets from kernel. Please notice that in terms of performance, this is the best method to use for receiving packets because out of all receivePackets overloads this method requires the least overhead and is almost as efficient as receiving packets directly through DPDK. So if performance is a critical factor in your application, please use this method.

Parameters
[out]rawPacketsArrA pointer to an array of MBufRawPacket pointers where all received packets will be written into. The array is expected to be allocated by the user and its length should be provided in rawPacketArrLength. Number of packets received will be returned. Notice it's the user responsibility to free the array and its content when done using it
[out]rawPacketArrLengthThe length of MBufRawPacket pointers array
Returns
The number of packets received. If an error occurred 0 will be returned and the error will be printed to log

◆ receivePackets() [3/3]

uint16_t pcpp::KniDevice::receivePackets ( Packet **  packetsArr,
uint16_t  packetsArrLength 
)

Receive parsed packets from kernel.

Parameters
[out]packetsArrA pointer to an allocated array of Packet pointers where all received packets will be written into. The array is expected to be allocated by the user and its length should be provided in packetsArrLength. Number of packets received will be returned. Notice it's the user responsibility to free the array and its content when done using it
[out]packetsArrLengthThe length of Packet pointers array
Returns
The number of packets received. If an error occurred 0 will be returned and the error will be printed to log

◆ sendPacket() [1/3]

bool pcpp::KniDevice::sendPacket ( RawPacket rawPacket)

Send a raw packet to kernel. Please notice that if the raw packet isn't of type MBufRawPacket, a new temp MBufRawPacket will be created and the data will be copied to it. This is necessary to allocate an mbuf which will store the data to be sent. If performance is a critical factor please make sure you send a raw packet of type MBufRawPacket. Please also notice that the mbuf used or allocated in this method isn't freed by this method, it will be transparently freed by DPDK.

Parameters
[in]rawPacketThe raw packet to send
Returns
True if packet was sent successfully or false if the packet wasn't sent for any other reason

◆ sendPacket() [2/3]

bool pcpp::KniDevice::sendPacket ( MBufRawPacket rawPacket)

Send a MBufRawPacket to kernel. Please notice that the mbuf used in this method isn't freed by this method, it will be transparently freed by DPDK.

Parameters
[in]rawPacketThe MBufRawPacket to send
Returns
True if packet was sent successfully or false if device is not opened or if the packet wasn't sent for any other reason

◆ sendPacket() [3/3]

bool pcpp::KniDevice::sendPacket ( Packet packet)

Send a parsed packet to kernel. Please notice that the mbuf used or allocated in this method isn't freed by this method, it will be transparently freed by DPDK.

Parameters
[in]packetThe parsed packet to send. Please notice that if the packet contains a raw packet which isn't of type MBufRawPacket, a new temp MBufRawPacket will be created and the data will be copied to it. This is necessary to allocate an mbuf which will store the data to be sent. If performance is a critical factor please make sure you send a parsed packet that contains a raw packet of type MBufRawPacket
Returns
True if packet was sent successfully or false if device is not opened or if the packet wasn't sent for any other reason

◆ sendPackets() [1/4]

uint16_t pcpp::KniDevice::sendPackets ( MBufRawPacket **  rawPacketsArr,
uint16_t  arrLength 
)

Send an array of MBufRawPacket to kernel. Please notice the following:

  • In terms of performance, this is the best method to use for sending packets because out of all sendPackets overloads this method requires the least overhead and is almost as efficient as sending the packets directly through DPDK. So if performance is a critical factor in your application, please use this method
  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • The mbufs used in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]rawPacketsArrA pointer to an array of MBufRawPacket
    [in]arrLengthThe length of the array
    Returns
    The number of packets actually and successfully sent

◆ sendPackets() [2/4]

uint16_t pcpp::KniDevice::sendPackets ( Packet **  packetsArr,
uint16_t  arrLength 
)

Send an array of parsed packets to kernel. Please notice the following:

  • If some or all of the packets contain raw packets which aren't of type MBufRawPacket, a new temp MBufRawPacket instances will be created and packet data will be copied to them. This is necessary to allocate mbufs which will store the data to be sent. If performance is a critical factor please make sure you send parsed packets that contain only raw packets of type MBufRawPacket
  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • The mbufs used or allocated in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]packetsArrA pointer to an array of parsed packet pointers
    [in]arrLengthThe length of the array
    Returns
    The number of packets actually and successfully sent

◆ sendPackets() [3/4]

uint16_t pcpp::KniDevice::sendPackets ( MBufRawPacketVector rawPacketsVec)

Send a vector of MBufRawPacket pointers to kernel. Please notice the following:

  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • The mbufs used in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]rawPacketsVecThe vector of raw packet
    Returns
    The number of packets actually and successfully sent

◆ sendPackets() [4/4]

uint16_t pcpp::KniDevice::sendPackets ( RawPacketVector rawPacketsVec)

Send a vector of RawPacket pointers to kernel. Please notice the following:

  • If some or all of the raw packets aren't of type MBufRawPacket, a new temp MBufRawPacket instances will be created and packet data will be copied to them. This is necessary to allocate mbufs which will store the data to be sent. If performance is a critical factor please make sure you send only raw packets of type MBufRawPacket (or use the sendPackets overload that sends MBufRawPacketVector)
  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • The mbufs used or allocated in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]rawPacketsVecThe vector of raw packet
    Returns
    The number of packets actually and successfully sent

◆ setLinkState()

bool pcpp::KniDevice::setLinkState ( KniLinkState  state)

Sets link state of KNI device. Firstly the link information is updated as by call to getLinkState(INFO_RENEW). Then link state is set only if obtained state differs from provided. New link state of KNI device is cached.

Note
You must be using sudo or be root or have CAP_NET_ADMIN capability to use this function
Generates change link state request
Parameters
[in]stateMust be LINK_UP or LINK_DOWN
Returns
true if desired link state of KNI device is set (was as provided or set successfully), false if some error occurred (debug info is printed)

◆ setMacAddress()

bool pcpp::KniDevice::setMacAddress ( MacAddress  mac)

Sets MAC address of KNI device. Unconditionally changes MAC of KNI device. If MAC is updated successfully then it is cached.

Note
You must be using sudo or be root or have CAP_NET_ADMIN capability to use this function
Generates change mac request
Parameters
[in]macNew MAC address of KNI device
Returns
true if desired MAC address is set, false if not and some error occurred (debug info is printed)

◆ setMtu()

bool pcpp::KniDevice::setMtu ( uint16_t  mtu)

Sets MTU of KNI device. Unconditionally changes MTU of KNI device. If MTU is updated successfully then it is cached.

Note
You must be using sudo or be root or have CAP_NET_ADMIN capability to use this function
Generates change mtu request
Warning
Low MTU values may crush Linux kernel. Follow Your kernel version documentation for details
Parameters
[in]mtuNew MTU address of KNI device
Returns
true if desired MTU is set, false if not and some error occurred (debug info is printed)

◆ setPromiscuous()

bool pcpp::KniDevice::setPromiscuous ( KniPromiscuousMode  mode)

Sets promiscuous mode of KNI device. Firstly the promiscuous mode information is updated as by call to getPromiscuous(INFO_RENEW). Then promiscuous mode is set only if obtained mode differs from provided. New promiscuous mode of KNI device is cached.

Note
You must be using sudo or be root or have CAP_NET_ADMIN capability to use this function
Generates promiscuous mode request
Parameters
[in]modeMust be PROMISC_DISABLE or PROMISC_ENABLE
Returns
true if desired promiscuous mode of KNI device is set (was as provided or set successfully), false if some error occurred (debug info is printed)

◆ startCapture()

bool pcpp::KniDevice::startCapture ( OnKniPacketArriveCallback  onPacketArrives,
void *  onPacketArrivesUserCookie 
)

Start capturing packets asynchronously on this KNI interface. Each time a burst of packets 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. Capturing thread will be terminated automatically on KNI device destruction or when close() is called.

Parameters
[in]onPacketArrivesA callback that is called each time a burst of packets is captured
[in]onPacketArrivesUserCookieA 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
Returns
True if capture started successfully, false if (relevant log error is printed in any case):
  • Capture is already running
  • Device is not opened
  • Capture thread could not be created

◆ startCaptureBlockingMode()

int pcpp::KniDevice::startCaptureBlockingMode ( OnKniPacketArriveCallback  onPacketArrives,
void *  onPacketArrivesUserCookie,
int  timeout 
)

Start capturing packets synchronously on this KNI interface in blocking mode. Blocking mode means that this method block and won't return until the user frees the blocking (via onPacketArrives callback) or until a user defined timeout expires. Whenever a burst of 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 stop 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.

Parameters
[in]onPacketArrivesA callback given by the user for handling incoming packets. After handling each burst of packets 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]onPacketArrivesUserCookieA 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]timeoutA 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
Returns
-1 if timeout expired, 1 if blocking was stopped via onPacketArrives callback or 0 if an error occurred (such as device not open etc.). When returning 0 an appropriate error message is printed to log

◆ startRequestHandlerThread()

bool pcpp::KniDevice::startRequestHandlerThread ( long  sleepSeconds,
long  sleepNanoSeconds = 0 
)

Starts new thread (using pthread) to asynchronously handle KNI device requests. See description of handleRequests() about requests. New thread is detached using pthread_detach. This thread can be stopped explicitly by calling stopRequestHandlerThread() or implicitly on KNI device destruction. Linux nanosleep() function is used for sleeping.

Note
Callbacks provided for this KNI device will be called asynchronously in new thread
Parameters
[in]sleepSecondsSleeping time in seconds
[in]sleepNanoSecondsSleeping time in nanoseconds
Returns
true if new thread is started successfully false otherwise

◆ stopCapture()

void pcpp::KniDevice::stopCapture ( )

Stop a currently running asynchronous packet capture.

◆ stopRequestHandlerThread()

void pcpp::KniDevice::stopRequestHandlerThread ( )

Explicitly stops request thread for this device if it was running. See description of handleRequests() about requests.

Warning
There may be a rare error when request thread handles requests on already destroyed device. It occurres only because request thread is detached one but it is really really rare. In case of this error occurring (must be SIGSEGV) change type of created thread in startRequestHandlerThread function from DETACHED to JOINABLE.

◆ updateLinkState()

KniLinkState pcpp::KniDevice::updateLinkState ( KniLinkState  state)

Updates link state of KNI device. Unconditionally updates link state of KNI device via call to DPDK librte_kni API. FASTER THAN setLinkState(state) but may not be supported or may fail. If link state is updated successfully then it is cached.

Parameters
[in]stateNew link state of KNI device
Returns
LINK_NOT_SUPPORTED if this capability is not supported by DPDK version used (DPDK ver < 18.11), LINK_ERROR if attempt to set link state failed (may always fail on some systems see class description) LINK_DOWN - previous link state was DOWN, state is successfully updated to provided one LINK_UP - previous link state was UP, state is successfully updated to provided one