NPF structures and definitions
[NPF driver internals manual]


Data Structures
struct	packet_file_header
	Header of a libpcap dump file. More...
struct	sf_pkthdr
	Header associated to a packet in the driver's buffer when the driver is in dump mode. Similar to the bpf_hdr structure, but simpler. More...
struct	_INTERNAL_REQUEST
	Stores an OID request. More...
struct	_PACKET_RESERVED
	Contains a NDIS packet. More...
struct	_DEVICE_EXTENSION
	Port device extension. More...
struct	__CPU_Private_Data
	Kernel buffer of each CPU. More...
struct	_OPEN_INSTANCE
	Contains the state of a running instance of the NPF driver. More...
struct	PacketHeader
	Structure prepended to each packet in the kernel buffer pool. More...
Defines
#define	MAX_REQUESTS 32
	Maximum number of simultaneous IOCTL requests.
#define	Packet_ALIGNMENT sizeof(int)
	Alignment macro. Defines the alignment size.
#define	Packet_WORDALIGN(x) (((x)+(Packet_ALIGNMENT-1))&~(Packet_ALIGNMENT-1))
	even multiple of Packet_ALIGNMENT.
#define	KERNEL_EVENT_NAMESPACE L"\\BaseNamedObjects\\"
#define	BIOCSETBUFFERSIZE 9592
	IOCTL code: set kernel buffer size.
#define	BIOCSETF 9030
	IOCTL code: set packet filtering program.
#define	BIOCGSTATS 9031
	IOCTL code: get the capture stats.
#define	BIOCSRTIMEOUT 7416
	IOCTL code: set the read timeout.
#define	BIOCSMODE 7412
	IOCTL code: set working mode.
#define	BIOCSWRITEREP 7413
	IOCTL code: set number of physical repetions of every packet written by the app.
#define	BIOCSMINTOCOPY 7414
	IOCTL code: set minimum amount of data in the kernel buffer that unlocks a read call.
#define	BIOCSETOID 2147483648
	IOCTL code: set an OID value.
#define	BIOCQUERYOID 2147483652
	IOCTL code: get an OID value.
#define	BIOCSETDUMPFILENAME 9029
	IOCTL code: set the name of a the file used by kernel dump mode.
#define	BIOCGEVNAME 7415
	IOCTL code: get the name of the event that the driver signals when some data is present in the buffer.
#define	BIOCSENDPACKETSNOSYNC 9032
	IOCTL code: Send a buffer containing multiple packets to the network, ignoring the timestamps.
#define	BIOCSENDPACKETSSYNC 9033
	IOCTL code: Send a buffer containing multiple packets to the network, considering the timestamps.
#define	BIOCSETDUMPLIMITS 9034
	IOCTL code: Set the dump file limits.
#define	BIOCISDUMPENDED 7411
	IOCTL code: Get the status of the kernel dump process.
#define	BIOCISETLOBBEH 7410
	IOCTL code: set the loopback behavior.
#define	BIOCSETEVENTHANDLE 7920
	This IOCTL passes the read event HANDLE allocated by the user (packet.dll) to kernel level.
#define	MODE_CAPT 0x0
	Capture working mode.
#define	MODE_STAT 0x1
	Statistical working mode.
#define	MODE_MON 0x2
	Kernel monitoring mode.
#define	MODE_DUMP 0x10
	Kernel dump working mode.
#define	IMMEDIATE 1
	Immediate timeout. Forces a read call to return immediately.
#define	NDIS_FLAGS_SKIP_LOOPBACK_W2K 0x400
	This is an undocumented flag for NdisSetPacketFlags() that allows to disable loopback reception.
#define	TCPDUMP_MAGIC 0xa1b2c3d4
	Libpcap magic number. Used by programs like tcpdump to recognize a driver's generated dump file.
#define	PCAP_VERSION_MAJOR 2
	Major libpcap version of the dump file. Used by programs like tcpdump to recognize a driver's generated dump file.
#define	PCAP_VERSION_MINOR 4
	Minor libpcap version of the dump file. Used by programs like tcpdump to recognize a driver's generated dump file.
#define	NPF_DISABLE_LOOPBACK 1
	Tells the driver to drop the packets sent by itself. This is usefult when building applications like bridges.
#define	NPF_ENABLE_LOOPBACK 2
	Tells the driver to capture the packets sent by itself.
