Introduction

Windows Packet Filter Kit: Introduction

NT Kernel Resources

http://ntkernel.com

WinpkFilter 3.1

Help File

Copyright(C) NT Kernel Resources 2000-2013

http://www.ntkernel.com/products/winpkfilter.htm

support@ntkernel.com


What is WinpkFilter

Windows Packet Filter Kit: Introduction

What is WinpkFilter©?

WinpkFilter is a high performance packet filtering framework for Windows 9x/ME/NT/2000/XP/2003/Vista/2008 that allows developers to transparently filter (view and modify) raw network packets with minimal impact on network activity without having to write low level TDI or NDIS driver code.

WinpkFilter is more than just a firewall development kit for Windows. Wide range of solutions can be implemented using WinpkFilter: custom firewalls, internet connection sharing (NAT), IP shaper, VPN and many other low-level network solutions completely in user-mode using your favorite development environment: Visual C++, Delphi, C++ Builder etc.

Using WinpkFilter requires no experience in kernel mode programming on your behalf since WinpkFilter provides you with powerful user level API. However, if you need to implement your solution (to achieve better performance) in kernel mode you can use well-documented raw IOCTL interface as well.

Product features:

  • The easiest way to develop and debug packet filtering/modifying communication applications such as firewalls, sniffers, internet connection sharing, VPN, etc.
  • Full portability to all Windows platforms due to the common API.
  • Operates on RAS/PPP adapters
  • Complete source code for sample applications and wrapper API DLL (registered version only) is available. Source code for helper drivers supplied when you purchase Source Code License ONLY.
  • Passive network listening and active filtering (with possible packet modification) modes
  • Interface for sending RAW Ethernet packets to network interface (originated by MSTCP) or to MSTCP
  • Supports MTU decrement (allows you to set system-wide MTU decrement). This option is required if you plan to add additional headers to IP packets (implement IP in IP packet tunneling, IPSEC based VPN and so on).
  • Helper routines in ndisapi.dll for converting internal (NDIS level) network interface names to the user friendly ones (the names you see in Network connections properties)
  • 32 bit helper drivers are based on NDIS-hooking and NDIS intermediate driver technology.
  • 64 bit helper drivers are based on NDIS intermediate driver technology.

Windows Packet Filter Kit can be used for the wide range of applications. Here are few of them:

  • User-mode firewall solutions. That’s right! WinpkFilter allows implementing a firewall completely in user-mode. This is not recommended for high speed connections (over 100Mbit) since filtering network packets in user-mode decreases network performance up to 30-40%, but it is quite useful for dial-up, DSL or even 100MBit Ethernet connections.
  • Kernel-mode firewall solutions. You can use RAW IOCTLs for calling helper driver from your kernel mode driver. This requires kernel-mode programming skills while eliminating performance degradation caused by redirecting packets from kernel mode to user mode and back.
  • Internet Connection Sharing (Network Address Translation) that can be implemented both in user and kernel modes.
  • VPN solution (IPSEC an example) that can also be implemented both in user and kernel modes.
  • Packets tunneling. Example: packets captured from the network (or from MSTCP) delivered into the user mode and tunneled to the remote system inside SSL stream. Remote system can indicate them to MSTCP (or send over network) after extracting packets from the SSL stream. Classic approaches like ‘IP in IP’ can also be implemented.
  • Packet sniffer. You can inspect all packets sent to (received from) MSTCP.
  • IP shaping solutions (when you need to limit bandwidth for Internet users).
  • Network traffic count solutions.
  • Wireless Firewall Gateways.

"The core" of WinpkFilter is composed by following files:

ndisrd.vxd | The virtual device driver supported by Windows 95/98/ME. Must be located under \<windows>\system;
ndisrd.sys | The kernel-mode driver supported by Windows NT/2000/XP/2003/Vista/7. Must be located under \<winnt>\system32\drivers; This driver exists in three forms: NDIS-hooking (can be used on Windows NT 4.0, Windows 2000, Windows XP, Windows 2003), NDIS IM one (can be used on Windows XP x64, Windows 2003 x64, Windows Vista/2008 x86/x64, Windows 7/2008R2 x86/x64), NDIS 6 LWF driver (can be used for Windows Vista/2008/7/2008R2/8/2012 x86/x64).
ndisapi.dll | The library providing driver function call for almost all programming languages. Must be located under \<windows>\system or any other directory available for the running application. Note, that ndisapi.dll is available in two variants for Microsoft Visual C++ and for Borland C++ Builder due to the difference in the *.lib file format and exporting C++ classes.
ndisapi.h | header file providing a C/C++ interface to ndisapi.dll
modDecl_Ndisapi.bas | provides a MSVB6 interface to ndisapi.dll
ndisapi.pas | provides a Delphi interface to ndisapi.dll
ndisapi.cs | provides a C# interface to ndisapi.dll

Copyright NT Kernel Resources © 2000-2013


Introduction

Windows Packet Filter Kit: Introduction

Programming Languages Support

WinpkFilter provides an interface to drivers for:

· Microsoft Visual C/C++

· Microsoft Visual C#

· Microsoft Visual Basic 6

· Borland Delphi (versions 2-7)

· Borland C++ Builder (versions 1, 3, 4, 5)

· Other programming systems that access functions in DLL's


Windows Packet Filter Kit: Installation

Installation of WinpkFilter© 3.0

WinpkFilter setup script will automatically configure your system and install required helper drivers. However, if your license allows driver redistribution and you plan to install helper drivers within your own setup script you should do the following:

Windows 9x/ME
Using NDIS Hooking VxD Filter Driver

Copy ndisrd.vxd to the \WINDOWS\SYSTEM directory and create the following registry key in order to start helper driver on system boot:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\NDISRD

Under this key you should create the following REG_SZ value:

"StaticVxD"="NDISRD.VxD"
Windows NT 4.0
Using NDIS Hooking Filter Driver

Copy ndisrd.sys to the \WINNT\SYSTEM32\DRIVERS directory and create the following registry key in order to start helper driver on system boot:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\NDISRD

Under this key you should create the following values:

"Type"=0x00000001 (REG_DWORD)

"Group"="Network" (REG_SZ)

"Start"=0x00000001 (REG_DWORD)

"Error Control"=0x00000001 (REG_DWORD)
Windows 2000/XP/2003 (32 bit OS)
Using NDIS Hooking Filter Driver

Copy ndisrd.sys to the \WINNT\SYSTEM32\DRIVERS directory and create the following registry key in order to start helper driver on system boot:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\NDISRD

Under this key you should create the following values:

"Type"=0x00000001 (REG_DWORD)

"Group"="Streams Drivers" (REG_SZ)

"Start"=0x00000001 (REG_DWORD)

"Error Control"=0x00000001 (REG_DWORD)

Windows XP/2003 x64
Windows Vista
Windows Server 2008
Using NDIS 5 Intermediate Filter Driver

Manual installation:

Prepare a floppy disk (or installation directory) that contains these files: ndisrd.inf, ndisrd_m.inf and ndisrd.sys. On the desktop, right-click the My Network Places icon and choose Properties. Right-click on the relevant Local Area Connection icon and choose Properties. Click Install, then Service, then Add, then Have Disk. Browse to the drive/directory containing the files listed above. Click OK. This should show "WinpkFilter Driver" in a list of Network Services. Highlight this and click OK. This should install the WinpkFilter driver. Click OK or Yes each time the system prompts with a warning regarding installation of unsigned files. This is necessary because binaries generated via the DDK build environment are not signed. Two .INF files are needed rather than one because WinpkFilter is installed both as a protocol and a miniport.

Automatic installation:

WinpkFilter package contains a modified version of snetcfg tool (original version of which can be found in the DDK) which allows automatic installation of WinpkFilter drivers. The command line below will install WinpkFilter driver automatically (snetcfg.exe, ndisrd.inf, ndisrd_m.inf and ndisrd.sys should be in the same folder):

snetcfg.exe -v -l ndisrd.inf -m ndisrd_m.inf -c s -i nt_ndisrd

Next command uninstalls WinpkFilter driver:

snetcfg.exe -v -u nt_ndisrd

Important note:

For Windows Vista and later versions of the Windows family of operating systems, kernel-mode software must have a digital signature to load on x64-based computer systems. WinpkFilter drivers are not signed and in order to test them on Vista/7 x64 you should press F8 during system boot and choose Disable Driver Signature Enforcement option. For the commercial software you'd have to obtain Code Signing certificate from Verysign.

Windows Vista
Windows Server 2008
Windows 7
Windows Server 2008 R2
Windows 8
Windows Server 2012
Using NDIS 6 Light Weight Filter Driver

These operating systems are supported by WinpkFilter driver based on NDIS Light Weight Filter driver.

Manual installation:

Prepare a floppy disk (or installation directory) that contains these files: ndisrd_lwf.inf and ndisrd.sys. On the desktop, right-click the My Network Places icon and choose Properties. Right-click on the relevant Local Area Connection icon and choose Properties. Click Install, then Service, then Add, then Have Disk. Browse to the drive/directory containing the files listed above. Click OK. This should show "WinpkFilter Light Weight Filter Driver" in a list of Network Services. Highlight this and click OK. This should install the WinpkFilter driver. Click OK or Yes each time the system prompts with a warning regarding installation of unsigned files. This is necessary because binaries generated via the DDK build environment are not signed.

Automatic installation:

WinpkFilter package contains a modified version of snetcfg tool (original version of which can be found in the DDK) which allows automatic installation of WinpkFilter drivers. The command line below will install WinpkFilter driver automatically (snetcfg.exe, ndisrd_lwf.inf and ndisrd.sys should be in the same folder):

snetcfg.exe -v -l ndisrd_lwf.inf -c s -i nt_ndisrd

Next command uninstalls WinpkFilter driver:

snetcfg.exe -v -u nt_ndisrd

Important note:

For Windows Vista and later versions of the Windows family of operating systems, kernel-mode software must have a digital signature to load on x64-based computer systems. WinpkFilter drivers are not signed and in order to test them on Vista/7 x64 you should press F8 during system boot and choose Disable Driver Signature Enforcement option. For the commercial software you'd have to obtain Code Signing certificate from Verysign.


Helper Drivers IOCTLs

Helper drivers support the following set of control codes (defined in common.h):

IOCTL_NDISRD_GET_VERSION
IOCTL_NDISRD_GET_TCPIP_INTERFACES
IOCTL_NDISRD_SEND_PACKET_TO_ADAPTER
IOCTL_NDISRD_SEND_PACKET_TO_MSTCP
IOCTL_NDISRD_READ_PACKET
IOCTL_NDISRD_SEND_PACKETS_TO_ADAPTER
IOCTL_NDISRD_SEND_PACKETS_TO_MSTCP
IOCTL_NDISRD_READ_PACKETS
IOCTL_NDISRD_SET_ADAPTER_MODE
IOCTL_NDISRD_FLUSH_ADAPTER_QUEUE
IOCTL_NDISRD_GET_RAS_LINKS
IOCTL_NDISRD_ADAPTER_QUEUE_SIZE
IOCTL_NDISRD_SET_EVENT
IOCTL_NDISRD_SET_PACKET_FILTERS
IOCTL_NDISRD_RESET_PACKET_FILTERS
IOCTL_NDISRD_GET_PACKET_FILTERS_TABLESIZE
IOCTL_NDISRD_GET_PACKET_FILTERS
IOCTL_NDISRD_GET_PACKET_FILTERS_RESET_STATS

