那家打印通信公司，又出新玩艺了。支持98，2000,xp的imd

好久没去看了，去看了一下发现那家打印通信公司，又出新玩艺了。
竟然是同时支持98，me,2000,xp的imd.
Divine同志看来是打算一直吃这碗饭了。
得好好象他学习一下。

\"Universal\"
NDIS Intermediate (IM)
Driver Samples
V2.04.05.14 - June 7, 2001



This page provides interim documentation about an ongoing PCAUSA development project.

This is not an \"advertised\" website and cannot be located by search engines. The URL is provided only to selected PCAUSA customers and other parties who may have an active interest the Universal NDIS IM product in its as-is condition or who may wish to monitor the progress of its development.

This is not intended to be a \"pretty\" site. It simply provides a convenient mechanism for PCAUSA to provide some documentation as the development progresses.

The product is expected to be released Q1 2002. It has been licensed to selected PCAUSA customers who are aware that it is a work-in-progress.

Thanks for your interest in this PCAUSA development activity.

Thomas F. Divine
President - PCAUSA



What\'s New
NDISIM Interim Documentation Released!!!
April 16, 2002 - Some additional documentation for the new PCAUSA NDIS IM driver samples is now available. The documentation is not final, but is released as-is as an aid to developers. We hope to have the final documentation shortly.

The documentation is provided as compiled HtmlHelp. It should be viewable won Windows 2000 and Windows XP. On other platforms it may be necessary to install Html Help Viewer updates. Go to the Microsoft Download Center and search for \"Html Help Downloads\".

[ New NDIS IM Driver Interim Documentation ]

 

NDISIM Interim Build 14 Released!!!
June 7, 2001 - NDISIM V2.04.05.14 (Beta Build 14) Released. Includes a new \"CryptoPing\" sample as well as an important fix for handling NDIS miniports that provide NDIS Task Offload support.

See the Release Notes:

[ NDISIM Release Notes ]

 



Introduction
The PCAUSA Universal NDIS Intermediate Driver Samples (UNIM) are the successor to the \"PCASIM\" product.  The following are the design goals for the PCAUSA \"Universal\" NDIS Intermediate (IM) Driver Samples:

Provide Windows 2000 NDIS IM Driver Sample
Provide NDIS IM Samples For Other Platforms (Windows XP, Windows Me, Windows 98)
Provide Single-Source Driver For All Supported Platforms
Provide A Uniform User Mode API For All Samples
Provide Additional IM Driver Functionality Samples
Improve Documentation
Explore Installation As Protocol/Service
Explore NDIS IM Drivers Over RAS/PPP Adapters
Improve Installation Functionality
The current version as-is state at least partially satisfies goals 1.), 2.), 3.), 4.) and 5.) above.

 June 4, 2001 - PCAUSA is likely to abandon development of NDIS IM driver samples for Windows 98 and Windows ME as part of this product. Sorry...

Although there is little difficulty in development of basic NDIS IM drivers for those platforms, the installation mechanism is horrible.

The NDIS PIM driver approach has proven to be much more robust and installation of a NDIS PIM driver is simple.

This page will be maintained as interim documentation as the product evolves. The documentation is broken down roughly as follows:

 Product Code Directory Layout
 Guide To The Sample NDIS Intermediate Drivers  Active PassThru NDIS IM Sample
 \"CryptoPing\" Packet Encrypting NDIS Intermediate Driver
 IP Packet Redirector NDIS IM Sample
 
 Building The Drivers
 Installing The Drivers
 Release Notes

 



Product Directory Layout
The NIM directory layout parallels the layout of the PCASIM directory tree.

PCADev - Root For PCAUSA Product Sources
    NDISIM - Root For New NDIS IM (NIM) Sources
        Apps - Win32 Application Sources
            IMUtil - Interim NIM Test Application
            PktRedir - IP Packet Redirector Test Applications
             PRTest1 - Simple Blocking IP Filter Test
             PRTest2 - Read Of Packet Being Sent Test
             PRTest3 - Read/Write Test (Virtual PING Reply Generator)
