A device wrapper around the WinDivert driver for Windows. More...

#include <WinDivertDevice.h>

Inheritance diagram for pcpp::WinDivertDevice:

Classes
struct	NetworkInterface
	A Windows network interface entry returned by getNetworkInterfaces(). More...

struct	ReceiveResult
	Result object returned by receive operations. More...

struct	SendResult
	Result object returned by send operations. More...

struct	WinDivertReceiveCallbackContext
	Context object passed to ReceivePacketCallback. More...

struct	WinDivertVersion
	The WinDivert runtime version as reported by the driver. More...

Public Types
enum class	QueueParam { QueueLength , QueueTime , QueueSize }
	Queue tuning parameters supported by WinDivert. More...

using	WinDivertRawPacketVector = PointerVector< WinDivertRawPacket >
	Convenience alias for a vector of WinDivertRawPacket pointers with ownership semantics.

using	ReceivePacketCallback = std::function< void(const WinDivertRawPacketVector &packetVec, const WinDivertReceiveCallbackContext &context)>
	Callback invoked with a batch of received packets when using the callback receive API. The callback is called from the receiving loop until stopReceive() is invoked or an error/timeout occurs. More...

using	QueueParams = std::unordered_map< QueueParam, uint64_t >
	A map of QueueParam keys to their values. Units are per QueueParam description above.

Public Member Functions
	WinDivertDevice (std::unique_ptr< internal::IWinDivertDriver > driver=nullptr)
	Construct a WinDivertDevice. More...

bool	open () override
	Open the device with a default filter capturing both directions. More...

bool	open (const std::string &filter)
	Open the device with a custom WinDivert filter. More...

void	close () override
	Close the device and release the underlying WinDivert handle.

bool	isOpened () const override

ReceiveResult	receivePackets (WinDivertRawPacketVector &packetVec, uint32_t timeout=5000, uint32_t maxPackets=0, uint8_t batchSize=64)
	Receive packets into a vector owned by the caller. More...

ReceiveResult	receivePackets (const ReceivePacketCallback &callback, uint32_t timeout=5000, uint8_t batchSize=64)
	Receive packets using a callback invoked for each received batch. More...

void	stopReceive ()
	Request to stop an ongoing receivePackets(callback, ...) loop. More...

SendResult	sendPackets (const RawPacketVector &packetVec, uint8_t batchSize=64) const
	Send a vector of raw packets in batches. More...

QueueParams	getPacketQueueParams () const
	Get the current WinDivert queue parameters. More...

void	setPacketQueueParams (const QueueParams &params) const
	Set WinDivert queue parameters. More...

WinDivertVersion	getVersion () const
	Get the WinDivert runtime version loaded on the system. More...

const NetworkInterface *	getNetworkInterface (uint32_t interfaceIndex) const
	Get a pointer to a specific Windows network interface by index. More...

std::vector< NetworkInterface >	getNetworkInterfaces () const
	Enumerate Windows network interfaces. More...

Detailed Description

A device wrapper around the WinDivert driver for Windows.

WinDivert is a kernel driver for packet interception and injection on Windows. WinDivertDevice opens a WinDivert handle on the WINDIVERT_LAYER_NETWORK layer using a filter and provides methods to receive and send packets in batches, query/set queue parameters, retrieve the WinDivert runtime version, and enumerate Windows network interfaces.

Notes:

The default open() uses the filter "true", capturing both directions.
The device is opened in sniffing mode and supports fragmented packets.
Receive can be done into a user-provided vector or via a callback loop that can be stopped with stopReceive().
Send batches multiple packets at once for efficiency.
Queue parameters map to WinDivert queue configuration (length in packets, time in milliseconds, size in bytes).

For WinDivert filter syntax, layer semantics, timestamps and error codes please refer to the WinDivert documentation.

Member Typedef Documentation

◆ ReceivePacketCallback

using pcpp::WinDivertDevice::ReceivePacketCallback = std::function<void(const WinDivertRawPacketVector& packetVec, const WinDivertReceiveCallbackContext& context)>

Callback invoked with a batch of received packets when using the callback receive API. The callback is called from the receiving loop until stopReceive() is invoked or an error/timeout occurs.

Parameters

[in]	packetVec	A list of the currently received batch of WinDivertRawPacket objects.
[in]	context	A context object providing the calling device and, potentially, other metadata.

Member Enumeration Documentation

◆ QueueParam

enum pcpp::WinDivertDevice::QueueParam

strong

Queue tuning parameters supported by WinDivert.

These map to WinDivert queue configuration parameters:

QueueLength – maximum number of packets in the internal queue (packets)
QueueTime – maximum time packets may sit in the internal queue (milliseconds)
QueueSize – maximum memory size for the internal queue (bytes)

Enumerator
QueueLength	Maximum number of packets in the packet queue (packets)
QueueTime	Maximum residence time of packets in the queue (milliseconds)
QueueSize	Maximum memory allocated for the queue (bytes)

Constructor & Destructor Documentation

◆ WinDivertDevice()

pcpp::WinDivertDevice::WinDivertDevice ( std::unique_ptr< internal::IWinDivertDriver > driver = nullptr )

Construct a WinDivertDevice.

Parameters

[in] driver Optional WinDivert driver implementation. Ownership is transferred to WinDivertDevice. Pass nullptr (the default) to use the built-in default driver implementation.

Member Function Documentation