All requests use buffered synchronous I/O.


IOCTL_NDISRD_ADAPTER_QUEUE_SIZE

This IOCTL returns current packets queue size for the given adapter.

Input Buffer | Adapter handle value
Input Buffer Size | 4
Output Buffer | Number of packets in the adapters queue
Output Buffer Size | 4

Remarks:

This control code is useful if you need to realize sort of flood attack protection in your WinpkFilter application, e.g. if adapter packet queue grows above some critical limit (under flood attack an example) then use IOCTL_NDISRD_FLUSH_ADAPTER_QUEUE in order to prevent filter driver packet buffer starving.


IOCTL_NDISRD_FLUSH_ADAPTER_QUEUE

This IOCTL flushes adapter packet queue. Use this IOCTL when you finished working with interface in order to release locked resources.

Input Buffer | Adapter handle value
Input Buffer Size | 4 bytes
Output Buffer | None
Output Buffer Size | 0

Remarks:

Helper driver will flush packet queue for the requested interface on this request.


IOCTL_NDISRD_GET_ADAPTER_MODE

This IOCTL returns the redirection flags for the selected adapter. See details in _ADAPTER_MODE structure description.

Input Buffer | _ADAPTER_MODE
Input Buffer Size | sizeof (_ADAPTER_MODE)
Output Buffer | _ADAPTER_MODE
Output Buffer Size | sizeof (_ADAPTER_MODE)

Remarks:

For this call the following field of ADAPTER_MODE must be initialized:

  • ADAPTER_MODE.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo).

As a result of this call driver fills the field of ADAPTER_MODE below:

  • ADAPTER_MODE.dwFlags is a combination of the XXX_LISTEN or XXX_TUNNEL flags:
    • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
    • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
    • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
    • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

    Version 2.0 of WinpkFilter has added three new flags:

    • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

    By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

    • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
    • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.


IOCTL_NDISRD_GET_PACKET_FILTERS_RESET_STATS

This IOCTL sets packet filter table into the driver.

Input Buffer | _STATIC_FILTER_TABLE
Input Buffer Size | Variable, depends of number of entries in the table
Output Buffer | _STATIC_FILTER_TABLE
Output Buffer Size | Variable, depends of number of entries in the table

Remarks:

You should allocate STATIC_FILTER_TABLE structure large enough to fit the one loaded into WinpkFilter driver. You can get the number of entries in the STATIC_FILTER_TABLE.m_TableSize using the GetPacketFilterTableSize API call. Basically this API does the same as IOCTL_NDISRD_GET_PACKET_FILTERS_RESET_STATS but also resets packets and bytes counters.


IOCTL_NDISRD_GET_PACKET_FILTERS

This IOCTL sets packet filter table into the driver.

Input Buffer | _STATIC_FILTER_TABLE
Input Buffer Size | Variable, depends of number of entries in the table
Output Buffer | _STATIC_FILTER_TABLE
Output Buffer Size | Variable, depends of number of entries in the table

Remarks:

You should allocate STATIC_FILTER_TABLE structure large enough to fit the one loaded into WinpkFilter driver. You can get the number of entries in the STATIC_FILTER_TABLE.m_TableSize using the GetPacketFilterTableSize API call.


IOCTL_NDISRD_GET_PACKET_FILTERS_TABLESIZE

This IOCTL sets packet filter table into the driver.

Input Buffer | DWORD
Input Buffer Size | 4
Output Buffer | DWORD
Output Buffer Size | 4

Remarks:

Receives the number of filters in the STATIC_FILTER_TABLE currently loaded into the WinpkFilter driver


IOCTL_NDISRD_GET_RAS_LINKS

This IOCTL queries MSTCP interfaces information.

Input Buffer | None
Input Buffer Size | 0
Output Buffer | _RAS_LINKS
Output Buffer Size | sizeof(_RAS_LINKS) bytes

Remarks:

Helper driver fills _RAS_LINKS with information about active WAN connections.


IOCTL_NDISRD_GET_TCPIP_INTERFACES

This IOCTL queries MSTCP interfaces information.

Input Buffer | None
Input Buffer Size | 0
Output Buffer | _TCP_AdapterList
Output Buffer Size | sizeof(_TCP_AdaptersList) bytes

Remarks:

Helper driver will fill TCP_AdapterList with MSTCP associated interfaces information (permanent and current MAC's, MTU, internal interface name, medium and handle required for calling any adapter associated services).


IOCTL_NDISRD_GET_VERSION

This IOCTL queries version information from the helper driver.

Input Buffer | None
Input Buffer Size | 0
Output Buffer | uint32
Output Buffer Size | 4 bytes


IOCTL_NDISRD_READ_PACKET

This IOCTL reads packet from the helper driver queue.

Input Buffer | _ETH_REQUEST
Input Buffer Size | sizeof (_ETH_REQUEST)
Output Buffer | _ETH_REQUEST
Output Buffer Size | sizeof (_ETH_REQUEST)

Remarks:

For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo). The packet will be extracted from the network interface associated packet queue. Remember that packets queued only when network interface in the filtering of listening mode.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER are initialized by helper driver in case of success:

  • INTERMEDIATE_BUFFER.m_IBuffer contains Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length contains the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags is a combination of NDIS_FLAGS_XXX (defined in ndis.h). These flags are copied from the NDIS_PACKET.Private.Flags.
  • INTERMEDIATE_BUFFER.m_dwDeviceFlags is PACKET_FLAG_ON_SEND if packet goes from MSTCP to network interface or PACKET_FLAG_ON_RECEIVE otherwise.


IOCTL_NDISRD_READ_PACKETS

This IOCTL reads a bulk of packets from the helper driver queue.
Input Buffer | _ETH_M_REQUEST
Input Buffer Size | sizeof (_ETH_M_REQUEST)
Output Buffer | _ETH_M_REQUEST
Output Buffer Size | sizeof (_ETH_M_REQUEST)

Remarks:

For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo). The packets will be extracted from the network interface associated packet queue. Remember that packets queued only when network interface in the filtering of listening mode.
  • ETH_M_REQUEST.dwPacketsNumber must be set to a number of entries in EthPacket array
  • ETH_M_REQUEST.EthPacket[i].Buffer must point to the user allocated INTERMEDIATE_BUFFER structure

The following fields of the ETH_M_REQUEST and INTERMEDIATE_BUFFER are initialized by helper driver in case of success:

  • ETH_M_REQUEST.dwPacketSuccess contains number of packets returned by driver
  • INTERMEDIATE_BUFFER.m_IBuffer contains Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length contains the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags is a combination of NDIS_FLAGS_XXX (defined in ndis.h). These flags are copied from the NDIS_PACKET.Private.Flags.
  • INTERMEDIATE_BUFFER.m_dwDeviceFlags is PACKET_FLAG_ON_SEND if packet goes from MSTCP to network interface or PACKET_FLAG_ON_RECEIVE otherwise.


IOCTL_NDISRD_RESET_PACKET_FILTERS

This IOCTL sets packet filter table into the driver.

Input Buffer | None
Input Buffer Size | 0
Output Buffer | None
Output Buffer Size | 0

Remarks:

This API call removes all filters from WinpkFilter driver.


IOCTL_NDISRD_SEND_PACKET_TO_ADAPTER

This IOCTL requests the helper driver to send raw Ethernet packet on the selected interface.

Input Buffer | _ETH_REQUEST
Input Buffer Size | sizeof (_ETH_REQUEST)
Output Buffer | None
Output Buffer Size | 0

Remarks:

For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) to which you would like to send packet.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags should be initialized by combination of NDIS_FLAGS_XXX (defined in ndis.h). Look at these flags for details. Note, that these flags usually don't work for the old NDIS versions.


IOCTL_NDISRD_SEND_PACKET_TO_MSTCP

This IOCTL requests the helper driver to indicate the raw Ethernet packet to MSTCP as it was received from the selected interface.

Input Buffer | _ETH_REQUEST
Input Buffer Size | sizeof (_ETH_REQUEST)
Output Buffer | None
Output Buffer Size | 0

Remarks:

For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) from which you would like to simulate receive.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet


IOCTL_NDISRD_SEND_PACKETS_TO_ADAPTER

This IOCTL requests the helper driver to send a bulk of raw Ethernet packet on the selected interface.
Input Buffer | _ETH_M_REQUEST
Input Buffer Size | sizeof (_ETH_M_REQUEST)
Output Buffer | None
Output Buffer Size | 0

Remarks:

For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) to which you would like to send packets.
  • ETH_M_REQUEST.dwPacketsNumber must be set to the number of initialized NDISRD_ETH_Packet structures in EthPacket array
  • ETH_M_REQUEST.EthPacket[].Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags should be initialized by combination of NDIS_FLAGS_XXX (defined in ndis.h). Look at these flags for details. Note, that these flags usually don't work for the old NDIS versions.


IOCTL_NDISRD_SEND_PACKETS_TO_MSTCP

This IOCTL requests the helper driver to indicate the bulk of raw Ethernet packets to MSTCP as it was received from the selected interface.
Input Buffer | _ETH_M_REQUEST
Input Buffer Size | sizeof (_ETH_M_REQUEST)
Output Buffer | None
Output Buffer Size | 0

Remarks:

For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) from which you would like to simulate receive.
  • ETH_M_REQUEST.dwPacketsNumber must be set to the number of initialized NDISRD_ETH_Packet structures in EthPacket array
  • ETH_M_REQUEST.EthPacket[].Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet


IOCTL_NDISRD_SET_EVENT

Windows Packet Filter Kit: Helper Drivers IOCTLs

IOCTL_NDISRD_SET_ADAPTER_EVENT

This IOCTL registers the Win32 event handle within helper driver. Driver sets event into the signaled state when TCP/IP bound adapter's list changes.

Input Buffer | Win32 event handle or NULL if you want to release event.
Input Buffer Size | 4
Output Buffer | None
Output Buffer Size | 0

Remarks:

User application should create Win32 event (with CreateEvent API call) and pass event handle to this function. To release event pass NULL instead event handle into this IOCTL. For Windows 9x/ME you should translate Ring3 event handle to Ring0 one (see details in the ndisapi.dll source code) . Helper driver will signal this event when TCP/IP bound adapter's list changes. Usually you should call GetTcpipBoundAdaptersInfo and renew your adapter associated structures on this event.


IOCTL_NDISRD_SET_ADAPTER_MODE

This IOCTL sets the redirection flags for the selected adapter. See details in _ADAPTER_MODE structure description.

Input Buffer | _ADAPTER_MODE
Input Buffer Size | sizeof (_ADAPTER_MODE)
Output Buffer | None
Output Buffer Size | 0