#define	RESERVED(_p) ((PPACKET_RESERVED)((_p)->ProtocolReserved))
	Macro to obtain a NDIS_PACKET from a PACKET_RESERVED.
#define	TRANSMIT_PACKETS 256
	of packets that can be transmitted at the same time or with a single call to NdisSendPackets.
#define	EXIT_SUCCESS(quantity)
	Macro used in the I/O routines to return the control to user-mode with a success status.
#define	EXIT_FAILURE(quantity)
	Macro used in the I/O routines to return the control to user-mode with a failure status.
Typedefs
typedef _INTERNAL_REQUEST	INTERNAL_REQUEST
	Stores an OID request.
typedef _INTERNAL_REQUEST *	PINTERNAL_REQUEST
	Stores an OID request.
typedef _PACKET_RESERVED	PACKET_RESERVED
	Contains a NDIS packet.
typedef _PACKET_RESERVED *	PPACKET_RESERVED
	Contains a NDIS packet.
typedef _DEVICE_EXTENSION	DEVICE_EXTENSION
	Port device extension.
typedef _DEVICE_EXTENSION *	PDEVICE_EXTENSION
	Port device extension.
typedef __CPU_Private_Data	CpuPrivateData
	Kernel buffer of each CPU.
typedef _OPEN_INSTANCE	OPEN_INSTANCE
	Contains the state of a running instance of the NPF driver.
typedef _OPEN_INSTANCE *	POPEN_INSTANCE
	Contains the state of a running instance of the NPF driver.
Enumerations
enum	ADAPTER_BINDING_STATUS { ADAPTER_UNBOUND, ADAPTER_BOUND, ADAPTER_UNBINDING }
Variables
ULONG	NCpu

Define Documentation

#define BIOCGEVNAME 7415

IOCTL code: get the name of the event that the driver signals when some data is present in the buffer.

Command used by the application to retrieve the name of the global event associated with a NPF instance. The event is signaled by the driver when the kernel buffer contains enough data for a transfer.

Definition at line 169 of file Packet.h.

#define BIOCGSTATS 9031

IOCTL code: get the capture stats.

This command returns to the application the number of packets received and the number of packets dropped by an instance of the driver.

Definition at line 107 of file Packet.h.

#define BIOCISDUMPENDED 7411

IOCTL code: Get the status of the kernel dump process.

This command returns TRUE if the kernel dump is ended, i.e if one of the limits set with BIOCSETDUMPLIMITS (amount of bytes or number of packets) has been reached.

Definition at line 204 of file Packet.h.

#define BIOCISETLOBBEH 7410

IOCTL code: set the loopback behavior.

This IOCTL sets the loopback behavior of the driver with packets sent by itself: capture or drop.

Definition at line 211 of file Packet.h.

#define BIOCQUERYOID 2147483652

IOCTL code: get an OID value.

This IOCTL is used to perform an OID get operation on the NIC driver.

Definition at line 152 of file Packet.h.

#define BIOCSENDPACKETSNOSYNC 9032

IOCTL code: Send a buffer containing multiple packets to the network, ignoring the timestamps.

Command used to send a buffer of packets in a single system call. Every packet in the buffer is preceded by a sf_pkthdr structure. The timestamps of the packets are ignored, i.e. the packets are sent as fast as possible. The NPF_BufferedWrite() function is invoked to send the packets.

Definition at line 178 of file Packet.h.

#define BIOCSENDPACKETSSYNC 9033

IOCTL code: Send a buffer containing multiple packets to the network, considering the timestamps.

Command used to send a buffer of packets in a single system call. Every packet in the buffer is preceded by a sf_pkthdr structure. The timestamps of the packets are used to synchronize the write, i.e. the packets are sent to the network respecting the intervals specified in the sf_pkthdr structure assiciated with each packet. NPF_BufferedWrite() function is invoked to send the packets.

Definition at line 188 of file Packet.h.

#define BIOCSETBUFFERSIZE 9592

IOCTL code: set kernel buffer size.

This IOCTL is used to set a new size of the circular buffer associated with an instance of NPF. When a BIOCSETBUFFERSIZE command is received, the driver frees the old buffer, allocates the new one and resets all the parameters associated with the buffer in the OPEN_INSTANCE structure. The currently buffered packets are lost.

