[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 Whistler. 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 Whistler 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 Whistler is subject to change. Developers should not assume availability of this functionality for user-mode applications on Windows Whistler.
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.
NOTE: On
Windows Whistler, 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 debugging
debug.h Debug macro definitions
macros.h Spinlock, event, referencing macros
ndisbind.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