Remarks:

For this call the following fields of ADAPTER_MODE must be initialized:

  • ADAPTER_MODE.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo).
  • ADAPTER_MODE.dwFlags must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:
    • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
    • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
    • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
    • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

    Version 2.0 of WinpkFilter has added three new flags:

    • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

    By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

    • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
    • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.


IOCTL_NDISRD_SET_EVENT

This IOCTL registers the Win32 event handle for specified network interface within helper driver. Driver sets event into the signaled state when adapter associated packet queue is not empty.

Input Buffer | Pointer to _ADAPTER_EVENT.
Input Buffer Size | sizeof(_ADAPTER_EVENT)
Output Buffer | None
Output Buffer Size | 0

Remarks:

User application should create Win32 event (with CreateEvent API call) and pass adapter handle and event handle to this function as the fields of _ADAPTER_EVENT structure. To release event pass NULL instead event handle into this IOCTL. For Windows 9x/ME you should translate Ring3 event handle to Ring0 one. See details in the ndisapi.dll and in _ADAPTER_EVENT structure description. Helper driver will signal this event when adapter associated packet queue is non-empty.


IOCTL_NDISRD_SET_PACKET_FILTERS

This IOCTL sets packet filter table into the driver.

Input Buffer | _STATIC_FILTER_TABLE
Input Buffer Size | Variable, depends of number of entries in the table
Output Buffer | None
Output Buffer Size | 0

Remarks:

You should allocate and initialize STATIC_FILTER_TABLE structure before passing iot to the driver. STATIC_FILTER_TABLE.m_TableSize should be set to number of entries in STATIC_FILTER_TABLE.m_StaticFilters. Filters are applied in their order m_StaticFilters array. Only one table can be loaded into the WinpkFilter driver.


IOCTL_NDISRD_SET_EVENT

Windows Packet Filter Kit: Helper Drivers IOCTLs

IOCTL_NDISRD_SET_WAN_EVENT

This IOCTL registers the Win32 event handle within helper driver. Driver sets event into the signaled state when WAN (dial-up, DSL, ADSL, ISDN or etc.) connection established or terminated.

Input Buffer | Win32 event handle or NULL if you want to release event.
Input Buffer Size | 4
Output Buffer | None
Output Buffer Size | 0

Remarks:

User application should create Win32 event (with CreateEvent API call) and pass event handle to this function. To release event pass NULL instead event handle into this IOCTL. For Windows 9x/ME you should translate Ring3 event handle to Ring0 one (see details in the ndisapi.dll source code). Helper driver will signal this event when WAN(dial-up, DSL, ADSL, ISDN or etc.) connection established or terminated


Wrapper DLL Interface

NDISAPI.DLL exports single C++ class (CNdisApi, declared in ndisapi.h) for usage from C/C++ environment and the set of wrapper C-style functions for usage from C/C++, Delphi, Visual Basic and other programming systems that access functions in DLL's.

Important Note: WinpkFilter package contains two versions of ndisapi.dll, one is for usage with Microsoft Visual C++ and another is for Borland C++ Builder. This is done because Microsoft Visual C++ and Borland C++ Builder uses different format for *.lib files and different C++ name mangling. However, if you use C interface from your programming system there is no differ which DLL to use.


C++ Interface

NDISAPI.DLL exports single C++ class (CNdisApi, declared in ndisapi.h), which hides platform dependent details from end user and implements some helper routines. This section describes CNdisApi in details.

Class Members:

Construction

CNdisApi

Destruction

~CNdisApi

Operations

DeviceIoControl

GetVersion

GetTcpipBoundAdaptersInfo

SendPacketToMstcp

SendPacketToAdapter

ReadPacket

SendPacketsToMstcp

SendPacketsToAdapter

ReadPackets

SetAdapterMode

FlushAdapterPacketQueue

GetAdapterPacketQueueSize

SetPacketEvent

NdisrdRequest

GetRasLinks

SetHwPacketFilter

GetHwPacketFilter

SetMTUDecrement

GetMTUDecrement

GetAdaptersStartupMode

SetAdaptersStartupMode

SetPacketFilterTable

ResetPacketFilterTable

GetPacketFilterTableSize

GetPacketFilterTable

GetPacketFilterTableResetStats

Static Helper Routines

ConvertWindowsNTAdapterName

ConvertWindows2000AdapterName

ConvertWindows9xAdapterName

Attributes

IsDriverLoaded

GetBytesReturned


CNdisApi::CNdisApi

CNdisApi (const TCHAR* pszFileName = _T("NDISRD"));

Parameters:

pszFileName

Specifies device name to open.

Remarks:

By default WinpkFilter helper device opened. You can create more then one CNdisApi object, but this is not recommended. Helper driver does not support per process (and per object contexts) so if packet was read from the driver queue it's removed from there, additionally only one event (last set) will be set to signal state on packet queuing. This is done for better performance. However, you can use additional CNdisApi objects for reading MSTCP interface configuration, sending raw Ethernet packets on the network or to the MSTCP and etc.


CNdisApi::~CNdisApi

~CNdisApi();

Parameters:

None

Remarks:

The destructor closes device and releases internal resources.


CNdisApi::ConvertWindows2000AdapterName

static BOOL ConvertWindows2000AdapterName (LPCSTR szAdapterName, LPSTR szUserFriendlyName, DWORD dwUserFriendlyNameLength);

Return Value:

TRUE in case of success, FALSE otherwise

Parameters:

szAdapterName

Internal adapter name returned by GetTcpipBoundAdaptersInfo call.

szUserFriendlyName

Pointer to user allocated buffer where user user-friendly name placed in case of success

dwUserFriendlyNameLength

Size of buffer in bytes pointed by szUserFriendlyName

Remarks:

This function converts internal network interface name returned by GetTcpipBoundAdaptersInfo into the one you see in Network Connections properties. This function should be called for Windows 2000 and XP only.


CNdisApi::ConvertWindows9xAdapterName

static BOOL ConvertWindows9xAdapterName (LPCSTR szAdapterName, LPSTR szUserFriendlyName, DWORD dwUserFriendlyNameLength);

Return Value:

TRUE in case of success, FALSE otherwise

Parameters:

szAdapterName

Internal adapter name returned by GetTcpipBoundAdaptersInfo call.

szUserFriendlyName

Pointer to user allocated buffer where user-friendly adapter name placed in case of success

dwUserFriendlyNameLength

Size of buffer in bytes pointed by szUserFriendlyName

Remarks:

This function converts internal network interface name returned by GetTcpipBoundAdaptersInfo into the one you see in Network Connections properties. This function should be called for Windows 9x and ME only.


CNdisApi::ConvertWindowsNTAdapterName

static BOOL ConvertWindowsNTAdapterName (LPCSTR szAdapterName, LPSTR szUserFriendlyName, DWORD dwUserFriendlyNameLength);

Return Value:

TRUE in case of success, FALSE otherwise

Parameters:

szAdapterName

Internal adapter name returned by GetTcpipBoundAdaptersInfo call.

szUserFriendlyName

Pointer to user allocated buffer where user-friendly adapter name placed in case of success

dwUserFriendlyNameLength

Size of buffer in bytes pointed by szUserFriendlyName

Remarks:

This function converts internal network interface name returned by GetTcpipBoundAdaptersInfo into the one you see in Network Connections properties. This function should be called for Windows NT4.0 only.


CNdisApi::DeviceIoControl

BOOL DeviceIoControl (DWORD dwService, void *BuffIn, int SizeIn, void *BuffOut, int SizeOut, int *SizeRet = NULL, LPOVERLAPPED povlp = NULL);

Return Value:

TRUE if request succeeded, FALSE otherwise

Parameters:

dwService

Specifies IOCTL to pass to the helper driver.

BuffIn

Specifies the input buffer pointer.

SizeIn

Specifies the size of input buffer.

BuffOut

Specifies the output buffer pointer.

SizeOut

Specifies the size of output buffer.

SizeRet

Specifies the optional parameter to save number of bytes returned by DeviceIoControl call.

povlp

Specifies the pointer to the optional OVERLAPPED structure. WinpkFilter does not use overlapped I/O, so this parameter should be always NULL.

Remarks:

This member is a simple wrapper for Win32 DeviceIoControl function.


CNdisApi::FlushAdapterPacketQueue

BOOL FlushAdapterPacketQueue ( HANDLE hAdapter );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hAdapter

Adapter handle obtained via call to GetTcpipBoundAdaptersInfo.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_FLUSH_ADAPTER_QUEUE. Helper driver will flush packet queue for the requested interface on this request.


CNdisApi::GetAdapterMode

BOOL GetAdapterMode ( PADAPTER_MODE pMode );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pMode

Pointer to the user allocated and initialized ADAPTER_MODE structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_ADAPTER_MODE. For this call the following field of ADAPTER_MODE must be initialized:

  • ADAPTER_MODE.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo).

As a result of this call driver fills the field of ADAPTER_MODE below:

  • ADAPTER_MODE.dwFlags must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:
    • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
    • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
    • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
    • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

    Version 2.0 of WinpkFilter has added three new flags:

    • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

    By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

    • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
    • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.


CNdisApi::GetAdapterPacketQueueSize

BOOL GetAdapterPacketQueueSize ( HANDLE hAdapter, PDWORD pdwSize);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hAdapter

Adapter handle obtained via call to GetTcpipBoundAdaptersInfo.

pdwSize

Pointer to the DWORD variable to store the current adapters packet queue size.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_ADAPTER_QUEUE_SIZE. Helper driver will return packet queue size for the requested interface on this request.


CNdisApi::GetAdaptersStartupMode

static DWORD GetAdaptersStartupMode();

Return Value:

Current default mode value applied to each adapter when it appears in the system.

Parameters:

None

Remarks:

Note that if you have not rebooted after calling SetAdaptersStartupMode the return value in meaningless.


CNdisApi::GetBytesReturned

DWORD GetBytesReturned ();

Return Value:

Returns number of bytes returned by the latest call to CNdisApi::DeviceIoControl

Parameters:

None

Remarks:

None


CNdisApi::GetHwPacketFilter

BOOL GetHwPacketFilter ( HANDLE hAdapter, PDWORD pFilter );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hAdapter

Specifies adapter handle.

Filter

Specifies pointer to the user allocated variable to save current hardware packet filter..

Remarks:

This function gets a hardware filter on the incoming packets. The constants that define the filters are declared in the file ntddndis.h. The input parameters are the adapter on which the filter must be defined, and the pointer to the variable to save current filter. Here is a list of the most useful filters:

  • NDIS_PACKET_TYPE_PROMISCUOUS: sets the promiscuous mode. Every incoming packet is accepted by the adapter.
  • NDIS_PACKET_TYPE_DIRECTED: only packets directed to the workstation's adapter are accepted.
  • NDIS_PACKET_TYPE_BROADCAST: only the broadcast packets are accepted.
  • NDIS_PACKET_TYPE_MULTICAST: only the multicast packets belonging to the groups of which this adapter is a member are accepted.
  • NDIS_PACKET_TYPE_ALL_MULTICAST: every multicast packet is accepted.
  • NDIS_PACKET_TYPE_ALL_LOCAL: all local packets, i.e. NDIS_PACKET_TYPE_DIRECTED + NDIS_PACKET_TYPE_BROADCAST + NDIS_PACKET_TYPE_MULTICAST