PRTest4 - Read Of Packet Being Received Test
PRTest5 - Filter ALL IP Packets Sent/Received At Win32
       Bin - Reference Executables And .INF Files
       Dll - PCAImApi DLL Sources
       Doc - Documentation
       Driver - Root for NDIS IM Driver Sources
            DDKINCX - Special NDIS.H for Windows NT 4.0, SP3+
            DDKLIBX - Special NDIS.LIB for Windows NT 4.0, SP3+
            PassThru - Single-Source Files For Active PassThru Sample
                NTBuild - MAKEFILE and SOURCES for Windows NT DDK Build
                W2KBuild - MAKEFILE and SOURCES for Windows 2000 DDK Build
                XPBuild - MAKEFILE and SOURCES for Windows XP DDK Build
            CryptoPing - Single-Source Files For CryptoPing Sample
                NTBuild - MAKEFILE and SOURCES for Windows NT DDK Build
                W2KBuild - MAKEFILE and SOURCES for Windows 2000 DDK Build
                XPBuild - MAKEFILE and SOURCES for Windows XP DDK Build
             PktRedir     - Single-Source Files For Win32 IP Packet Redirector Sample
                NTBuild - MAKEFILE and SOURCES for Windows NT DDK Build
                W2KBuild - MAKEFILE and SOURCES for Windows 2000 DDK Build
                XPBuild - MAKEFILE and SOURCES for Windows XP DDK Build
       Include - Headers shared by all NIM components
       LBLInc - \"Unix-style\" Internet Header Files
 

If you are a current user of the Windows NT PCASIM V1.00.01.07 you will see roughly the same breakdown of source code modules. Many of the same supporting functions are in place.

 Do understand that although the directory structure parallels that of the older PCASIM sources, many files are actually different and shouldn\'t be interchanged between PCASIM and NIM.

 



Guide To The NDIS Intermediate Driver Samples
The following NDIS Intermediate Driver Samples are available in V2.04.05.14 :

 Active PassThru NDIS Intermediate Driver
 \"CryptoPing\" Packet Encrypting NDIS Intermediate Driver
 IP Packet Redirector NDIS Intermediate Driver

 



Active PassThru NDIS Intermediate Driver
Although the current suite of Microsoft DDK NDIS IM driver samples are extremely useful, they are \"passive PassThru\" drivers. They perform only the absolute minimum of processing and inspection of data being sent or received. For example, when processing a received packet they simply \"re-wrap\" the received packet and pass the re-wrapped packet up to higher-level protocols. Similarly, NDIS requests and other operations are just passed on with a minimum of processing.

Passive PassThru NDIS IM samples do not provide answers to these interesting questions:

How do I inspect or \"filter\" data passing through the driver?
How do I make copies of data being sent or received?
How do I inject my own data into the send/receive paths?
How can I distinguish between my own data and passthru data in completion functions such as ProtocolSendComplete and ReturnPacketHandler.
    Note: For example, you wouldn\'t want to call a higher-level protocol\'s ProtocolSendComplete handler
    for a packet that it did not actually send.
How do I actually handle packets in my ProtocolReceiveHandler?
    NOTE: This is actually very messy, and is required and exercised even on Windows 2000.
How do I filter calls to QueryInformationHandler or SetInformationHandler?
How can I implement a practical Win32 API for communication with my driver?
The PCAUSA Active PassThru and Packet Redirector (PtkRedir) samples attempt to answer these questions.

 



\"CryptoPing\" Packet Encrypting NDIS Intermediate Driver
CryptoPing takes the PassThru sample and extends it to illustrate a NDIS IM driver that performs modification to transmitted and received network packets. The sample performs simple in-place \"encryption\" of transmitted ICMP Echo Request (\"ping\" requests) packets and an inverse decryption of received ICMP Echo Reply packets.

Without CryptoPing installed the ping packets observed on the network look similar to the following HEX dump representation:

Packet No.: 0000000030            Time: 0252892873 msec       Length: 74/74
Ethernet Dest: 00.40.95.49.03.5F   Src:  00.50.DA.03.4D.DF    Type: 0x0800
000000:  00 40 95 49 03 5F 00 50 : DA 03 4D DF 08 00 45 00    .@.I._.P..M...E.
000010:  00 3C 07 46 00 00 80 01 : AF 9C C0 A8 01 6E C0 A8    .<.F.........n..
000020:  01 20 08 00 48 5C 03 00 : 02 00 61 62 63 64 65 66    . ..H\\....abcdef
000030:  67 68 69 6A 6B 6C 6D 6E : 6F 70 71 72 73 74 75 76    ghijklmnopqrstuv
000040:  77 61 62 63 64 65 66 67 : 68 69                      wabcdefghi......

