SwsVpkt User Mode API

The SwsVpkt virtual packet driver, although primarily designed to support DOS packet driver applications, can also be used by Win32 user mode programs to perform raw Ethernet frame I/O. The user mode API is similar to Microsoft's Ndisuio device but has the significant advantage of supporting multiple simultaneous clients

The SwsVpkt virtual packet driver consists of 3 components:

  1. A real mode stub (swsvpkt.exe) that forwards packet driver API calls from DOS programs to a.Win32 DLL.
  2. A Win32 DLL (swsvpkt.dll) that implements the packet driver API (see http://www.crynwr.com/packet_driver.html) and provides a virtual NIC for each DOS client. The DLL performs raw Ethernet frame I/O using a Win32 device.
  3. An NDIS 4.0 protocol driver (swsvpkt.sys) that implements the Win32 device for performing user mode network I/O.

This document describes the Win32 user mode interface provided by swsvpkt.sys. The archive userio.zip contains a C language example program and reusable header file.

SwsVpkt devices

The NDIS protocol driver creates a Win32 device for each bound network adapter. NDIS manages the bindings based upon information supplied during installation in an inf file. The devices are named \\.\SwsVpkt0 thru \\.\SwsVpkt31. A device handle may be obtained using the Win32 user mode function CreateFile:

Read Operations

Raw incoming Ethernet frames, complete with header but no trailing FCS, are received by posting buffers using standard Win32 file read functions. Each frame that is indicated to the NDIS protocol driver is passed unmodified to each open client handle. If there are no pending read operations for a given client then the frame is ignored for that client - no error indication is given. If a client buffer is too small then the excess data is discarded and the read operation terminated with error. Incoming frames are not concatenated into a single buffer, even if there is remaining buffer space in a read request after the first frame. There is a one to one correspondence between incoming frames and completed read requests. Hence it is essential that each client queue a sufficient number of maximum sized buffers using asynchronous read requests.

Write Operations

Raw outgoing Ethernet frames, complete with header but no trailing FCS, are sent using standard Win32 file write functions. The Ethernet frame is not modified in any way and is passed directly to the network adapter driver.

Ioctl Operations

The following operations, defined in ioctls.h from the userio.zip archive, are supported using DeviceIoControl:

IOCTL_GETMACADDR

Read the adapter's MAC address.
Output buffer: 6 byte MAC address.

IOCTL_SETMULTICASTLIST

Set the adapter's multicast input filter list.
Input buffer: Array of 6 byte multicast addresses. If the list is zero length then multicast reception is disabled.

IOCTL_SETPROMISCUITY

Enable or disable the adapter's promiscuous listen mode.
Input buffer: 1 byte. Non-zero to enable promiscuous mode.

IOCTL_WRITE_SCATTER

Reserved for future use.

IOCTL_GETINFO

Read status information.
Output buffer: struct IOCTL_INFO.

typedef struct IOCTL_INFO {
BOOLEAN bPowerOn;
BOOLEAN bMediaDisconnected;
BOOLEAN bWan; /* Adapter is a WAN */
BOOLEAN bWanDown; /* WAN is not connected */
} IOCTL_INFO;

IOCTL_GETMULTICASTLIST

Get the adapter's multicast input filter list. Note that this is the union of multicast lists from each client.
Output buffer: Array of 6 byte multicast addresses.

IOCTL_GETDESC

Get the adapter name. This is typically the same as that shown in the Network and Dial-up Connections control panel.
Output buffer: ASCIIZ name.