CNdisApi::GetMTUDecrement

static DWORD GetMTUDecrement ();

Return Value:

Current system wide MTU decrement

Parameters:

None

Remarks:

Note that if you have not rebooted after calling SetMTUDecrement the return value in meaningless.


CNdisApi::GetPacketFilterTable

BOOL GetPacketFilterTable ( PSTATIC_FILTER_TABLE pFilterList);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pFilterList

Pointer to STATIC_FILTER_TABLE.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_PACKET_FILTERS. You should allocate STATIC_FILTER_TABLE structure large enough to fit the one loaded into WinpkFilter driver. You can get the number of entries in the STATIC_FILTER_TABLE.m_TableSize using the GetPacketFilterTableSize API call.


CNdisApi::GetPacketFilterTableResetStats

BOOL GetPacketFilterTableResetStats ( PSTATIC_FILTER_TABLE pFilterList);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pFilterList

Pointer to STATIC_FILTER_TABLE.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_PACKET_FILTERS_RESET_STATS. You should allocate STATIC_FILTER_TABLE structure large enough to fit the one loaded into WinpkFilter driver. You can get the number of entries in the STATIC_FILTER_TABLE.m_TableSize using the GetPacketFilterTableSize API call. Basically this API does the same as GetPacketFilterTable but also resets packets and bytes counters.


CNdisApi::GetPacketFilterTableSize

BOOL GetPacketFilterTableSize ( DWORD pdwTableSize);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pdwTableSize

Pointer to DWORD which receives the number of filters in the STATIC_FILTER_TABLE loaded into the WinpkFilter driver.

Remarks:

This member is a wrapper for IOCTL_NDISRD_GET_PACKET_FILTERS_TABLESIZE.


CNdisApi::GetRasLinks

BOOL GetRasLinks ( HANDLE hAdapter, PRAS_LINKS pLinks );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hAdapter

Specifies WAN interface handle.

pLinks

Pointer to the user allocated RAS_LINKS structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_RAS_LINKS. Helper driver fills _RAS_LINKS with information about active WAN connections.


CNdisApi::GetTcpipBoundAdaptersInfo

BOOL GetTcpipBoundAdaptersInfo ( PTCP_AdapterList pAdapters );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pAdapters

Pointer to the user allocated TCP_AdapterList structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_TCPIP_INTERFACES. Helper driver will fill TCP_AdapterList with MSTCP associated interfaces information (permanent and current MAC's, MTU, internal interface name, medium and handle required for calling any adapter associated services).


CNdisApi::GetVersion

ULONG GetVersion ();

Return Value:

Function returns version of current helper driver.

Parameters:

None

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_VERSION.


CNdisApi::IsDriverLoaded

BOOL IsDriverLoaded ();

Return Value:

Returns TRUE if helper driver is loaded and was successfully opened, FALSE otherwise

Parameters:

None

Remarks:

None


CNdisApi::NdisrdRequest

BOOL NdisrdRequest ( PPACKET_OID_DATA OidData, BOOL Set );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

OidData

Specifies the pointer to the user allocated and initialized _PACKET_OID_DATA structure.

Set

Specifies if the operation is a set (set=TRUE) or a query (set=FALSE).

Remarks:

This function is used to perform a query/set operation on the adapter pointed by OidData.hAdapterHandle. With this function it is possible to obtain or define various parameters of the network adapter, like the dimension of the internal buffers, the link speed or the counter of corrupted packets.The constants that define the operations are declared in the file ntddndis.h. More details on the argument can be found in the documentation provided with the Microsoft DDK.

NOTE: not all the network adapters implement all the query/set functions. There is a set of mandatory OID functions that is granted to be present on all the adapters, and a set of facultative functions, not provided by all the adapters (see the DDKs to see which functions are mandatory). If you use a facultative function, be careful to enclose it in an if statement to check the result.


CNdisApi::ReadPacket

BOOL ReadPacket ( PETH_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pPacket

Pointer to the user allocated and initialized ETH_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_READ_PACKET. For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo). The packet will be extracted from the network interface associated packet queue. Remember that packets queued only when network interface in the filtering of listening mode.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER are initialized by helper driver in case of success:

  • INTERMEDIATE_BUFFER.m_IBuffer contains Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length contains the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags is a combination of NDIS_FLAGS_XXX (defined in ndis.h). These flags are copied from the NDIS_PACKET.Private.Flags.
  • INTERMEDIATE_BUFFER.m_dwDeviceFlags is PACKET_FLAG_ON_SEND if packet goes from MSTCP to network interface or PACKET_FLAG_ON_RECEIVE otherwise.


CNdisApi::ReadPackets

BOOL ReadPackets ( PETH_M_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pPacket

Pointer to the user allocated and initialized ETH_M_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_READ_PACKETS. For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo). The packets will be extracted from the network interface associated packet queue. Remember that packets queued only when network interface in the filtering of listening mode.
  • ETH_M_REQUEST.dwPacketsNumber must be set to a number of entries in EthPacket array
  • ETH_M_REQUEST.EthPacket[i].Buffer must point to the user allocated INTERMEDIATE_BUFFER structure

The following fields of the ETH_M_REQUEST and INTERMEDIATE_BUFFER are initialized by helper driver in case of success:

  • ETH_M_REQUEST.dwPacketSuccess contains number of packets returned by driver
  • INTERMEDIATE_BUFFER.m_IBuffer contains Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length contains the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags is a combination of NDIS_FLAGS_XXX (defined in ndis.h). These flags are copied from the NDIS_PACKET.Private.Flags.
  • INTERMEDIATE_BUFFER.m_dwDeviceFlags is PACKET_FLAG_ON_SEND if packet goes from MSTCP to network interface or PACKET_FLAG_ON_RECEIVE otherwise.


CNdisApi::ResetPacketFilterTable

BOOL ResetPacketFilterTable ( );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

NONE

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_RESET_PACKET_FILTERS. ResetPacketFilterTable removes filters from WinpkFilter driver.


CNdisApi::SendPacketsToAdapter

BOOL SendPacketsToAdapter ( PETH_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pPacket

Pointer to the user allocated and initialized ETH_M_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKETS_TO_ADAPTER. For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) to which you would like to send packets.
  • ETH_M_REQUEST.dwPacketsNumber must be set to the number of initialized NDISRD_ETH_Packet structures in EthPacket array
  • ETH_M_REQUEST.EthPacket[].Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags should be initialized by combination of NDIS_FLAGS_XXX (defined in ndis.h). Look at these flags for details. Note, that these flags usually don't work for the old NDIS versions.


CNdisApi::SendPacketsToMstcp

BOOL SendPacketsToMstcp ( PETH_M_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pPacket

Pointer to the user allocated and initialized ETH_M_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKETS_TO_MSTCP. For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) from which you would like to simulate receive.
  • ETH_M_REQUEST.dwPacketsNumber must be set to the number of initialized NDISRD_ETH_Packet structures in EthPacket array
  • ETH_M_REQUEST.EthPacket[].Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet


CNdisApi::SendPacketToMstcp

BOOL SendPacketToMstcp ( PETH_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pPacket

Pointer to the user allocated and initialized ETH_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKET_TO_MSTCP. For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) from which you would like to simulate receive.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet


CNdisApi::SendPacketToAdapter

BOOL SendPacketToAdapter ( PETH_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pPacket

Pointer to the user allocated and initialized ETH_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKET_TO_ADAPTER. For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) to which you would like to send packet.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags should be initialized by combination of NDIS_FLAGS_XXX (defined in ndis.h). Look at these flags for details. Note, that these flags usually don't work for the old NDIS versions.


CNdisApi::SetAdapterMode

BOOL SetAdapterMode ( PADAPTER_MODE pMode );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pMode

Pointer to the user allocated and initialized ADAPTER_MODE structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_ADAPTER_MODE. For this call the following fields of ADAPTER_MODE must be initialized:

  • ADAPTER_MODE.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo).
  • ADAPTER_MODE.dwFlags must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:
    • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
    • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
    • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
    • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

    Version 2.0 of WinpkFilter has added three new flags:

    • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

    By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

    • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
    • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.


CNdisApi::SetAdapterListChangeEvent

BOOL SetAdapterListChangeEvent ( HANDLE hEvent );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hEvent

Handle to user created Win32 event. Set it to NULL if you want to release event.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_ADAPTER_EVENT. User application should create Win32 event (with CreateEvent API call) and pass the event handle to this function. Helper driver will signal this event when TCP/IP bound adapter's list changes (an example this happens on plug/unplug network card, disable/enable network connection or etc.). Usually you should call GetTcpipBoundAdaptersInfo and renew your adapter associated structures on this event.


CNdisApi::SetAdaptersStartupMode

static BOOL SetAdaptersStartupMode ( DWORD dwAdaptersStartupMode );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

dwAdaptersStartupMode - must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:

  • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
  • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
  • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
  • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

Version 2.3 of WinpkFilter has added three new flags:

  • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

  • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
  • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.

Remarks:

This routine sets the default mode to be applied on the each adapter when it appears in the system.. It can be useful when you need to prevent network interface to start operating before your application has started. Important note, this API call requires a system reboot to take effect.


CNdisApi::SetHwPacketFilter

BOOL SetHwPacketFilter ( HANDLE hAdapter, DWORD Filter );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hAdapter

Specifies adapter handle.

Filter

Specifies hardware filter value.

Remarks:

This function sets a hardware filter on the incoming packets. The constants that define the filters are declared in the file ntddndis.h. The input parameters are the adapter on which the filter must be defined, and the identifier of the filter. Here is a list of the most useful filters:

  • NDIS_PACKET_TYPE_PROMISCUOUS: sets the promiscuous mode. Every incoming packet is accepted by the adapter.
  • NDIS_PACKET_TYPE_DIRECTED: only packets directed to the workstation's adapter are accepted.
  • NDIS_PACKET_TYPE_BROADCAST: only the broadcast packets are accepted.
  • NDIS_PACKET_TYPE_MULTICAST: only the multicast packets belonging to the groups of which this adapter is a member are accepted.
  • NDIS_PACKET_TYPE_ALL_MULTICAST: every multicast packet is accepted.
  • NDIS_PACKET_TYPE_ALL_LOCAL: all local packets, i.e. NDIS_PACKET_TYPE_DIRECTED + NDIS_PACKET_TYPE_BROADCAST + NDIS_PACKET_TYPE_MULTICAST


CNdisApi::SetMTUDecrement

static BOOL SetMTUDecrement ( DWORD dwMTUDecrement );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

dwMTUDecrement

System wide MTU decrement value to set.

Remarks:

Some network applications need to insert additional headers into the packet. The examples of these applications are IP in IP tunneling, IPSEC based VPNs and etc. This function sets the parameter in the registry key which helper driver reads during it's initialization and subtracts it's value from the real MTU when MSTCP requests it from the network, so this API call requires a system reboot to take effect.