Definition at line 87 of file Packet.h.

#define BIOCSETDUMPFILENAME 9029

IOCTL code: set the name of a the file used by kernel dump mode.

This command opens a file whose name is contained in the IOCTL buffer and associates it with current NPf instance. The dump thread uses it to copy the content of the circular buffer to file. If a file was already opened, the driver closes it before opening the new one.

Definition at line 161 of file Packet.h.

#define BIOCSETDUMPLIMITS 9034

IOCTL code: Set the dump file limits.

This IOCTL sets the limits (maximum size and maximum number of packets) of the dump file created when the driver works in dump mode.

Definition at line 196 of file Packet.h.

#define BIOCSETEVENTHANDLE 7920

This IOCTL passes the read event HANDLE allocated by the user (packet.dll) to kernel level.

Parameter: HANDLE Parameter size: sizeof(HANDLE). If the caller is 32 bit, the parameter size is 4 bytes, even if sizeof(HANDLE) at kernel level is 8 bytes. That's why in this IOCTL code handler we detect a 32bit calling process and do the necessary thunking.

TODO GV:I will go to hell for this ugly IOCTL definition. We should use CTL_CODE!!

Definition at line 222 of file Packet.h.

#define BIOCSETF 9030

IOCTL code: set packet filtering program.

This IOCTL sets a new packet filter in the driver. Before allocating any memory for the new filter, the bpf_validate() function is called to check the correctness of the filter. If this function returns TRUE, the filter is copied to the driver's memory, its address is stored in the bpfprogram field of the OPEN_INSTANCE structure associated with current instance of the driver, and the filter will be applied to every incoming packet. This command also empties the circular buffer used by current instance to store packets. This is done to avoid the presence in the buffer of packets that do not match the filter.

Definition at line 99 of file Packet.h.

#define BIOCSETOID 2147483648

IOCTL code: set an OID value.

This IOCTL is used to perform an OID set operation on the NIC driver.

Definition at line 145 of file Packet.h.

#define BIOCSMINTOCOPY 7414

IOCTL code: set minimum amount of data in the kernel buffer that unlocks a read call.

This command sets the OPEN_INSTANCE::MinToCopy member.

Definition at line 138 of file Packet.h.

#define BIOCSMODE 7412

IOCTL code: set working mode.

This IOCTL can be used to set the working mode of a NPF instance. The new mode, received by the driver in the buffer associated with the IOCTL command, can be MODE_CAPT for capture mode (the default), MODE_STAT for statistical mode or MODE_DUMP for dump mode.

Definition at line 123 of file Packet.h.

#define BIOCSRTIMEOUT 7416

IOCTL code: set the read timeout.

This command sets the maximum timeout after which a read is released, also if no data packets were received.

Definition at line 114 of file Packet.h.

#define BIOCSWRITEREP 7413

IOCTL code: set number of physical repetions of every packet written by the app.

Sets the number of times a single write call must be repeated. This command sets the OPEN_INSTANCE::Nwrites member, and is used to implement the 'multiple write' feature of the driver.

Definition at line 131 of file Packet.h.

#define EXIT_FAILURE ( quantity )

Value:

Irp->IoStatus.Information=quantity;\
    Irp->IoStatus.Status = STATUS_UNSUCCESSFUL;\
    IoCompleteRequest(Irp, IO_NO_INCREMENT);\
    return STATUS_UNSUCCESSFUL;\

Macro used in the I/O routines to return the control to user-mode with a failure status.

Definition at line 471 of file Packet.h.

#define EXIT_SUCCESS ( quantity )

Value:

Irp->IoStatus.Information=quantity;\
    Irp->IoStatus.Status = STATUS_SUCCESS;\
    IoCompleteRequest(Irp, IO_NO_INCREMENT);\
    return STATUS_SUCCESS;\

Macro used in the I/O routines to return the control to user-mode with a success status.

Definition at line 465 of file Packet.h.

#define IMMEDIATE 1

Immediate timeout. Forces a read call to return immediately.

Definition at line 231 of file Packet.h.

#define KERNEL_EVENT_NAMESPACE L"\\BaseNamedObjects\\"

Definition at line 73 of file Packet.h.

#define MAX_REQUESTS 32

Maximum number of simultaneous IOCTL requests.

Definition at line 67 of file Packet.h.

