PcapPlusPlus
22.11
|
#include <KniDevice.h>
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 () |
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:
Various link related constants for KNI device
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).
[in] | state | Defines information relevance level |
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).
[in] | state | Defines information relevance level |
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).
[in] | state | Defines information relevance level |
|
inline |
Obtains name of KNI device in form of C++ string
|
inline |
Obtains port ID of KNI device
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).
[in] | state | Defines information relevance level |
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:
|
inline |
Indicates whether the KNI device was initialized successfully
|
virtual |
Takes appropriate actions for opening KNI device.
Implements pcpp::IDevice.
uint16_t pcpp::KniDevice::receivePackets | ( | MBufRawPacketVector & | rawPacketsArr | ) |
Receive raw packets from kernel.
[out] | rawPacketsArr | A vector where all received packets will be written into |
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.
[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 |
uint16_t pcpp::KniDevice::receivePackets | ( | Packet ** | packetsArr, |
uint16_t | packetsArrLength | ||
) |
Receive parsed packets from kernel.
[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 |
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.
[in] | rawPacket | The raw packet to send |
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.
[in] | rawPacket | The MBufRawPacket to send |
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.
[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 |
uint16_t pcpp::KniDevice::sendPackets | ( | MBufRawPacket ** | rawPacketsArr, |
uint16_t | arrLength | ||
) |
Send an array of MBufRawPacket to kernel. Please notice the following:
[in] | rawPacketsArr | A pointer to an array of MBufRawPacket |
[in] | arrLength | The length of the array |
uint16_t pcpp::KniDevice::sendPackets | ( | Packet ** | packetsArr, |
uint16_t | arrLength | ||
) |
Send an array of parsed packets to kernel. Please notice the following:
[in] | packetsArr | A pointer to an array of parsed packet pointers |
[in] | arrLength | The length of the array |
uint16_t pcpp::KniDevice::sendPackets | ( | MBufRawPacketVector & | rawPacketsVec | ) |
Send a vector of MBufRawPacket pointers to kernel. Please notice the following:
[in] | rawPacketsVec | The vector of raw packet |
uint16_t pcpp::KniDevice::sendPackets | ( | RawPacketVector & | rawPacketsVec | ) |
Send a vector of RawPacket pointers to kernel. Please notice the following:
[in] | rawPacketsVec | The vector of raw packet |
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.
[in] | state | Must be LINK_UP or LINK_DOWN |
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.
[in] | mac | New MAC address of KNI device |
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.
[in] | mtu | New MTU address of KNI device |
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.
[in] | mode | Must be PROMISC_DISABLE or PROMISC_ENABLE |
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.
[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 |
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.
[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 |
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.
[in] | sleepSeconds | Sleeping time in seconds |
[in] | sleepNanoSeconds | Sleeping time in nanoseconds |
void pcpp::KniDevice::stopCapture | ( | ) |
Stop a currently running asynchronous packet capture.
void pcpp::KniDevice::stopRequestHandlerThread | ( | ) |
Explicitly stops request thread for this device if it was running. See description of handleRequests() about requests.
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.
[in] | state | New link state of KNI device |