◆ getNetworkInterface()

const NetworkInterface* pcpp::WinDivertDevice::getNetworkInterface ( uint32_t interfaceIndex ) const

Get a pointer to a specific Windows network interface by index.

Parameters

[in] interfaceIndex The Windows interface index.

Returns: A pointer to an internal NetworkInterface entry or nullptr if not found.

Warning: The returned pointer may become invalid after subsequent calls that refresh interfaces.

◆ getNetworkInterfaces()

std::vector<NetworkInterface> pcpp::WinDivertDevice::getNetworkInterfaces ( ) const

Enumerate Windows network interfaces.

Returns: A vector of NetworkInterface entries.

◆ getPacketQueueParams()

QueueParams pcpp::WinDivertDevice::getPacketQueueParams ( ) const

Get the current WinDivert queue parameters.

Returns: A map from QueueParam to the configured value.

◆ getVersion()

WinDivertVersion pcpp::WinDivertDevice::getVersion ( ) const

Get the WinDivert runtime version loaded on the system.

Returns: A WinDivertVersion with major and minor components.

◆ isOpened()

bool pcpp::WinDivertDevice::isOpened ( ) const

inlineoverridevirtual

Returns: True if the file is opened, false otherwise

Implements pcpp::IDevice.

◆ open() [1/2]

bool pcpp::WinDivertDevice::open ( )

overridevirtual

Open the device with a default filter capturing both directions.

Returns: true on success, false on failure (see logs for details).

Note: This calls open("true") on WINDIVERT_LAYER_NETWORK with sniffing/fragments flags.

Implements pcpp::IDevice.

◆ open() [2/2]

bool pcpp::WinDivertDevice::open ( const std::string & filter )

Open the device with a custom WinDivert filter.

Parameters

[in] filter A WinDivert filter string (e.g. "ip and tcp.DstPort == 80").

Returns: true on success, false on failure (see logs for details).

Note: The device is opened on WINDIVERT_LAYER_NETWORK with sniffing and fragment support.

◆ receivePackets() [1/2]

ReceiveResult pcpp::WinDivertDevice::receivePackets	(	const ReceivePacketCallback &	callback,
		uint32_t	timeout = `5000`,
		uint8_t	batchSize = `64`
	)

Receive packets using a callback invoked for each received batch.

The method runs a receive loop and invokes callback with each batch. The loop ends when stopReceive() is called from another thread, on timeout, or if an error occurs. Packet memory is valid during the callback and is released when the callback returns.

Parameters

[in]	callback	A callback receiving a vector view of the current batch.
[in]	timeout	Receive timeout in milliseconds per wait cycle. Default is 5000ms.
[in]	batchSize	Number of packets to read per WinDivert call (must be > 0). Default is 64.

Returns: A ReceiveResult describing the final outcome.

◆ receivePackets() [2/2]

ReceiveResult pcpp::WinDivertDevice::receivePackets	(	WinDivertRawPacketVector &	packetVec,
		uint32_t	timeout = `5000`,
		uint32_t	maxPackets = `0`,
		uint8_t	batchSize = `64`
	)

Receive packets into a vector owned by the caller.

This method receives up to maxPackets packets (0 means unlimited) in batches of batchSize. It returns when either enough packets were captured or timeout milliseconds elapsed without completion.

Parameters

[out]	packetVec	Destination vector for received packets. Each entry is a WinDivertRawPacket that owns its data.
[in]	timeout	Receive timeout in milliseconds. Use 0 with a positive maxPackets to wait until quota is reached.
[in]	maxPackets	Maximum packets to receive before returning. Use 0 for no limit (subject to timeout).
[in]	batchSize	Number of packets to read per WinDivert call (must be > 0). Default is 64.

Returns: A ReceiveResult describing the outcome. On failure, see error and errorCode.

◆ sendPackets()

SendResult pcpp::WinDivertDevice::sendPackets	(	const RawPacketVector &	packetVec,
		uint8_t	batchSize = `64`
	)		const

Send a vector of raw packets in batches.

The method copies packet data into an internal buffer and calls WinDivert send in batches of batchSize.

Parameters

[in]	packetVec	A vector of raw packets to send.
[in]	batchSize	Number of packets to send per WinDivert call (must be > 0). Default is 64.

Returns: A SendResult describing the outcome and number of packets sent.

◆ setPacketQueueParams()

void pcpp::WinDivertDevice::setPacketQueueParams ( const QueueParams & params ) const

Set WinDivert queue parameters.

Parameters

[in] params A map of queue parameters to set. Absent keys are left unchanged.

Note: Values units are: length (packets), time (milliseconds), size (bytes).

◆ stopReceive()

void pcpp::WinDivertDevice::stopReceive ( )

Request to stop an ongoing receivePackets(callback, ...) loop.

Note: This is thread-safe and can be called from a thread other than the receiving thread.

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ ReceivePacketCallback

Member Enumeration Documentation

◆ QueueParam

Constructor & Destructor Documentation

◆ WinDivertDevice()

Member Function Documentation

◆ getNetworkInterface()

◆ getNetworkInterfaces()

◆ getPacketQueueParams()

◆ getVersion()

◆ isOpened()

◆ open() [1/2]

◆ open() [2/2]

◆ receivePackets() [1/2]

◆ receivePackets() [2/2]

◆ sendPackets()

◆ setPacketQueueParams()

◆ stopReceive()