CNdisApi::SetPacketFilterTable

BOOL SetPacketFilterTable ( PSTATIC_FILTER_TABLE pFilterList);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

pFilterList

Pointer to STATIC_FILTER_TABLE to set for WinpkFilter driver.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_PACKET_FILTERS. You should allocate and initialize STATIC_FILTER_TABLE structure before passing iot to the driver. STATIC_FILTER_TABLE.m_TableSize should be set to number of entries in STATIC_FILTER_TABLE.m_StaticFilters. Filters are applied in their order m_StaticFilters array. Only one table can be loaded into the WinpkFilter driver.


CNdisApi::SetPacketEvent

BOOL SetPacketEvent ( HANDLE hAdapter, HANDLE hEvent );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hAdapter

Adapter handle to associate event with.

hEvent

Handle to user created Win32 event. Set it to NULL if you want to release event.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_EVENT. User application should create Win32 event (with CreateEvent API call) and pass adapter handle and event handle to this function. Helper driver will signal this event when adapter associated packet queue is non-empty.


CNdisApi::SetWANEvent

BOOL SetWANEvent ( HANDLE hEvent );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hEvent

Handle to user created Win32 event. Set it to NULL if you want to release event.

Remarks:

This routine is a simple wrapper for IOCTL_NDISRD_SET_WAN_EVENT. User application should create Win32 event (with CreateEvent API call) and pass event handle to this function. Helper driver will signal this event when WAN (dial-up, DSL, ADSL or etc.) connection is established or terminated.


C Interface

NDISAPI.DLL exports the set of functions, which hides platform dependent details from end user and implements some helper routines. This section describes these routines in details.

Functions:

OpenFilterDriver

CloseFilterDriver

GetVersion

GetTcpipBoundAdaptersInfo

SendPacketToMstcp

SendPacketToAdapter

ReadPacket

SendPacketsToMstcp

SendPacketsToAdapter

ReadPackets

SetAdapterMode

FlushAdapterPacketQueue

GetAdapterPacketQueueSize

SetPacketEvent

NdisrdRequest

GetRasLinks

SetHwPacketFilter

GetHwPacketFilter

SetMTUDecrement

GetMTUDecrement

GetAdaptersStartupMode

SetAdaptersStartupMode

ConvertWindowsNTAdapterName

ConvertWindows2000AdapterName

ConvertWindows9xAdapterName

IsDriverLoaded

GetBytesReturned

SetPacketFilterTable

ResetPacketFilterTable

GetPacketFilterTableSize

GetPacketFilterTable

GetPacketFilterTableResetStats


CloseFilterDriver

VOID CloseFilterDriver( HANDLE hOpen );

Return Value:

None

Parameters:

hOpen

Specifies driver object handle.

Remarks:

This function closes driver object handle returned from the OpenDriverObject function.


FlushAdapterPacketQueue

BOOL FlushAdapterPacketQueue ( HANDLE hOpen, HANDLE hAdapter );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hAdapter

Adapter handle obtained via call to GetTcpipBoundAdaptersInfo.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_FLUSH_ADAPTER_QUEUE. Helper driver will flush packet queue for the requested interface on this request.


GetAdapterMode

BOOL GetAdapterMode ( HANDLE hOpen, PADAPTER_MODE pMode );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pMode

Pointer to the user allocated and initialized ADAPTER_MODE structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_ADAPTER_MODE. For this call the following field of ADAPTER_MODE must be initialized:

  • ADAPTER_MODE.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo).

As a result of this call driver fills the field of ADAPTER_MODE below:

  • ADAPTER_MODE.dwFlags must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:
    • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
    • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
    • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
    • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

    Version 2.3 of WinpkFilter has added three new flags:

    • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

    By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

    • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
    • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.


GetAdapterPacketQueueSize

BOOL GetAdapterPacketQueueSize ( HANDLE hOpen, HANDLE hAdapter, PDWORD pdwSize);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hAdapter

Adapter handle obtained via call to GetTcpipBoundAdaptersInfo.

pdwSize

Pointer to the DWORD variable to store the current adapters packet queue size.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_ADAPTER_QUEUE_SIZE. Helper driver will return packet queue size for the requested interface on this request.


GetAdaptersStartupMode

DWORD GetAdaptersStartupMode();

Return Value:

Current default mode value applied to each adapter when it appears in the system.

Parameters:

None

Remarks:

Note that if you have not rebooted after calling SetAdaptersStartupMode the return value in meaningless.


GetBytesReturned

DWORD GetBytesReturned ( HANDLE hOpen );

Return Value:

Returns number of bytes returned by the latest call to driver.

Parameters:

hOpen

Specifies driver object open handle.

Remarks:

None


GetDriverVersion

Windows Packet Filter Kit: Wrapper DLL C Interface

GetVersion

ULONG GetDriverVersion ( HANDLE hOpen );

Return Value:

Function returns version of current helper driver.

Parameters:

hOpen

Specifies driver object open handle.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_VERSION.


GetMTUDecrement

DWORD GetMTUDecrement ();

Return Value:

Current system wide MTU decrement

Parameters:

None

Remarks:

Note that if you have not rebooted after calling SetMTUDecrement the return value in meaningless.


GetHwPacketFilter

BOOL GetHwPacketFilter ( HANDLE hOpen, HANDLE hAdapter, PDWORD pFilter );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hAdapter

Specifies adapter handle.

Filter

Specifies pointer to the user allocated variable to save current hardware packet filter..

Remarks:

This function gets a hardware filter on the incoming packets. The constants that define the filters are declared in the file ntddndis.h. The input parameters are the adapter on which the filter must be defined, and the pointer to the variable to save current filter. Here is a list of the most useful filters:

  • NDIS_PACKET_TYPE_PROMISCUOUS: sets the promiscuous mode. Every incoming packet is accepted by the adapter.
  • NDIS_PACKET_TYPE_DIRECTED: only packets directed to the workstation's adapter are accepted.
  • NDIS_PACKET_TYPE_BROADCAST: only the broadcast packets are accepted.
  • NDIS_PACKET_TYPE_MULTICAST: only the multicast packets belonging to the groups of which this adapter is a member are accepted.
  • NDIS_PACKET_TYPE_ALL_MULTICAST: every multicast packet is accepted.
  • NDIS_PACKET_TYPE_ALL_LOCAL: all local packets, i.e. NDIS_PACKET_TYPE_DIRECTED + NDIS_PACKET_TYPE_BROADCAST + NDIS_PACKET_TYPE_MULTICAST


CNdisApi::GetPacketFilterTableResetStats

Windows Packet Filter Kit: Wrapper DLL C Interface

GetPacketFilterTableResetStats

BOOL GetPacketFilterTableResetStats ( HANDLE hOpen, PSTATIC_FILTER_TABLE pFilterList);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pFilterList

Pointer to STATIC_FILTER_TABLE.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_PACKET_FILTERS_RESET_STATS. You should allocate STATIC_FILTER_TABLE structure large enough to fit the one loaded into WinpkFilter driver. You can get the number of entries in the STATIC_FILTER_TABLE.m_TableSize using the GetPacketFilterTableSize API call. Basically this API does the same as GetPacketFilterTable but also resets packets and bytes counters.


CNdisApi::GetPacketFilterTable

Windows Packet Filter Kit: Wrapper DLL C Interface

GetPacketFilterTable

BOOL GetPacketFilterTable ( HANDLE hOpen, PSTATIC_FILTER_TABLE pFilterList);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pFilterList

Pointer to STATIC_FILTER_TABLE.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_PACKET_FILTERS. You should allocate STATIC_FILTER_TABLE structure large enough to fit the one loaded into WinpkFilter driver. You can get the number of entries in the STATIC_FILTER_TABLE.m_TableSize using the GetPacketFilterTableSize API call.


CNdisApi::GetPacketFilterTableSize

Windows Packet Filter Kit: Wrapper DLL C Interface

GetPacketFilterTableSize

BOOL GetPacketFilterTableSize ( HANDLE hOpen, DWORD pdwTableSize);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle

pdwTableSize

Pointer to DWORD which receives the number of filters in the STATIC_FILTER_TABLE loaded into the WinpkFilter driver.

Remarks:

This member is a wrapper for IOCTL_NDISRD_GET_PACKET_FILTERS_TABLESIZE.


Windows Packet Filter Kit: Wrapper DLL C Interface

GetRasLinks

BOOL GetRasLinks ( HANDLE hOpen, HANDLE hAdapter, PRAS_LINKS pLinks );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hAdapter

Specifies WAN interface handle.

pLinks

Pointer to the user allocated RAS_LINKS structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_RAS_LINKS.Helper driver fills _RAS_LINKS with information about active WAN connections.


GetTcpipBoundAdaptersInfo

BOOL GetTcpipBoundAdaptersInfo ( HANDLE hOpen, PTCP_AdapterList pAdapters );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pAdapters

