TDI Library Functions and Macros
Windows 2000 and later versions of the operating system provide a small set of TDI library functions as a kernel-mode dynamic-link library (the tdi.sys export library) with which TDI drivers and kernel-mode clients link themselves. However, most of the system-supplied TdiBuildXxx called by kernel-mode clients are implemented as macros in the tdikrnl.h header that both clients and transports include.
Any kernel-mode TDI client can use the TdiBuildXxx macros as needed in preparing the TDI_XXX IOCTL IRPs, already mentioned in TDI IOCTL Requests. After the client has set up such an IRP with a TdiBuildXxx macro, it submits the request to the underlying TDI driver by passing the IRP to IoCallDriver. Each of these macros fills in the relevant members of the client-provided IRP, except for the Statusand Information members, which the underlying transport fills in after processing its client's request. Before using one of TdiBuildXxx IOCTL macros, a client can call TdiBuildInternalDeviceControlIrpto allocate the IRP if it has not already been allocated by a still higher level network component and given to the client.
A transport driver never uses the TdiBuildXxx macros. However, a TDI driver can use some of the remaining TDI library routines, such as TdiCompleteRequestand TdiCopyBufferToMdl, for assistance in processing client requests.
TDI library routines and macros include the following:
TdiBuildInternalDeviceControlIrp
Allocates an IRP if the client does not receive an IRP from a higher network layer.TdiBuildAccept
Sets up an IRP for a client-submitted TDI_ACCEPT request.TdiBuildAction
Sets up an IRP for a client-submitted TDI_ACTION request.TdiBuildAssociateAddress
Sets up an IRP for a client-submitted TDI_ASSOCIATE_ADDRESS request.TdiBuildConnect
Sets up an IRP for a client-submitted TDI_CONNECT request.TdiBuildDisassociateAddress
Sets up an IRP for a client-submitted TDI_DISASSOCIATE_ADDRESS request.TdiBuildListen
Sets up an IRP for a client-submitted TDI_LISTEN request.TdiBuildQueryInformation
Sets up an IRP for a client-submitted TDI_QUERY_INFORMATION request.TdiBuildReceive
Sets up an IRP for a client-submitted TDI_RECEIVE request.TdiBuildReceiveDatagram
Sets up an IRP for a client-submitted TDI_RECEIVE_DATAGRAM request.TdiBuildSend
Sets up an IRP for a client-submitted TDI_SEND request.TdiBuildSendDatagram
Sets up an IRP for a client-submitted TDI_SEND_DATAGRAM request.TdiBuildSetEventHandler
Sets up an IRP for a client-submitted TDI_SET_EVENT_HANDLER request.TdiBuildSetInformation
Sets up an IRP for a client-submitted TDI_SET_INFORMATION request.TdiBuildNetbiosAddress
Sets up a NetBIOS address for a client.TdiBuildNetbiosAddressEa
Sets up a buffered NetBIOS address that a client can pass subsequently to ZwCreateFile to open the address.TdiReturnChainedReceives
Relinquishes control of the buffer that was passed to a ClientEventChainedReceive(Xxx) handler after the client has consumed the received TSDU.TdiCopyBufferToMdl
Copies a range of buffered data into a destination buffer mapped by a given MDL.Both clients and transports can use this function.
TdiCopyMdlToBuffer
Copies data from buffers mapped by a given MDL into a caller-supplied destination buffer.Both clients and transports can use this function.
TdiCopyLookaheadData
Safely copies received data indicated to the transport by a NIC driver, whatever the nature of the memory (including mapped device memory) that the NIC is using.TdiMapUserRequest
Converts an IRP passed in to a transport's TdiDispatchDeviceControl routine into a TDI_XXX IOCTL IRP if TdiMapUserRequest recognizes the minor function code specified in the input IRP.TdiCompleteRequest
Completes an IRP with the system-defined network-specific priority boost for a transport driver.TdiRegisterPnPHandlers
Registers a set of ClientPnPXxx routines with TDI to receive notifications of PnP binding-change, network-address-change, and power-state-change events from underlying PnP-aware TDI transports.TdiDeregisterPnPHandlers
Removes a set of ClientPnPXxx routines from being notified about subsequent PnP binding-change, network-address-change, and power-state-change events.TdiRegisterProvider
Registers a PnP-aware transport driver for Windows 2000 and later versions with TDI during system startup.TdiProviderReady
Indicates a PnP-aware transport driver's readiness to carry out network I/O on one or more newly established transport-to-NIC bindings.TdiDeregisterProvider
Deregisters a PnP-aware transport driver just before it unloads.TdiRegisterDeviceObject
Registers a named, transport-created device object that the clients of such a PnP-aware transport can subsequently "open" for network I/O. In effect, such a transport's call to this TDI function notifies all potential clients of this transport that it has just established a new transport-to-NIC binding.TdiDeregisterDeviceObject
Deregisters a transport-created device object when a PnP-aware transport is tearing down a binding.TdiRegisterNetAddress
Registers a valid network address that a PnP-aware transport has just created for the local machine or has just obtained when establishing a connection to a remote node on a particular binding. In effect, a PnP-aware transport's call to this TDI function notifies its potential clients that they (or their remote-node peers) can subsequently use this protocol-specific address for network communications.TdiDeregisterNetAddress
Removes a network address from the list of those valid on a particular PnP-aware transport-to-NIC binding.TdiPnPPowerRequest
Forwards certain NET_PNP_EVENT-type notifications (by NDIS to the lower edge of the transport stack) to a PnP-aware transport's clients. In effect, a PnP-aware transport's call to this TDI function gives its clients the opportunity to notify their own still higher level clients about binding changes or power-state changes to the underlying NIC on which the transport depends.TdiPnPPowerComplete
Indicates that a client has completed its processing of a binding-change or power-state-change notification for which it previously returned STATUS_PENDING.TdiEnumerateAddresses
Returns a list of all valid network addresses to the calling client. (This TDI function is almost never called because it has a severe adverse effect on the caller's performance.)
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).