#include <KniDevice.h>

Inheritance diagram for pcpp::KniDevice:

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

enum pcpp::KniDevice::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

enum pcpp::KniDevice::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

enum pcpp::KniDevice::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] state Defines 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] state Defines 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] state Defines 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] state Defines 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] rawPacketsArr A 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]	rawPacketsArr	A 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]	rawPacketArrLength	The 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]	packetsArr	A 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]	packetsArrLength	The 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] rawPacket The 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] rawPacket The 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] packet The 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] rawPacketsArr A pointer to an array of MBufRawPacket

[in] arrLength The 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] packetsArr A pointer to an array of parsed packet pointers

[in] arrLength The 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] rawPacketsVec The 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] rawPacketsVec The 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] state Must 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] mac New 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] mtu New 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] mode Must 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]	onPacketArrives	A callback that is called each time a burst of packets 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

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]	onPacketArrives	A 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]	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]	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

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]	sleepSeconds	Sleeping time in seconds
[in]	sleepNanoSeconds	Sleeping 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] state New 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

[in]	rawPacketsArr	A pointer to an array of MBufRawPacket
[in]	arrLength	The length of the array

[in]	packetsArr	A pointer to an array of parsed packet pointers
[in]	arrLength	The length of the array

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ KniInfoState

◆ KniLinkState

◆ KniPromiscuousMode

Member Function Documentation

◆ getLinkState()

◆ getMacAddress()

◆ getMtu()

◆ getName()

◆ getPort()

◆ getPromiscuous()

◆ handleRequests()

◆ isInitialized()

◆ open()

◆ receivePackets() [1/3]

◆ receivePackets() [2/3]

◆ receivePackets() [3/3]

◆ sendPacket() [1/3]

◆ sendPacket() [2/3]

◆ sendPacket() [3/3]

◆ sendPackets() [1/4]

◆ sendPackets() [2/4]

◆ sendPackets() [3/4]

◆ sendPackets() [4/4]

◆ setLinkState()

◆ setMacAddress()

◆ setMtu()

◆ setPromiscuous()

◆ startCapture()

◆ startCaptureBlockingMode()

◆ startRequestHandlerThread()

◆ stopCapture()

◆ stopRequestHandlerThread()

◆ updateLinkState()