Pointer to the user allocated TCP_AdapterList structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_GET_TCPIP_INTERFACES. Helper driver will fill TCP_AdapterList with MSTCP associated interfaces information (permanent and current MAC's, MTU, internal interface name, medium and handle required for calling any adapter associated services).


IsDriverLoaded

BOOL IsDriverLoaded ( HANDLE hOpen );

Return Value:

Returns TRUE if helper driver is loaded and was successfully opened, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

Remarks:

None


NdisrdRequest

BOOL NdisrdRequest ( HANDLE hOpen, PPACKET_OID_DATA OidData, BOOL Set );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

OidData

Specifies the pointer to the user allocated and initialized _PACKET_OID_DATA structure.

Set

Specifies if the operation is a set (set=TRUE) or a query (set=FALSE).

Remarks:

This function is used to perform a query/set operation on the adapter pointed by OidData.hAdapterHandle. With this function it is possible to obtain or define various parameters of the network adapter, like the dimension of the internal buffers, the link speed or the counter of corrupted packets.The constants that define the operations are declared in the file ntddndis.h. More details on the argument can be found in the documentation provided with the Microsoft DDK.

NOTE: not all the network adapters implement all the query/set functions. There is a set of mandatory OID functions that is granted to be present on all the adapters, and a set of facultative functions, not provided by all the adapters (see the DDKs to see which functions are mandatory). If you use a facultative function, be careful to enclose it in an if statement to check the result.


OpenFilterDriver

HANDLE OpenFilterDriver( LPCSTR szDriverName = "NDISRD");

Return Value:

This function opens driver object and returnes handle to it.

Parameters:

szDriverName

Specifies driver object name.

Remarks:

C/C++ definition of this function has default parameter, which is equal to "NDISRD". For the Delphi and other programming languages you should specify this parameter explicitly.


ReadPacket

BOOL ReadPacket ( HANDLE hOpen, PETH_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pPacket

Pointer to the user allocated and initialized ETH_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_READ_PACKET. For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo). The packet will be extracted from the network interface associated packet queue. Remember that packets queued only when network interface in the filtering of listening mode.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER are initialized by helper driver in case of success:

  • INTERMEDIATE_BUFFER.m_IBuffer contains Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length contains the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags is a combination of NDIS_FLAGS_XXX (defined in ndis.h). These flags are copied from the NDIS_PACKET.Private.Flags.
  • INTERMEDIATE_BUFFER.m_dwDeviceFlags is PACKET_FLAG_ON_SEND if packet goes from MSTCP to network interface or PACKET_FLAG_ON_RECEIVE otherwise.


ReadPackets

BOOL ReadPackets ( HANDLE hOpen, PETH_M_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pPacket

Pointer to the user allocated and initialized ETH_M_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_READ_PACKETS. For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo). The packets will be extracted from the network interface associated packet queue. Remember that packets queued only when network interface in the filtering of listening mode.
  • ETH_M_REQUEST.dwPacketsNumber must be set to a number of entries in EthPacket array
  • ETH_M_REQUEST.EthPacket[i].Buffer must point to the user allocated INTERMEDIATE_BUFFER structure

The following fields of the ETH_M_REQUEST and INTERMEDIATE_BUFFER are initialized by helper driver in case of success:

  • ETH_M_REQUEST.dwPacketSuccess contains number of packets returned by driver
  • INTERMEDIATE_BUFFER.m_IBuffer contains Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length contains the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags is a combination of NDIS_FLAGS_XXX (defined in ndis.h). These flags are copied from the NDIS_PACKET.Private.Flags.
  • INTERMEDIATE_BUFFER.m_dwDeviceFlags is PACKET_FLAG_ON_SEND if packet goes from MSTCP to network interface or PACKET_FLAG_ON_RECEIVE otherwise.


CNdisApi::ResetPacketFilterTable

Windows Packet Filter Kit: Wrapper DLL C Interface

ResetPacketFilterTable

BOOL ResetPacketFilterTable ( HANDLE hOpen );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_RESET_PACKET_FILTERS. ResetPacketFilterTable removes filters from WinpkFilter driver.


SendPacketsToAdapter

BOOL SendPacketsToAdapter ( HANDLE hOpen, PETH_M_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pPacket

Pointer to the user allocated and initialized ETH_M_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKETS_TO_ADAPTER. For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) to which you would like to send packets.
  • ETH_M_REQUEST.dwPacketsNumber must be set to the number of initialized NDISRD_ETH_Packet structures in EthPacket array
  • ETH_M_REQUEST.EthPacket[].Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags should be initialized by combination of NDIS_FLAGS_XXX (defined in ndis.h). Look at these flags for details. Note, that these flags usually don't work for the old NDIS versions.


SendPacketsToMstcp

BOOL SendPacketsToMstcp ( HANDLE hOpen, PETH_M_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pPacket

Pointer to the user allocated and initialized ETH_M_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKETS_TO_MSTCP. For this call the following fields of ETH_M_REQUEST must be initialized:

  • ETH_M_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) from which you would like to simulate receive.
  • ETH_M_REQUEST.dwPacketsNumber must be set to the number of initialized NDISRD_ETH_Packet structures in EthPacket array
  • ETH_M_REQUEST.EthPacket[].Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet


SendPacketToAdapter

BOOL SendPacketToAdapter ( HANDLE hOpen, PETH_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pPacket

Pointer to the user allocated and initialized ETH_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKET_TO_ADAPTER. For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) to which you would like to send packet.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet
  • INTERMEDIATE_BUFFER.m_Flags should be initialized by combination of NDIS_FLAGS_XXX (defined in ndis.h). Look at these flags for details. Note, that these flags usually don't work for the old NDIS versions.


SendPacketToMstcp

BOOL SendPacketToMstcp ( HANDLE hOpen, PETH_REQUEST pPacket );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pPacket

Pointer to the user allocated and initialized ETH_REQUEST structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SEND_PACKET_TO_MSTCP. For this call the following fields of ETH_REQUEST must be initialized:

  • ETH_REQUEST.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo) from which you would like to simulate receive.
  • ETH_REQUEST.EthPacket.Buffer must point to the user allocated and initialized INTERMEDIATE_BUFFER structure

The following fields of the INTERMEDIATE_BUFFER should be initialized:

  • INTERMEDIATE_BUFFER.m_IBuffer should contain Ethernet packet
  • INTERMEDIATE_BUFFER.m_Length should be initialized to the actual length of the packet


SetAdapterListChangeEvent

BOOL SetAdapterListChangeEvent ( HANDLE hOpen, HANDLE hEvent );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hEvent

Handle to user created Win32 event. Set it to NULL if you want to release event.

Remarks:

This routine is a simple wrapper for IOCTL_NDISRD_SET_ADAPTER_EVENT. User application should create Win32 event (with CreateEvent API call) and pass the event handle to this function. Helper driver will signal this event when TCP/IP bound adapter's list changes (an example this happens on plug/unplug network card, disable/enable network connection or etc.). Usually you should call GetTcpipBoundAdaptersInfo and renew your adapter associated structures on this event.


SetAdapterMode

BOOL SetAdapterMode ( HANDLE hOpen, PADAPTER_MODE pMode );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pMode

Pointer to the user allocated and initialized ADAPTER_MODE structure.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_ADAPTER_MODE. For this call the following fields of ADAPTER_MODE must be initialized:

  • ADAPTER_MODE.hAdapterHandle must be set to the interface handle (obtained via call to CNdisApi::GetTcpipBoundAdaptersInfo).
  • ADAPTER_MODE.dwFlags must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:
    • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
    • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
    • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
    • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

    Version 2.3 of WinpkFilter has added three new flags:

    • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

    By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

    • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
    • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.


SetAdaptersStartupMode

BOOL SetAdaptersStartupMode ( DWORD dwAdaptersStartupMode );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

dwAdaptersStartupMode - must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:

  • MSTCP_FLAG_SENT_TUNNEL - queue all packets sent from MSTCP to network interface. Original packet dropped.
  • MSTCP_FLAG_RECV_TUNNEL - queue all packets indicated by network interface to MSTCP. Original packet dropped.
  • MSTCP_FLAG_SENT_LISTEN - queue all packets sent from MSTCP to network interface. Original packet goes ahead.
  • MSTCP_FLAG_RECV_LISTEN - queue all packets indicated by network interface to MSTCP. Original packet goes ahead.

Version 2.3 of WinpkFilter has added three new flags:

  • MSTCP_FLAG_FILTER_DIRECT - In promiscuous mode TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets, to prevent this set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and network interface current MAC will never reach MSTCP.

By default loopback packets are passed to original MSTCP handlers without processing, to change this behavior use the flags below:

  • MSTCP_FLAG_LOOPBACK_FILTER - Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
  • MSTCP_FLAG_LOOPBACK_BLOCK - Silently drop loopback packets, this flag is recommended for usage in combination with promiscuous mode to avoid multiply processing of one packet.

Remarks:

This routine sets the default mode to be applied on the each adapter when it appears in the system.. It can be useful when you need to prevent network interface to start operating before your application has started. Important note, this API call requires a system reboot to take effect.


SetHwPacketFilter

BOOL SetHwPacketFilter ( HANDLE hOpen, HANDLE hAdapter, DWORD Filter );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hAdapter

Specifies adapter handle.

Filter

Specifies hardware filter value.

Remarks:

This function sets a hardware filter on the incoming packets. The constants that define the filters are declared in the file ntddndis.h. The input parameters are the adapter on which the filter must be defined, and the identifier of the filter. Here is a list of the most useful filters:

  • NDIS_PACKET_TYPE_PROMISCUOUS: sets the promiscuous mode. Every incoming packet is accepted by the adapter.
  • NDIS_PACKET_TYPE_DIRECTED: only packets directed to the workstation's adapter are accepted.
  • NDIS_PACKET_TYPE_BROADCAST: only the broadcast packets are accepted.
  • NDIS_PACKET_TYPE_MULTICAST: only the multicast packets belonging to the groups of which this adapter is a member are accepted.
  • NDIS_PACKET_TYPE_ALL_MULTICAST: every multicast packet is accepted.
  • NDIS_PACKET_TYPE_ALL_LOCAL: all local packets, i.e. NDIS_PACKET_TYPE_DIRECTED + NDIS_PACKET_TYPE_BROADCAST + NDIS_PACKET_TYPE_MULTICAST


SetMTUDecrement

BOOL SetMTUDecrement ( DWORD dwMTUDecrement );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

dwMTUDecrement

System wide MTU decrement value to set.

Remarks:

Some network applications need to insert additional headers into the packet. The examples of these applications are IP in IP tunneling, IPSEC based VPNs and etc. This function sets the parameter in the registry key which helper driver reads during it's initialization and subtracts it's value from the real MTU when MSTCP requests it from the network, so this API call requires a system reboot to take effect.


CNdisApi::SetPacketFilterTable

Windows Packet Filter Kit: Wrapper DLL C Interface

SetPacketFilterTable

BOOL SetPacketFilterTable (HANDLE hOpen, PSTATIC_FILTER_TABLE pFilterList);

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

pFilterList

Pointer to STATIC_FILTER_TABLE to set for WinpkFilter driver.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_PACKET_FILTERS. You should allocate and initialize STATIC_FILTER_TABLE structure before passing iot to the driver. STATIC_FILTER_TABLE.m_TableSize should be set to number of entries in STATIC_FILTER_TABLE.m_StaticFilters. Filters are applied in their order m_StaticFilters array. Only one table can be loaded into the WinpkFilter driver.


SetPacketEvent

BOOL SetPacketEvent ( HANDLE hOpen, HANDLE hAdapter, HANDLE hEvent );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hAdapter

Adapter handle to associate event with.

hEvent

Handle to user created Win32 event. Set it to NULL if you want to release event.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_EVENT. User application should create Win32 event (with CreateEvent API call) and pass adapter handle and event handle to this function. Helper driver will signal this event when adapter associated packet queue is non-empty.


SetWANEvent

BOOL SetWANEvent ( HANDLE hOpen, HANDLE hEvent );

Return Value:

TRUE if call was successful, FALSE otherwise

Parameters:

hOpen

Specifies driver object open handle.

hEvent

Handle to user created Win32 event. Set it to NULL if you want to release event.

Remarks:

This member is a simple wrapper for IOCTL_NDISRD_SET_WAN_EVENT. User application should create Win32 event (with CreateEvent API call) and pass event handle to this function. Helper driver will signal this event when WAN (dial-up, DSL, ADSL or etc.) connection is established or terminated.


WinpkFilter structures

WinpkFilter framework defines a small set of structures for exchange with helper driver. These structures defined in common.h, here is each of them described shortly.

_TCP_AdapterList

_INTERMEDIATE_BUFFER

_NDISRD_ETH_Packet

_ETH_REQUEST

_ADAPTER_MODE

_ADAPTER_EVENT

_STATIC_FILTER_TABLE


_ADAPTER_EVENT

struct _ADAPTER_EVENT
{
    HANDLE		hAdapterHandle;
    HANDLE		hEvent;
}

hAdapterHandle

The adapters handle value.