#define MODE_CAPT 0x0

Capture working mode.

Definition at line 225 of file Packet.h.

#define MODE_DUMP 0x10

Kernel dump working mode.

Definition at line 228 of file Packet.h.

#define MODE_MON 0x2

Kernel monitoring mode.

Definition at line 227 of file Packet.h.

#define MODE_STAT 0x1

Statistical working mode.

Definition at line 226 of file Packet.h.

#define NDIS_FLAGS_SKIP_LOOPBACK_W2K 0x400

This is an undocumented flag for NdisSetPacketFlags() that allows to disable loopback reception.

Definition at line 233 of file Packet.h.

#define NPF_DISABLE_LOOPBACK 1

Tells the driver to drop the packets sent by itself. This is usefult when building applications like bridges.

Definition at line 242 of file Packet.h.

#define NPF_ENABLE_LOOPBACK 2

Tells the driver to capture the packets sent by itself.

Definition at line 243 of file Packet.h.

#define Packet_ALIGNMENT sizeof(int)

Alignment macro. Defines the alignment size.

Definition at line 69 of file Packet.h.

#define Packet_WORDALIGN ( x ) (((x)+(Packet_ALIGNMENT-1))&~(Packet_ALIGNMENT-1))

even multiple of Packet_ALIGNMENT.

Alignment macro. Rounds up to the next

Definition at line 70 of file Packet.h.

#define PCAP_VERSION_MAJOR 2

Major libpcap version of the dump file. Used by programs like tcpdump to recognize a driver's generated dump file.

Definition at line 238 of file Packet.h.

#define PCAP_VERSION_MINOR 4

Minor libpcap version of the dump file. Used by programs like tcpdump to recognize a driver's generated dump file.

Definition at line 239 of file Packet.h.

#define RESERVED ( _p ) ((PPACKET_RESERVED)((_p)->ProtocolReserved))

Macro to obtain a NDIS_PACKET from a PACKET_RESERVED.

Definition at line 308 of file Packet.h.

#define TCPDUMP_MAGIC 0xa1b2c3d4

Libpcap magic number. Used by programs like tcpdump to recognize a driver's generated dump file.

Definition at line 237 of file Packet.h.

#define TRANSMIT_PACKETS 256

of packets that can be transmitted at the same time or with a single call to NdisSendPackets.

Maximum number of packets in the transmit packet pool. This value is an upper bound to the number

Definition at line 460 of file Packet.h.

Typedef Documentation

typedef struct __CPU_Private_Data CpuPrivateData

Kernel buffer of each CPU.

Structure containing the kernel buffer (and other CPU related fields) used to capture packets.

typedef struct _DEVICE_EXTENSION DEVICE_EXTENSION

Port device extension.

Structure containing some data relative to every adapter on which NPF is bound.

typedef struct _INTERNAL_REQUEST INTERNAL_REQUEST

Stores an OID request.

This structure is used by the driver to perform OID query or set operations on the underlying NIC driver. The OID operations be performed usually only by network drivers, but NPF exports this mechanism to user-level applications through an IOCTL interface. The driver uses this structure to wrap a NDIS_REQUEST structure. This allows to handle correctly the callback structure of NdisRequest(), handling multiple requests and maintaining information about the IRPs to complete.

typedef struct _OPEN_INSTANCE OPEN_INSTANCE

Contains the state of a running instance of the NPF driver.

This is the most important structure of NPF: it is used by almost all the functions of the driver. An _OPEN_INSTANCE structure is associated with every user-level session, allowing concurrent access to the driver.

typedef struct _PACKET_RESERVED PACKET_RESERVED

Contains a NDIS packet.

The driver uses this structure to wrap a NDIS_PACKET structure. This allows to handle correctly the callback structure of NdisTransferData(), handling multiple requests and maintaining information about the IRPs to complete.

typedef struct _DEVICE_EXTENSION * PDEVICE_EXTENSION

Port device extension.

Structure containing some data relative to every adapter on which NPF is bound.

typedef struct _INTERNAL_REQUEST * PINTERNAL_REQUEST

Stores an OID request.

typedef struct _OPEN_INSTANCE * POPEN_INSTANCE

Contains the state of a running instance of the NPF driver.

typedef struct _PACKET_RESERVED * PPACKET_RESERVED

Contains a NDIS packet.