[This is
preliminary documentation and subject to change.]
This sample demonstrates
a connection-less NDIS 5.0/5.1 protocol driver. The driver supports sending and
receiving raw Ethernet frames using ReadFile/WriteFile
calls from user-mode. It only receives frames with a specific (run-time
configurable) EtherType field. As an NDIS protocol,
it illustrates how to establish and tear down bindings to Ethernet adapters,
i.e. those that export medium type NdisMedium802_3. It shows how to set
a packet filter, send and receive data, and handle plug-and-play events. It
also shows use of the following NDIS 5.1 features/APIs:
1.
Canceling
sends
2.
NdisQueryPendingIOCount()
The sample works on
Windows 2000, 32-bit and 64-bit platforms, and Windows XP. Both checked and
free builds are available.
From the
Free or Checked Build environment, execute build in the ndisuio directory.
This step can be omitted on Windows XP where this driver is installed by default, as a hidden protocol. NOTE that the functionality present in the in-build version of NDISUIO on Windows XP is subject to change. Developers should not assume availability of this functionality for user-mode applications on Windows XP.
The driver is installed
using the INF file ndisuio.inf, which is provided in the driver directory. In
Network Connections UI, select an adapter and open Properties.
Click Install,
then Protocol, then Add, and then Have disk. Then point to
the location of the .inf and driver.
Select NDIS Usermode
I/O Protocol and click OK. After installing the protocol, copy over
the test application uiotest.exe to a convenient location.
To start
the driver, type
Net start ndisuio
To stop
the driver, type
Net stop ndisuio
To test
the driver, run uiotest. For help on usage, run uiotest -?
usage: UIOTEST [options] <devicename>
options:
-e: Enumerate devices -r: Read -w: Write (default) -l <length>: length of each packet (default: 100) -n <count>: number of packets (defaults to infinity) -m <MAC address> (defaults to local MAC)
Uiotest exercises the IOCTLs
supported by NDISUIO, and sends and/or receives data on the selected device. In
order to use uiotest, the user must have administrative privilege.
NOTE: On
Windows XP, uiotest may fail to access devices since other processes could have
open handles to NDISUIO for those devices. To work around this, stop and
restart NDISUIO as shown above. You will be prompted to stop services that
depend on NDISUIO as well.
Use the –e option to enumerate all
devices to which NDISUIO is bound:
C:\uio>uiotest -e
0. \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F} - Intel-Based 10/100 Ethernet Card
The
following command sends and receives 2 packets on a device). Since these packets are sent to
the local MAC address (default), both packets are received. The
device name parameter to uiotest is picked up from the output of uiotest –e
(see above).
C:\uio>uiotest -n 2 \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F}DoWriteProc: finished sending 2 packets of 100 bytes each
DoReadProc finished: read 2 packets
With a checked version of
ndisuio.sys, you can control the volume of debug information generated by
changing the variable ndisuioDebugLevel. Refer to debug.h for more information.
Directory: Test
File Description
uiotest.c User-mode test application Directory: Sys
File Description
debug.c Routines to aid debuggingdebug.h Debug macro definitionsmacros.h Spinlock, event, referencing macrosndisbind.c NDIS protocol entry points to handle binding/unbinding from adapters
ndisuio.h Data structure definitions
ndisuio.inf INF file for installing NDISUIO
ntdisp.c NT Entry points and dispatch routines for NDISUIO
nuiouser.h IOCTL and associated structure definitions
recv.c NDIS protocol entry points for receiving data, and IRP_MJ_READ processing
send.c NDIS protocol routines for sending data, and IRP_MJ_WRITE processing
|
|
© Microsoft Corporation
2000