hEvent

Win32 event handle or NULL if you want to release event. For Windows 9x/ME it should be Ring0 handle. To convert Ring3 handle use OpenVxDHandle call from kernel32.dll.


_ADAPTER_MODE

struct _ADAPTER_MODE
{
    HANDLE		hAdapterHandle;
    unsigned long	dwFlags;
}

hAdapterHandle

The adapters handle value.

dwFlags

This field must be a combination of the filter and/or listen flags (MSTCP_FLAG_SENT_TUNNEL, MSTCP_FLAG_RECV_TUNNEL, MSTCP_FLAG_SENT_LISTEN, MSTCP_FLAG_RECV_LISTEN, MSTCP_FLAG_FILTER_DIRECT, MSTCP_FLAG_LOOPBACK_FILTER, MSTCP_FLAG_LOOPBACK_BLOCK).


_DATA_LINK_LAYER_FILTER

struct _DATA_LINK_LAYER_FILTER
{
     unsigned long m_dwUnionSelector;
     union
     {
          ETH_802_3_FILTER m_Eth8023Filter;
     };
}

This structure represents data link layer (OSI-7) filter.

m_dwUnionSelector

Specifies which of the union members below is valid. Currently only Ethernet 802.3 is supported and this field should be laways set to ETH_802_3.

m_Eth8023Filter

Ethernet 802.3 filter


_ETH_802_3_FILTER

struct _ETH_802_3_FILTER
{
      unsigned long     m_ValidFields;
      unsigned char     m_SrcAddress[ETHER_ADDR_LENGTH];
      unsigned char     m_DestAddress[ETHER_ADDR_LENGTH];
      unsigned short    m_Protocol;
}

m_ValidFields

Specifies which of the fileds below contain valid values and should be matched against the packet. Must be a combination of the following flags: ETH_802_3_SRC_ADDRESS, ETH_802_3_DEST_ADDRESS, ETH_802_3_PROTOCOL

m_SrcAddress

Source MAC address

m_DestAddress

Destination MAC address

m_Protocol

Next Protocol (Ethernet type)


_ETH_M_REQUEST

struct _ETH_M_REQUEST
{
    HANDLE    		hAdapterHandle;
     unsigned   		dwPacketsNumber;
     unsigned   		dwPacketsSuccess;
     NDISRD_ETH_Packet 	EthPacket[ANY_SIZE];
}

hAdapterHandle

The adapters handle value. This structure is used for sending receiving packets and this field specifies network interface for the operation.

dwPacketsNumber

Number of buffers in EthPacket array

dwPacketsSuccess

Number of buffers successfully returned from read operation

EthPacket

This field keeps an array of pointers to the _INTERMEDIATE_BUFFER.


_ETH_REQUEST

struct _ETH_REQUEST
{
    HANDLE			hAdapterHandle;
    NDISRD_ETH_Packet	EthPacket;
}

hAdapterHandle

The adapters handle value. This structure is used for sending receiving packets and this field specifies network interface for the operation.

EthPacket

This field keeps a pointer to the _INTERMEDIATE_BUFFER.

>iv class=footer align="center">Copyright NT Kernel Resources © 2000-2013


_INTERMEDIATE_BUFFER

struct _INTERMEDIATE_BUFFER
{
    LIST_ENTRY		m_qLink;
    ULONG			m_dwDeviceFlags;
    ULONG			m_Length;
    ULONG			m_Flags; // NDIS_PACKET flags
    ULONG			m_8021q; // 802.1q info
    UCHAR			m_IBuffer [MAX_ETHER_FRAME];
}

m_qLink

Used by helper driver internally. Feel free to use this field on your own.

m_dwDeviceFlags

This field must be a PACKET_FLAG_ON_SEND if packet was intercepted from MSTCP or PACKET_FLAG_ON_RECEIVE if packet was intercepted from the network interface.

m_Length

The length of the packet in the m_IBuffer.

m_Flags

This field can be a combination of the NDIS_FLAGS_XXX (defined in ndis.h)

m_8021q

802.1q VLAN Tag

m_IBuffer

This field contains the raw Ethernet packet.


_IP_ADDRESS_V4

struct _IP_ADDRESS_V4
{
     unsigned long m_AddressType;
     union
     {
          IP_SUBNET_V4  m_IpSubnet;
          IP_RANGE_V4  m_IpRange;
     };
}

m_AddressType

Specifies which of the IP v4 address types is used below. Must be set to IP_SUBNET_V4_TYPE or IP_RANGE_V4_TYPE

m_IpSubnet

IPv4 address expressed as subnet

m_AddressType

IPv4 address expressed as the range of the addresses


_IP_ADDRESS_V6

struct _IP_ADDRESS_V6
{
     unsigned long m_AddressType;
     union
     {
          IP_SUBNET_V6  m_IpSubnet;
          IP_RANGE_V6  m_IpRange;
     };
}

m_AddressType

Specifies which of the IP v6 address types is used below. Must be set to IP_SUBNET_V6_TYPE or IP_RANGE_V6_TYPE

m_IpSubnet

IPv6 address expressed as subnet

m_AddressType

IPv6 address expressed as the range of the addresses


_IP_RANGE_V4

struct _IP_RANGE_V4
{
    unsigned long  m_StartIp;
    unsigned long  m_EndIp;
}

m_StartIp

IPv4 address expressed as ULONG (first address of the range)

m_EndIp

IPv4 address expressed as ULONG (last address of the range)


_IP_RANGE_V6

struct _IP_RANGE_V6
{
    IN6_ADDR  m_StartIp;
    IN6_ADDR  m_EndIp;
}

m_StartIp

IPv6 start range address

m_EndIp

IPv6 end range address


_IP_SUBNET_V4

struct _IP_SUBNET_V4
{
     unsigned long  m_Ip;
     unsigned long  m_IpMask;
}

m_Ip

IPv4 address expressed as ULONG

m_IpMask

IPv4 mask expressed as ULONG


_IP_SUBNET_V6

struct _IP_SUBNET_V6
{
     IN6_ADDR  m_Ip;
     IN6_ADDR  m_IpMask;
}

m_Ip

IPv6 address

m_IpMask

IPv6 network mask


_IP_V4_FILTER

struct _IP_V4_FILTER
{
     unsigned long 	m_ValidFields;
     IP_ADDRESS_V4 	m_SrcAddress;
     IP_ADDRESS_V4 	m_DestAddress;
     unsigned char 	m_Protocol;

}

m_ValidFields

Specifies which of the fileds below contain valid values and should be matched against the packet. Must be a combination of the following flags: IP_V4_FILTER_SRC_ADDRESS, IP_V4_FILTER_DEST_ADDRESS, IP_V4_FILTER_PROTOCOL.

m_SrcAddress

Source IP address

m_DestAddress

Destination IP address

m_Protocol

Next Protocol (IP protocol type)


_IP_V6_FILTER

struct _IP_V6_FILTER
{
     unsigned long 	m_ValidFields;
     IP_ADDRESS_V6 	m_SrcAddress;
     IP_ADDRESS_V6 	m_DestAddress;
     unsigned char 	m_Protocol;

}

m_ValidFields

Specifies which of the fileds below contain valid values and should be matched against the packet. Must be a combination of the following flags: IP_V6_FILTER_SRC_ADDRESS, IP_V6_FILTER_DEST_ADDRESS, IP_V6_FILTER_PROTOCOL.

m_SrcAddress

Source IP address

m_DestAddress

Destination IP address

m_Protocol

Next Protocol (IP protocol type)


_NETWORK_LAYER_FILTER

struct _NETWORK_LAYER_FILTER
{
     unsigned long m_dwUnionSelector;
     union
     {
          IP_V4_FILTER m_IPv4;

          IP_V6_FILTER m_IPv6;
     };
}

This structure represents network layer (OSI-7) filter level.

m_dwUnionSelector

Specifies which of the union members below is valid.

m_IPv4

IP version 4 filter

m_IPv6

IP version 6 filter


_NDISRD_ETH_Packet

struct _NDISRD_ETH_Packet
{
    PINTERMEDIATE_BUFFER		Buffer;
}

Buffer

The pointer to the _INTERMEDIATE_BUFFER structure

Copyright NT Kernel Resources © 2000-2010


_PACKET_OID_DATA

struct _PACKET_OID_DATA
{
    HANDLE			hAdapterHandle;
    ULONG			Oid;
     ULONG			Length;
     UCHAR			Data[1];
}

hAdapterHandle

The adapters handle value for set/query operation.

Oid

This is a numeric identifier that indicates the type of query/set function to perform on the adapter through the PacketRequest function. Possible values are defined in the ntddndis.h include file. It can be used, for example, to retrieve the status of the error counters on the adapter, its MAC address, the list of the multicast groups defined on it, and so on.

Length

This field indicates the length of the Data field.

Data

This fiels contains the information passed to or received from the adapter.


_PORT_RANGE

struct _PORT_RANGE
{
     unsigned short m_StartRange;
     unsigned short m_EndRange;
}

m_StartRange

First TCP/UDP port value expressed in host byte order

m_EndRange

Last TCP/UDP port value expressed in host byte order


_RAS_LINK_INFO

struct _RAS_LINK_INFO
{
    ULONG  		LinkSpeed;
        ULONG  		MaximumTotalSize;
        UCHAR  		RemoteAddress [ETHER_ADDR_LENGTH];
        UCHAR  		LocalAddress [ETHER_ADDR_LENGTH];
        ULONG  		ProtocolBufferLength;
        UCHAR  		ProtocolBuffer	[RAS_LINK_BUFFER_LENGTH];
}

LinkSpeed

Specifies the speed of the link, in units of 100 bps. Zero indicates no change from the speed returned when the protocol called NdisRequest with OID_GEN_LINK_SPEED.

MaximumTotalSize

 Specifies the maximum number of bytes per packet that the protocol can send over the network. Zero indicates no change from the value returned when the protocol called NdisRequest with OID_GEN_MAXIMUM_TOTAL_SIZE.

RemoteAddress

Represents the address of the remote node on the link in Ethernet-style format. NDISWAN supplies this value.

LocalAddress

Represents the protocol-determined context for indications on this link in Ethernet-style format.

ProtocolBufferLength

Specifies the number of bytes in the buffer at ProtocolBuffer.

ProtocolBuffer

Containing protocol-specific information supplied by a higher-level component that makes connections through NDISWAN to the appropriate protocol(s). Maximum size is 600 bytes (on Windows Vista)


_RAS_LINKS

struct _RAS_LINKS
{
    ULONG		nNumberOfLinks;
    RAS_LINK_INFO	RasLinks[RAS_LINKS_MAX];
}

nNumberOfLinks

Specifies number of entries initialized in RasLinks array.

RasLinks

 Array of RAS_LINK_INFO structures initialized according active WAN connections list.


_STATIC_FILTER