Packet No.: 0000000031            Time: 0252892873 msec       Length: 74/74
Ethernet Dest: 00.50.DA.03.4D.DF   Src:  00.40.95.49.03.5F    Type: 0x0800
000000:  00 50 DA 03 4D DF 00 40 : 95 49 03 5F 08 00 45 00    .P..M..@.I._..E.
000010:  00 3C E5 15 00 00 80 01 : D1 CC C0 A8 01 20 C0 A8    .<........... ..
000020:  01 6E 00 00 50 5C 03 00 : 02 00 61 62 63 64 65 66    .n..P\\....abcdef
000030:  67 68 69 6A 6B 6C 6D 6E : 6F 70 71 72 73 74 75 76    ghijklmnopqrstuv
000040:  77 61 62 63 64 65 66 67 : 68 69                      wabcdefghi......
The ICMP Option Data is shown in bold letters.

CryptoPing encodes transmitted ICMP Echo Requests by simply changing the case of odd-numbered ICMP Option Data. Received ICMP Echo Reply packets are decrypted using the inverse operation. With CryptoPing installed the ping packets observed on the network look similar to the following HEX dump representation:

Packet No.: 0000000005            Time: 0253034683 msec       Length: 74/74
Ethernet Dest: 00.40.95.49.03.5F   Src:  00.20.18.D6.41.E7    Type: 0x0800
000000:  00 40 95 49 03 5F 00 20 : 18 D6 41 E7 08 00 45 00    .@.I._. ..A...E.
000010:  00 3C 56 AD 00 00 80 01 : 60 3D C0 A8 01 66 C0 A8    .<V.....`=...f..
000020:  01 20 08 00 A3 07 02 00 : AA 54 61 42 63 44 65 46    . .......TaBcDeF
000030:  67 48 69 4A 6B 4C 6D 4E : 6F 50 71 52 73 54 75 56    gHiJkLmNoPqRsTuV
000040:  77 41 62 43 64 45 66 47 : 68 49                      wAbCdEfGhI......

Packet No.: 0000000006            Time: 0253034683 msec       Length: 74/74
Ethernet Dest: 00.20.18.D6.41.E7   Src:  00.40.95.49.03.5F    Type: 0x0800
000000:  00 20 18 D6 41 E7 00 40 : 95 49 03 5F 08 00 45 00    . ..A..@.I._..E.
000010:  00 3C F2 15 00 00 80 01 : C4 D4 C0 A8 01 20 C0 A8    .<........... ..
000020:  01 66 00 00 AB 07 02 00 : AA 54 61 42 63 44 65 46    .f.......TaBcDeF
000030:  67 48 69 4A 6B 4C 6D 4E : 6F 50 71 52 73 54 75 56    gHiJkLmNoPqRsTuV
000040:  77 41 62 43 64 45 66 47 : 68 49                      wAbCdEfGhI......
Implementation of CryptoPing involved changes to only one module from the baseline PassThru sample.

The changes involved primarily:

Selection of the packets to modify.
Modification of selected packets.
The selection process made use of the Un*x-style IP-related header structures and definitions provided in the NetINet directory. Use of these headers provides one systematic way to access information in IP packets.

Modification of selected packets is fairly easy since the machinery provided in the active PassThru sample already builds \"clone\" NDIS packets that include a private \"flattened\" that contains a copy of the original packet data. This private flattened buffer can be modified using ordinary pointer arithmetic. After the modification the ICMP message checksum is recomputed.

The sample has limitations. It does not perform re-assembly or fragmentation. It only operates on request and reply packets that are contained on one packet; if they are longer, then they are ignored.

 



IP Packet Redirector NDIS Intermediate Driver
This sample adds a mechanism that allows a Win32 application to interact with the packet stream that passes through the NDIS IM driver.

 
Virtual Adapter And Lower Adapter Interfaces
For each NDIS IM driver binding there are actually two logical \"adapter\" interfaces:

 LowerAdapter - A \"real\" adapter that the NDIS IM driver binds to at it\'s lower \"protocol\" edge.
 Virtual Adapter - The virtual adapter that the NDIS IM driver presents to other protocols at its upper \"miniport\" edge.

The API allows a Win32 application to open a handle to either (or both) of these adapter interfaces:

 PCASIM_OpenLowerAdapter - Opens a handle associated with the lower or \"real\" adapter using the \"Adapter Name\".
 PCASIM_OpenVirtualAdapter - Opens a handle associated with the upper or \"virtual\" adapter using the \"AdapterName\".
 PCASIM_OpenLowerAdapterByLinkAddress - Opens a handle associated with the lower or \"real\" adapter using the adapters physical or link address.
 PCASIM_OpenVirtualAdapterLinkAddress - Opens a handle associated with the upper or \"virtual\" adapter using the adapters physical or link address.

 

Reading And Writing On PCASIM Adapter Handles
One can read and write on either of these adapter handles using these API functions:

 PCASIM_ReadOnAdapter - Reads a selected packet on the specified handle.
 PCASIM_WriteOnAdapter - Writes a packet on the specified handle.

It should be easy to understand read/write operations on a PCASIM lower adapter handle. Writes on a PCASIM lower adapter handle are translated to NdisSend calls to the lower \"real\" adapter and result in packets being sent on the network. Similarly, reads on the lower adapter handle allow the Win32 application to read a selected packet that was being received or indicated from the lower adapter.

Note: On Windows NT and Windows 2000 the PCASIM_ReadOnAdapter and PCASIM_WriteOnAdapter functions are simply wrappers around the Win32 API ReadFile and WriteFile functions. However, the functions translate to a DeviceIoControl call on Windows 9X and Windows Millennium since ReadFile and WriteFile cannot be used.

 

IP Packet Filter For Reading On PCASIM Adapter Handles
Of course, it isn\'t a real good idea to pass all received packets up to the Win32 application. A mechanism is provided that allows the Win32 application to pass a filter to the driver to specify which IP packets can be read. The filter is list of IP Source/Destination address ranges and an \"action\" to be performed on packets that match the filter criteria. The actions can be combinations of:

 BLOCK - Have the NDIS IM driver drop the matching packet from the normal packet flow.
 REDIRECT - Have the NDIS IM driver pass a copy of the received packet to the Win32 application through the PCASIM_ReadOnPacket mechanism.

For example, the combination of BLOCK and REDIRECT actions cause a matching packet to be be diverted up to the Win32 application for processing. The REDIRECT action allows the Win32 application to monitor the packet while allowing it to also pass up to higher level protocols for ordinary processing.

 

Operations On The PCASIM Virtual Adapter Handle
Yes, the API is fully symmetrical. This means that one can also read and write on a virtual adapter handle.

However, in this case the behavior is \"upside-down\". For example, a write on a virtual adapter handle will cause a packet to be injected and travel \"upwards\" to higher-level protocols as if it had been received from the network. Similarly, reads on a virtual adapter handle actually operate on packets being send from the higher-level protocols.

 

Uniform Win32 API Across All Platforms
Finally, the Win32 API has been refined so that it provides a uniform and consistent interface on all platforms. This means that you can have one Win32 application and have it operate on all of the supported platforms.

 

Other Features
 Driver buffering (queuing) of received packets by the NDIS IM driver.

 

Sample Applications
Here are the current test applications provided to test the IP Packet Redirector sample:

 PRTest1 - Illustrates setting an IP Filter to block sending of selected IP packets.
 PRTest2 - Monitors selected IP packets as they are being sent.
 PRTest3 - Redirects selected PING requests to Win32 where they are echoed.
 PRTest4 - Monitors reception of selected IP packets as they are received.
 PRTest5 - All IP packets sent or received are looped through a Win32 application.

These are Win32 console applications.

For some tests you must use Ctrl-C to exit the program. This is a simple way to terminate the application and has the additional virtue of testing the driver I/O cancellation and cleanup logic.

 



Building The Drivers
It is intended that NIM will employ single-source driver sources. So far this has been achieved for:

 Windows Millennium
 Windows NT 4.0
 Windows 2000
 Windows XP

Although a single set of sources is used to build both drivers, there are differences that must be accommodated at compile time. These differences are controlled by preprocessor variables initialized in the SOURCES file used to build the driver:

 NDIS40 - For building using NDIS 4.0 specific features.
 NDIS50 - For building using NDIS 5.0 specific features.
 NDIS51 - For building using NDIS 5.1 specific features.
 NDIS_WDM - For building with WDM support. For the Windows NT build this variable is NOT defined.

In addition, there are further differences that must be accommodated at run-time. These are distinguished, to the extent possible, by using a WDM version check based on IoIsWdmVersionAvailable.

The DDK BUILD tools can be used to build different drivers from the same set of source files. The technique used by PCAUSA to allow single-source builds is to move the SOURCES and MAKEFILE to a DDK-specific subdirectories under the driver sources directory.

The Table below lists the build environments for each of the NIM drivers:

Windows Platform Build Directory DDK For Build
Windows Millennium MEBuild Windows 2000 DDK
Windows NT 4.0 NTBuild Windows NT 4.0 DDK
Windows 2000 W2KBuild Windows 2000 DDK
Windows XP XPBuild Windows XP DDK

 

To build the NIM driver for a particular target Windows platform first run the DDK Build Environment listed in column 3. Then change to the Build Directory listed in column 2 and build from there.

PCAUSA is also considering implementing a binary-compatible driver for all platforms except Windows NT.

 



Installing The Drivers
Installation of NDIS Intermediate Drivers is actually a substantial problem, and can easily consume up to fifty-percent of the development effort.

Can\'t say enough about this... Later!!!

 Do understand that one of the as yet unrealized objectives of the Universal NDIS Intermediate Driver Samples is to make significant improvements to the NDIS IM driver installation procedures.

The current directions for installing the platform-specific NDIS Intermediate Drivers can be found by following the links below:

 Installation Of The Windows Millennium NDIS Intermediate Driver
 
 Installation Of The Windows NT NDIS Intermediate Driver
 
 Installation Of The Windows 2000 NDIS Intermediate Driver
 
 Installation Of The Windows XP NDIS Intermediate Driver
 

 



Testing The Drivers
Observe Debug Messages
If you have installed the Debug binaries, then you can observe debug output messages that confirm operation of the driver.

Here are some sample messages from the Windows 2000 NIM driver:

 

================ Wed Nov 01 21:02:38 2000
PCASIM: DeviceName: \"\\Device\\PCASIMWDM
PCASIM: SymbolicName: \"\\DosDevices\\PCASIMWDM
PCASIM: CLPnPHandler
PCASIM: CLBindAdapterHandler: Entry...
PCASIM: LowerAdapterName:
\\DEVICE\\{B76397B8-766E-40C3-8E46-011414D5DB97}
PCASIM: ProtocolSection:
PCASIMCL\\Parameters\\Adapters\\{B76397B8-766E-40C3-8E46-011414D5DB97}
PCASIM: UpperBindings DeviceInstance:
\\Device\\{22418E9D-A480-493B-87DC-54EA94D9C1B9}
PCASIM: LowerAdapterName:
\\DEVICE\\{B76397B8-766E-40C3-8E46-011414D5DB97}; Adapter: 0x82BABBA8
PCASIM: VirtualAdapterName:
\\Device\\{22418E9D-A480-493B-87DC-54EA94D9C1B9}; Adapter: 0x82BABBA8
PCASIM: CLOpenAdapterComplete: Adapter: 0x82BABBA8
PCASIM: HeaderSize: 14
PCASIM: FrameSize: 1500
PCASIM: TotalSize: 1514
PCASIM: CLPnPHandler
PCASIM: CLPnPNetEventReconfigure
PCASIM: CLPnPHandler
PCASIM: CLPnPHandler
PCASIM: CLPnPNetEventReconfigure
PCASIM: CLPnPHandler
PCASIM: MPInitialize: ConfigStatus: 0x00000000
PCASIM: MPInitialize: Adapter: 0x82BABBA8
PCASIM: Lower Adapter Options: 0x0000000D
PCASIM: Virtual Adapter Options: 0x00000005
PCASIM: Lower Adapter Options: 0x0000000D
PCASIM: Virtual Adapter Options: 0x00000005
PCASIM: Lower Adapter Supports Task Offload
PCASIM: CLReceiveIndication: Adapter: 0x82BABBA8
PCASIM: UTILMakePacketFromReceiveIndication: Adapter: 0x82BABBA8
PCASIM: UTIL Alloc/Free(2): 1/0
PCASIM: (82BABBA8) CLTransferDataComplete: Packet FFA79EE8 Status 00000000 Bytes
xfer\'ed 0
PCASIM: MPReturnPacket: Adapter: 0x82BABBA8
PCASIM: UTIL Alloc/Free(2): 1/1
PCASIM: CLReceiveComplete: Adapter: 0x82BABBA8
PCASIM: Lower Adapter Options: 0x0000000D
PCASIM: Virtual Adapter Options: 0x00000005
PCASIM: MPSendPackets: Adapter: 0x82BABBA8
PCASIM: UTIL Alloc/Free(2): 2/1
PCASIM: MPSendComplete: Adapter: 0x82BABBA8
PCASIM: UTIL Alloc/Free(2): 2/2


Using The IMUtil Test Application
The IMUtil test application is a Win32 console application that is used to test the DeviceIoControl interface to the NIM driver. Do understand that the PCAImApi DLL exports functions that support this interface it must be installed.

The IMUtil application performs the following trivial operations intended to illustrate DeviceIoControl communication:

 Opens the NIM driver.
 Queries for the NIM driver description string.
 Fetches the NIM driver capability bitmask.
 Enumerates and displays the NIM bindings (as reported by the NIM driver itself).
 Opens handles to both the NIM virtual (upper-edge) and real (lower-edge) adapters.
 Queries the real adapter for NDIS Medium and current address.

 

IMUtil Output on Windows 2000 Platform
Here is a sample of the output from IMUtil operating on Windows 2000:

PCAUSA Sample NDIS Intermediate Driver (SIM) Utility Version 1.00.00.04
Copyright (c) 1999-2000 Printing Communications Associates, Inc.
All rights reserved.

Driver Description : \"PCASIM - PassThru Sample IM Driver\"

Virtual AdapterName: \"\\Device\\{22418E9D-A480-493B-87DC-54EA94D9C1B9}\"
Opened Virtual Adapter

Lower AdapterName: \"\\DEVICE\\{B76397B8-766E-40C3-8E46-011414D5DB97}\"
Opened Lower Adapter
Medium: 802.3 (0x00000000)
Current Address: 00-D0-59-0D-A2-46
 

IMUtil Output on Windows Millennium Platform
Here is a sample of the output from IMUtil operating on Windows Me:

PCAUSA Sample NDIS Intermediate Driver (SIM) Utility Version 1.01.02.08
Copyright (c) 1999-2000 Printing Communications Associates, Inc.
All rights reserved.

Driver Description : \"PCASIM - PassThru Sample IM Driver\"

Virtual AdapterName: \"PCASIMMP\\0000\"
Opened Virtual Adapter

Lower AdapterName: \"0000\"
Opened Lower Adapter
Medium: 802.3 (0x00000000)
Current Address: 00-50-04-87-18-73
 

IMUtil Output on Windows NT 4.0 Platform
Here is a sample of the output from IMUtil operating on Windows NT 4.0:

PCAUSA Sample NDIS Intermediate Driver (SIM) Utility Version 1.01.02.08
Copyright (c) 1999-2000 Printing Communications Associates, Inc.
All rights reserved.

Driver Description : \"PCASIM - PassThru Sample IM Driver\"

Virtual AdapterName: \"\\Device\\PCASIMMP6\"
Opened Virtual Adapter

Lower AdapterName: \"\\Device\\E100B3\"
Opened Lower Adapter
Medium: 802.3 (0x00000000)
Current Address: 00-90-27-8C-B4-91
Virtual AdapterName: \"\\Device\\PCASIMMP5\"
Opened Virtual Adapter

Lower AdapterName: \"\\Device\\E100B4\"
Opened Lower Adapter
Medium: 802.3 (0x00000000)
Current Address: 00-90-27-8C-B4-92

Virtual AdapterName: \"\\Device\\PCASIMMP2\"
Opened Virtual Adapter

Lower AdapterName: \"\\Device\\El90x1\"
Opened Lower Adapter
Medium: 802.3 (0x00000000)
Current Address: 00-60-08-A3-29-D0