TDI Client Callbacks
Most TDI clients' routines are highly variable and environment-dependent. However, TDI defines a set of callback routines that clients can register with the underlying TDI transport to receive notifications when network events of interest occur. A kernel-mode TDI client can register any of these ClientEventXxx routines if the TDI driver is to notify it of a particular type of network event occurrence. The client can even use such a registered ClientEventXxx handler as an alternative to issuing certain TDI_XXX IOCTL requests to the driver.
Like the TdiDispatchXxx routines described already, the client-supplied event handlers can have any names the client writer chooses. Each ClientEventXxx mentioned here is registered as an entry point passed in a client-supplied IRP submitted to the TdiDispatchInternalDeviceControl routine.
A TDI client can have one or more of the callbacks listed next, registered at the beginning of network operations on an open transport address with the TDI transport driver by issuing successive TDI_SET_EVENT_HANDLERrequests, set up with TdiBuildSetEventHandler:
ClientEventConnect
Notifies the client of a connection offer from a remote-node peer process.ClientEventDisconnect
Notifies the local-node client that its remote-node peer is terminating the endpoint-to-endpoint connection between them.ClientEventErrorand/or ClientEventErrorEx
Notifies the client of an error condition in its underlying transport driver, in one of the lower protocol layers of the transport stack, or in a still lower NDIS driver that has made subsequent I/O on the client's open transport address unreliable or even impossible.ClientEventReceive
Notifies the client that its transport has received normal data from the remote-node peer on an endpoint-to-endpoint connection and makes all or part of the received data available to be copied by the client.ClientEventChainedReceive
Notifies the client that its transport has received a normal TSDU from the remote-node peer on an endpoint-to-endpoint connection and makes the full TSDU available for consumption by the client.ClientEventReceiveExpedited
Notifies the client that its transport has received expedited data from the remote-node peer on an endpoint-to-endpoint connection and makes all or part of the received data available to be copied by the client.ClientEventChainedReceiveExpedited
Notifies the client that its transport has received an expedited TSDU from the remote-node peer on an endpoint-to-endpoint connection and makes the full TSDU available for consumption by the client.ClientEventReceiveDatagram
Notifies the client that the TDI driver has received a datagram directed to a transport address that the client has opened.ClientEventChainedReceiveDatagram
Notifies the client that the TDI driver has received a datagram directed to a transport address that the client has opened and makes the full TSDU available for consumption by the client.ClientEventSendPossible
Notifies the client that the transport, which buffers send data internally, again has buffer space available for sends.
TDI clients for Windows 2000 and later versions can also register a set of ClientPnPXxx callbacks with TDI to receive notifications of dynamic PnP binding-change, net-address-change, and power-state-change events from PnP-aware TDI transports. Like the ClientEventXxx handlers, these client-supplied PnP event handlers can have any names the client writer chooses.
Such a TDI client for Windows 2000 and later has the set of callbacks listed next, which are registered with a call to TdiRegisterPnPHandlerswhen the client initializes itself:
ClientPnPBindingChange
During system startup, TDI calls this routine to notify the client of all available transport-created named device objects that represent transport-to-NIC bindings, again when each such PnP-aware TDI transport indicates its readiness to carry out network data transfers on its bindings, and again when all possible TDI transport-to-NIC bindings have been established.During run time, TDI calls this client routine whenever a PnP-aware transport registers another device object to represent a newly established transport-to-NIC binding or deregisters an existing device object while tearing down a binding. TDI also calls this client routine if the end user makes binding-list-order changes in the network connections folder.
ClientPnPAddNetAddress
During system startup, TDI calls this routine to notify the client of all network addresses currently registered with TDI by PnP-aware transports on their established bindings. Subsequently, TDI calls this client whenever a PnP-aware transport registers a new network address (usually for a newly established connection to a remote node) on an established binding.ClientPnPDelNetAddress
TDI calls this routine to notify the client whenever a PnP-aware TDI transport deregisters an existing network address (usually when breaking a connection to a remote node) on an established binding.ClientPnPPowerChange
TDI calls this routine to notify the client of proposed NIC removals and of proposed system-power-state changes that could affect that client's ability to transfer data over the network on a particular binding.
A client that registers such a set of ClientPnPXxx handlers with TDI typically maintains dynamic state, usually as one or more internal lists, about all valid network addresses on the bindings of all TDI transports it uses to communicate over the network.
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).