struct _STATIC_FILTER
{
     ULARGE_INTEGER  	m_Adapter;
     unsigned long  		m_dwDirectionFlags;
     unsigned long  		m_FilterAction;
     unsigned long  		m_ValidFields;
     unsigned long  		m_LastReset;
     ULARGE_INTEGER  	m_Packets;
     ULARGE_INTEGER  	m_Bytes;
     DATA_LINK_LAYER_FILTER 	m_DataLinkFilter;
     NETWORK_LAYER_FILTER 	m_NetworkFilter;
     TRANSPORT_LAYER_FILTER 	m_TransportFilter;
}

This structure represents single filter entry.

m_Adapter
Adapter handle. For 32 bit systems assign adapter handle to m_Adapter.LowPart , for 64 bit systems to m_Adapter.QuadPart. If m_Adapter.QuadPart = 0 then filter is applied to all adapters.

m_dwDirectionFlags
Determines if filter should be applied to incoming, outgoing or incoming and outgoing packets. Must be a combination of PACKET_FLAG_ON_SEND and PACKET_FLAG_ON_RECEIVE

m_FilterAction
Determines if packet should be passed, dropped or redirected for processing in user mode. Must be assigned to the one of FILTER_PACKET_PASS, FILTER_PACKET_DROP or FILTER_PACKET_REDIRECT

m_ValidFields
Specifies which of the filters below contain valid values and should be matched against the packet. Must be a combination of DATA_LINK_LAYER_VALID, NETWORK_LAYER_VALID and TRANSPORT_LAYER_VALID

m_LastReset
Time of the last counters reset (in seconds passed since 1 Jan 1980)

m_Packets
Number of packets passed through this filter since last reset

m_Bytes
Number of bytes passed through this filter since last reset

m_DataLinkFilter
Data link layer filter entry

m_NetworkFilter
Network layer filter entry

m_TransportFilter
Transport layer filter entry


_STATIC_FILTER_TABLE

struct _STATIC_FILTER_TABLE
{
     unsigned long m_TableSize;
     STATIC_FILTER m_StaticFilters[ANY_SIZE];
}

m_TableSize

Number of the STATIC_FILTER elements in m_StaticFilters array.

m_StaticFilters

Array of STATIC_FILTER structures. Filters are applied to the packets in the order of this array, e.g. m_StaticFilters[0] is applied first and if it matches the packet other filters are not checked.


_TCP_AdapterList

struct _TCP_AdapterList
{
   unsigned long	m_nAdapterCount;
   unsigned char	m_szAdapterNameList[ ADAPTER_LIST_SIZE ][ ADAPTER_NAME_SIZE ];
   HANDLE		m_nAdapterHandle [ ADAPTER_LIST_SIZE ];
   unsigned int		m_nAdapterMediumList[ ADAPTER_LIST_SIZE ];
   unsigned char	m_czCurrentAddress[ ADAPTER_LIST_SIZE ][ ETHER_ADDR_LENGTH ];
   unsigned short	m_usMTU [ ADAPTER_LIST_SIZE ];
}

m_nAdapterCount

Number of MSTCP associated interfaces.

m_szAdapterNameList

An array of internal adapter names.

m_nAdapterHandle

An array of adapter handles, this are key handles for any adapter relative operation.

m_nAdapterMediumList

An array of adapters mediums.

m_czCurrentAddress

An array of adapters current (configured) Ethernet addresses.

m_usMTU

An array of adapters MTUs.


_TCPUDP_FILTER

struct _TCPUDP_FILTER
{
     unsigned long  	m_ValidFields;
     PORT_RANGE  	m_SourcePort;
     PORT_RANGE  	m_DestPort;
}

m_ValidFields

Specifies which of the fileds below contain valid values and should be matched against the packet. Must be a combination of the following flags: TCPUDP_SRC_PORT, TCPUDP_DEST_PORT.

m_SourcePort

Source TCP/UDP port

m_DestPort

Destination TCP/UDP port


_TRANSPORT_LAYER_FILTER

struct _TRANSPORT_LAYER_FILTER
{
     unsigned long m_dwUnionSelector;
     union
     {
          TCPUDP_FILTER m_TcpUdp;
     };
}

This structure represents transport layer (OSI-7) filter level.

m_dwUnionSelector

Specifies which of the union members below is valid. Currently only TCP and UDP are supported and this field should be laways set to TCPUDP.

m_TcpUdp

TCP/UDP port filter


WinpkFilter Samples

For easy start with WinpkFilter framework there are several sample applications with complete source code provided. All samples created as Win32 console applications and contains relatively small amount of code (without much error handling) for easier understanding. Lets describe them here shortly:

AdaptersList

PacketSniffer

PassThru

NdisRequest

WWWCensor

GRETunnel

Filter

FilterStats


Filter

This sample demonstrates the basic usage of the SetPacketFilterTable API. It introduces sets of filters for the following scenarios:

1) Redirect only DNS packets for processing in user mode.
2) Redirect only HTTP(TCP port 80) packets for processing in user mode.
3) Drop all ICMP packets. Redirect all other packets to user mode (default behaviour).
4) Block access to http://www.ntkernel.com. Pass all other packets without processing in user mode.
5) Redirect only ARP/RARP packets to user mode. Pass all others.


FilterStats

This sample demonstrates the basic usage of the GetPacketFilterTable and GetPacketFilterTableResetStats. It can be used together with the Filter sample application.


GRETunnel

This sample demonstrates IP over GRE tunneling. For each outgoing IP packet application inserts GRE header before the IP header. For each incoming packet application checks if it has the GRE header and removes it. In order to test the application you have to run it on two systems connected over network. While the applications are active these two systems will be able to communicate over network with each other (over GRE tunnels) but won't be able to communicate with any other system.


ListAdapters

This sample demonstrates the basic usage of CNdisApi object, CNdisApi::GetTcpipBoundAdaptersInfo, adapter name conversion functions and CNdisApi::GetMTUDecrement. It dumps all information requested from helper driver on the console screen. Network interfaces indexes dumped by this utility can be passed to PacketSniffer and PassThru.

Notes:

  • Displayed MTU value is a real network interface MTU (size of maximum IP packet) without system wide MTU decrement
  • On Windows NT/2000/XP MTU is not defined for \Device\NDISWANIP (dial-up interface) before connection was established
  • When multiply NDISWAN connections established (Windows 2000/XP supports more then one active NDISWAN device) it also displays available information on WAN links.


NdisRequest

This sample demonstrates the basic usage of NdisrdRequest function. It queries all locally installed network interfaces for their current MAC address, frames transmitted without errors, frames received without errors, frames not transmitted or transmitted with errors, frames received with errors.


PacketSniffer

This sample demonstrates the basic usage of listening modes. It sets chosen network interface into the listening mode (sent and received packets queued) and polls helper driver for new packets. Starting from version 2.0 of WinpkFilter this sample is also demonstrates the usage of promiscuous mode.

Notes:

  • If you set adapter into the listening mode you should remember that the internal helper driver packet queue size is limited (500 packets in current version). If you don't read packets from the queue (with CNdisApi::ReadPacket) or release the queued packets directly by calling CNdisApi::FlushAdapterPacketQueue then after the queue reaches it's maximum limit all network activities will be frozen. Please be attentive, don't forget to release network interface after you have finished reading packets from it (see ReleaseInterface function in the PacketSniffer.cpp).
  • Use ListAdapters for getting information about MSTCP network interfaces and for getting network interface index for calling PacketSniffer
  • Note that as far as network interfaces can be enabled/disabled dynamically on Windows 2000/XP adapter list also changes when these operations performed.
  • PacketSniffer uses polling helper driver for packets. This is not effective and has a serious performance impact. Take a look on the more advanced PassThru for more effective approach with Win32 event.


PassThru

Windows Packet Filter Kit: Samples

PassThru (PackThru)

This sample demonstrates the basic usage of active filtering modes. It sets chosen network interface into the filtering mode (sent and received packets queued), register Win32 event (CNdisApi::SetPacketEvent) and start waiting for the new packets. This samples functionality is close to Windows DDK PassThru intermediate driver sample. PackThru is the same as PassThru but it uses multiply packets sends/receives.

Notes:

  • If you set adapter into the filtering mode you should remember that the internal helper driver packet queue size is limited (500 packets in current version). If you don't read packets from the queue (with CNdisApi::ReadPacket) or release the queued packets directly by calling CNdisApi::FlushAdapterPacketQueue then after the queue reaches it's maximum limit all network activities will be frozen. Please be attentive, don't forget to release network interface after you have finished reading packets from it (see ReleaseInterface function in the PassThru.cpp).
  • Use ListAdapters for getting information about MSTCP network interfaces and for getting network interface index for calling PacketSniffer
  • Note that as far as network interfaces can be enabled/disabled dynamically on Windows 2000/XP adapter list is also changed when these operations are performed.


WWWCensor

This is a simple packet content filtering sample. It accepts a single word or phrase as input and drops every HTTP packet where it finds the specified pattern. An example, if you start "wwwcensor.exe porn" the application will block access to any web site which contains "porn" as part of the URL also no pages containing the word porn will be displayed in browser.


ConvertWindows9xAdapterName

BOOL ConvertWindows9xAdapterName (LPCSTR szAdapterName, LPSTR szUserFriendlyName, DWORD dwUserFriendlyNameLength);

Return Value:

TRUE in case of success, FALSE otherwise

Parameters:

szAdapterName

Internal adapter name returned by GetTcpipBoundAdaptersInfo call.

szUserFriendlyName

Pointer to user allocated buffer where user-friendly adapter name placed in case of success

dwUserFriendlyNameLength

Size of buffer in bytes pointed by szUserFriendlyName

Remarks:

This function converts internal network interface name returned by GetTcpipBoundAdaptersInfo into the one you see in Network Connections properties. This function should be called for Windows 9x and ME only.


ConvertWindows2000AdapterName

BOOL ConvertWindows2000AdapterName (LPCSTR szAdapterName, LPSTR szUserFriendlyName, DWORD dwUserFriendlyNameLength);

Return Value:

TRUE in case of success, FALSE otherwise

Parameters:

szAdapterName

Internal adapter name returned by GetTcpipBoundAdaptersInfo call.

szUserFriendlyName

Pointer to user allocated buffer where user user-friendly name placed in case of success

dwUserFriendlyNameLength

Size of buffer in bytes pointed by szUserFriendlyName

Remarks:

This function converts internal network interface name returned by GetTcpipBoundAdaptersInfo into the one you see in Network Connections properties. This function should be called for Windows 2000 and XP only.


ConvertWindowsNTAdapterName

BOOL ConvertWindowsNTAdapterName (LPCSTR szAdapterName, LPSTR szUserFriendlyName, DWORD dwUserFriendlyNameLength);

Return Value:

TRUE in case of success, FALSE otherwise

Parameters:

szAdapterName

Internal adapter name returned by GetTcpipBoundAdaptersInfo call.

szUserFriendlyName

Pointer to user allocated buffer where user-friendly adapter name placed in case of success

dwUserFriendlyNameLength

Size of buffer in bytes pointed by szUserFriendlyName

Remarks:

This function converts internal network interface name returned by GetTcpipBoundAdaptersInfo into the one you see in Network Connections properties. This function should be called for Windows NT4.0 only.