Transport Driver Interface
The following figure shows the general relationship between TDI clients and transport drivers.
As this figure shows, the Transport Driver Interface (TDI)defines a kernel-mode network interface that is exposed at the upper edge of all transport protocol stacks. The highest level protocol driver in every such stack supports the TDI interface for still higher level kernel-mode network clients.
This interface includes the following:
A set of standard kernel-mode intermediate driver Dispatch routines exported by each TDI transport driver to which clients can submit I/O requests (IRPs) by making calls to support routines, such as the Zw..File routines or IoCallDriver
A set of ClientEventXxx callback routines exported by each TDI client that can be registered with the underlying transport driver to receive notifications of specific network events when they occur
A set of ClientPnPXxx callback routines exported by TDI clients that can be registered with TDI to receive notifications of dynamic binding, network address, and power-state changes from PnP-aware transports for Windows 2000 and later versions of the operating system.
Parameters, structures, IOCTLs, and procedural rules associated with these TDI transport and ClientEventXxx and ClientPnPXxx routines
A set of system-supplied TdiXxx functions that transports and clients can call to communicate with each other
A set of system-supplied TdiBuildXxx macros and functions that clients can use to set up I/O requests to be submitted to their underlying transports
Requiring that all transport drivers expose a single common interface (TDI) simplifies the task of transport driver development in that all transports need code to support only a single defined interface. It also simplifies the task of client development by minimizing the amount of transport-specific code that must be written.
Windows 2000 and later versions of the operating system include interface modules for several popular network interfaces, such as Windows Sockets and NetBIOS. Each of these interface modules exposes a native set of primitive functions, which are accessible through standard calls from user mode. When called, the interface module maps the native (frequently user-mode) function and its associated parameters and procedural rules, to one or more calls to the underlying TDI transport driver.
Key features of TDI include the following:
- High Level of Granularity
TDI accommodates all primitives and conventions from existing popular network interfaces because it is relatively granular in nature, with several small TDI-defined requests that can be mixed and matched to accommodate mapping from existing network-interface functions.
- Asynchronous Operation
Most kernel-mode TDI operations are asynchronous, using client-supplied callback routines to indicate asynchronous network events as they occur and completing most client-initiated operations submitted as IRPs asynchronously as well.
- 32-bit Addressing and Values
Like all kernel-mode components for Windows 2000 and later versions, TDI transports and their clients are 32-bit code. TDI-defined structures and parameters use 32-bit pointers and values.
- Flexible Addressing Scheme
TDI does not mandate any particular address format, such as the 16-character NetBIOS name defined for legacy operating systems. Instead, it features an extensible mechanism by which many address formats can be identified and used.
- Extensible Communication
TDI defines a TDI_ACTION IOCTL request that any TDI transport can use to support a set of transport-determined operations initiated by requests from its clients. This allows the client to submit transport-specific requests to the underlying transport driver that are not expressly defined by TDI.
- Event Notification
TDI defines a scheme by which transports can notify their clients of interesting events that occur on the network without requiring the client to submit an explicit I/O request. For certain types of events, such as connects, disconnects, and receives, the transport driver can indicate data along with the event notification when it calls its client with such a notification.
- Plug and Play Event Notifications
TDI defines a scheme by which transports for Windows 2000 and later versions can notify their clients of certain PnP events, such as the availablity of underlying NICs and the creation/deletion of connections on local network addresses.
- System Power-State Change Notifications
TDI defines a scheme by which transports for Windows 2000 and later versions can notify their clients of proposed system power-state changes, thereby giving the client an opportunity to keep an active connection powered up.
The following features can be supported by a TDI transport driver as additional options:
- Data Transfer Modes
TDI supports sending and receiving data as discrete messages (message mode) or as a stream of bytes (byte-stream mode). Support for either mode (or both) depends on the transport driver writer or on the nature of the protocol.
- Internal Buffering
TDI transports can buffer their client's sends and receives internally. Transport-internal buffering allows the TDI client to set and query driver internal buffer sizes, request nonblocking send operations, receive notification of available buffer space, and look at (peek) buffered data before receiving it.
- Management Options
All transports maintain some TDI-defined state about their respective features, limits, and run-time statistics. This allows each client to dynamically query and, in some cases to set, transport-provider static information, statistics, and configuration parameters. In addition, the extensible TDI_ACTION IOCTL, mentioned previously, allows any TDI transport driver to implement unique network-management features that can be accessed by its clients through action requests to the transport.
- Quality of Service (QoS)
TDI transports can provide QoS negotiation upon establishment of a network connection. In addition, such a driver can support QoS for connectionless datagram transmission. To support either, TDI-defined connection-establishment and datagram-send requests include Options and OptionsLength parameters that allow a TDI client to include a transport-specific, variable-length counted string specifying QoS options.
In fact, the Options and OptionsLength parameters can be used to pass any transport-specific connection- or datagram-related options to the transport driver at the discretion of the driver writer, not just QoS specifications.
- Expedited Delivery
When sending messages, the client can flag particular messages as expedited. At the sending side, the underlying transport sends these messages ahead of nonexpedited messages. At the receiving side, expedited messages are indicated to the client before or separate from nonexpedited messages.
- Chained Receive Indications
If the underlying NDIS miniport drivers support multipacket receive indications, a TDI transport can give its clients direct read-only access to a full TSDU in a single call, and the client can retain control of the buffer containing the TSDU until it has consumed the indicated data. This feature improves the performance of both transport and client by cutting down on call overhead for receive indications.
Note The TDI feature is deprecated and will be removed in future versions of Microsoft Windows. Depending on how you use TDI, use either the Winsock Kernel (WSK) or Windows Filtering Platform (WFP). For more information about WFP and WSK, see Windows Filtering Platform and Winsock Kernel. For a Windows Core Networking blog entry about WSK and TDI, see Introduction to Winsock Kernel (WSK).