|
|
|
|
|
 | TCI Client Samples Overview |
| TDI Filter Samples Overview |
| Downloading Additional Documentation |
| Downloading Demonstration Executables |
| Licensing Information |
| Pricing Information |
A major goal of these samples is to illustrate how to add TDI client functionality into your own Windows driver. The product includes provides several TDI client driver samples, including:
| TDI Test TCP (TTCP)
| ||||||||
| TDI Echo Server
| ||||||||
| TDI Query Test Driver
|
The TDI client Samples illustrate these basic TDI operations:
| Opening A Transport Address | ||||||||
| Opening A Connection Endpoint | ||||||||
| Making An Endpoint-To-Endpoint Connection
| ||||||||
| Sending And Receiving Connection-Oriented Data (TCP) | ||||||||
| Sending And Receiving Connectionless Data (UDP) | ||||||||
| Disconnecting An Endpoint-To-Endpoint Connection | ||||||||
| Closing A Connection Endpoint |
The TDI Client Samples also illustrate these more advanced TDI Operations
| Sending Chained MDLs | ||||||||
| Querying TDI Information
| ||||||||
| Querying Extended TCP Information
| ||||||||
| Setting TDI Information (Limited) |
Most of the TDI Client Samples are capable of handling multiple concurrent connections.
PCAUSA provides companion Winsock and Win32 applications used to test and control operation of the sample drivers.
For example, a Winsock TTCP application is provided as a companion to the TDI TTCP driver sample. This allows you to see both the user-mode and the kernel-mode implementation of similar functions.
The implementation of the PCAUSA TDI client samples employs thin API over the basic TDI request interface. The functions provided by the TDI Kerned Support (KS) Library are intended to make TDI client development a little easier. The KS library routines provide a thin layer over the low-level TDI API (after all, who cares how an extended attribute buffer is built...), but don't totally obscure their intended use.
Also see the topic Why We Don't Provide a "Kernel Sockets" Framework.
The thin KS library API has been well received by PCAUSA customers since it was introduced in early 2000 and has been used in a wide variety of shipping commercial applications.
A Programmers Reference to the KS library routines is provided.
Filtering of TDI operation is required for a variety of applications including:
| Firewalls |
| Email Scanning |
| Monitoring Data (Not Packets) on Specified IP Addresses and Ports |
| Monitoring Data (Not Packet) on the IP Loopback Address (127.0.0.1) |
PCAUSA provides several TDI filter samples intended to provide insight into practical approaches to filter TDI.
It should be emphasized that TDI filtering is not simple for a variety of reasons:
| Although the basic TDI API for normal TCP and UDP
operations is fairly well documented in the DDK, the API employs fairly
sophisticated kernel-mode programming techniques that may not be familiar to
many Windows driver programmers. |
| Writing of any filter driver requires that the
filter-writer be thoroughly familiar with the behavior of the higher-level
devices (e.g., the TDI clients) that are to be filtered. Many TDI
filter-writers do not take the time to understand how TDI clients operate
before they begin writing a filter. |
| The TDI API for normal TCP and UDP operations is
extremely flexible. For many operations there are several different APIs that
can be used either alone or in combination to achieve the same result (e.g.,
to receive TCP stream data). It difficult for a filter-writer to anticipate
the possible API combinations that may be invoked by the TDI client being
filtered. |
| There are IRQL and API limitations that make it
difficult to pend or delay some TDI operations. |
| There are potential interactions between TDI filters
and anti-virus or firewall products. |
| Microsoft-proprietary undocumented APIs are used for some special purposes such as VPN tunneling. |
Despite these difficulties TDI filters may be the only solution that can be used to satisfy some requirements. The PCAUSA TDI samples certainly provide a starting point for TDI filter development if it is required.
PCAUSA provides two different pass through TDI filter samples. Both of these are "monitoring" filters that do not modify data. In general monitoring data, as well as blocking connections and datagrams, are operations that can be achieved reliably for TCP and UDP. Modifying TCP or UDP data (in any filter including - the much simpler NDIS IM driver...) is an advanced topic beyond the scope the PCAUSA TDI filter samples.
| Layered Pass Through TDI Filter - Uses IoAttachDeviceToDeviceStack. |
| Dispatch-Hooking Pass Through TDI Filter - Manipulates the Tcpip Dispatch table. |
The Pass Through TDI filter samples provides functions that support filtering of these TDI operations and their completion functions (when appropriate):
| TdiOpenAddress, TdiCloseAddress |
| TdiOpenConnection, TdiCloseConnection |
| TdiSetEvent |
| TdiConnect, TdiDisconnect |
| TdiAssociateAddress, TdiDisAssociateAddress |
| TdiSend, TdiReceive |
| TdiReceiveEventHandler, TdiChainedReceiveEventHandler |
| TdiSendDatagram, TdiReceiveDatagram |
| TdiReceiveDGEventHandler, TdiChainedReceiveDGEventHandler |
The TDI filter samples include code to associate, to the extent practical, the process that owns each new TDI Address Object. For TCP and UDP operations the TDI filter samples illustrate fetching the local and remote IP address and port for most operations.
Operation of the Layered Pass Through TDI Filter can be observed with a debugger. See an Example TDI Filter Trace.
Additional TDI filter samples are provided that build on the basic functionality of the pass through TDI filters. These include:
| Loopback Data Monitor - Logs data sent and received on 127.0.0.1 to the console. |
| Remote Port Data Monitor - Logs data sent and received on a specific remote port to the console. |
| TCP/UDP Port Blocker - Selectively
blocks incoming and outgoing TCP connections and UDP datagram traffic. Click here for more information.  |
| Outgoing TCP Connection Redirector - Can
redirect selected connection attempts to local proxy. Click here for more information. |
An example of the operation of the Remote Port Data Monitor is monitoring email sent via a SMTP server:
| Email Sent |
| Data Logged on SMTP Port |
The PCAUSA TDI Filter samples illustrate attaching a filter driver over the MSTCP driver's \Device\Tcp and \Device\Udp devices. Most normal TCP and UDP data is transferred over these devices.
MSTCP exports additional devices which are basically Microsoft proprietary or largely undocumented. These devices provide support for the Microsoft Virtual Private Network (VPN) tunnels as well as IP support operations (e.g., ICMP, etc.).
The PCAUSA TDI Filter Samples do NOT provide information on these Microsoft proprietary MSTCP devices.
The current TDI Client and TDI Filter samples have been tested to the extent practical on the most current Windows versions available as of the release date. The current samples have been developed and tested on systems up to and including 4-way Windows Server 2003 systems.
Most TDI Client and TDI Filter samples can be built for and run on NT systems ranging from Windows NT 4.0 through Windows Server 2003.
Some of the TDI Filter samples can be optionally built to use OS enhancements introduced with Windows XP. For example, the TDI Loopback Data Monitor (TDILpbkH) can be built to use the queued spin lock feature available with Windows XP and higher.
The term "sockets" appears to be a magic word in the world of network programming. It suggests a standard network programming interface that is intended to be portable across a wide variety of platforms. Judging by questions on various newsgroups and mailing lists related to "porting" sockets applications from one platform to another, the "portability" of sockets applications seems far from perfect.
In the specific case of Winsock, it is only after a sockets application has been "successfully" ported to Winsock that the developer realizes that the use of Microsoft-specific Winsock facilities (WSA..., IOCP, etc.) must be (or should be) used to extract maximum performance on the platform.
In addition, it should be remembered that the sockets API is a user mode API.
On the other hand, kernel mode network programming on any platform is significantly different from user mode programming.
The Transport Data Interface (TDI)
is
the Windows native networking API.
In PCAUSA's judgment, TDI is well suited to network programming in kernel mode, and wrapping the NT native kernel mode networking API in a "kernel sockets" API would obscure its intended use. In addition, it would only be after a sockets application had been "successfully" ported to "kernel sockets" that the developer realizes that the use of TDI-specific facilities must be (or should be) used to extract maximum performance in the kernel environment.
So, no "kernel sockets" from PCAUSA...
It is your responsibility to setup the device driver build environment. In addition, it is your responsibility to learn the general techniques used to build and debug Windows NT device drivers.
If this is your first experience in device driver development, it is likely that you will encounter problems in simply setting up the Device Driver Kit (DDK). Some of these problems can be very frustrating to the uninitiated. When you undergo these trials for the first time, please have patience.
The Advanced TDI Samples can be built under:
| NT 4.0 Target - Windows NT 4.0 Device Driver Kit |
| Windows 2000 or Higher Target - Windows 2000 Build Environment of the Windows Server 2003 DDK |
There are several Window DDK versions that include the Windows 2000 Build Environment. However, PCAUSA currently uses and recommends the Windows 2000 Build Environment provided by the Windows Server 2003 DDK (Build 3790).
It is strongly recommended that you have separate executables for each of the two target platforms compiled under the appropriate DDK.
A programmer intending to write TDI Clients or TDI Filters should have prior experience in development and debugging of Windows NT device drivers.
Some of the techniques used the TDI API are not encountered in typical Windows NT device drivers and/or are weakly described in Microsoft documentation and DDK samples. The following intermediate-level device driver programming topics are involved in TDI device drivers:
| Extended Attributes |
| Handmade IRPs |
| Memory Descriptor Lists (MDLs) |
| Asynchronous Inter-Driver Calling Methods |
| Kernel Threads |
| Attention To IRQL Restrictions |
| Attention To Process/Thread Context Restrictions |
TDI filter driver writers must also understand the architecture of the Windows NT layered device driver model and techniques used to filter IRPs.
The product includes:
| Over 100 pages of documentation, provided in HTML Help format |
| Over 15,000 lines (250 pages) of heavily commented driver sample code |
| Complete source code to all sample drivers |
You can download and review the TDI Sample documentation using the link below.
Download TDI Sample
HTML Help Documentation 
You can also view the current Release Notes.
You can download executable versions of several TDI driver samples. Clicking on the links below should activate your email client to send an empty request message to PCAUSA. You'll need to read the Terms And Conditions and enter your Contact Information before receiving an autoresponder email that will provide the URL to download the sample executables.
Your Contact Information will only be used by PCAUSA, primarily to determine if there is sufficient interest to maintain the software on the PCAUSA website.
You can download the executable versions of this TDI client sample driver:
| Test TCP (TTCP) TDI Client - Uses a TDI client to implement the Test TCP (TTCP) suite of performance benchmarking tests. This sample illustrates use of TCP and UDP for sending and receiving from a kernel-mode driver. |
The PCAUSA TDI Client Demo Executables can be downloaded as a ZIP from the following URL:
TDIClientDemo.zip
267.77KB (274198 bytes)After unzipping the file, please read the documentation in the Readme.htm files in this folder:
\PCADemo\TDI Samples\TDI Clients\TTCP
You can download the executables for two sample TDI filters:
| TDI Loopback Data Monitor - Uses a TDI filter to log TCP data sent and received on the loopback (127.0.0.1) address. |
| TDI Remote Port Monitor - Uses a TDI filter to log TCP data sent and received on a specified remote port such as SMTP, POP3 or HTTP. |
The PCAUSA TDI Filter Demo Executables can be downloaded as a ZIP from the following URL:
TDIFilterDemo.zip
143.87KB (147320 bytes)After unzipping the file, please read the documentation in the Readme.htm files in these folders:
\PCADemo\TDI Samples\TDI Filters\Loopback Monitor
\PCADemo\TDI Samples\TDI Filters\Remote Port Monitor
If you find bugs in these samples or wish to suggest improvements, please let us know.
The product includes a royalty-free license to incorporate sample code into your executable products. Please review the PCAUSA License Agreement and Limited Warranty.
PCAUSA offers the Advanced TDI Samples with a variety of terms and conditions.
|
Advanced TDI Samples For Windows NT, Windows 2000 and Higher |
||||||||||||||||||||||||||||||||||||
|
Prices good through June 30, 2008.
3/27/06
|
PCAUSA Home ·
Privacy Statement ·
Products ·
Ordering ·
Support ·
Utilities ·
Resources
|
