Opening a Transport Address
The following figure shows how a kernel-mode client opens a transport address in its underlying transport driver.
.png)
After opening a transport-created device object for a binding, a TDI client usually begins communicating with its local-node transport by opening a file object that represents a transport address. To do this, the client calls ZwCreateFile, passing the address specification in the EA (extended attributes) buffer parameter to ZwCreateFile. Within the EA buffer, the client sets the EaName member to the system-defined value TdiTransportAddress followed by an EA value of the TDI-defined type TRANSPORT_ADDRESS, set up by the client to specify the transport-specific address to be opened.
The client can specify that a particular transport address be either sharable with other clients or exclusive to the client when it calls ZwCreateFile. The initial client to successfully open a particular transport address for exclusive use prevents other clients from opening the same address until the original client closes that address.
To do subsequent connectionless communication over the network, the client can specify the underlying transport's broadcast address in the EA buffer, assuming the transport supports broadcast datagrams. Such an address cannot be opened for exclusive use by any client.
The client's call to ZwCreateFile causes the I/O manager to create a client-process-specific file object to represent the address and to call the TDI transport driver's TdiDispatchCreateroutine with an IRP containing the client-supplied parameters to ZwCreateFile. TdiDispatchCreate parses the EA information, and the transport sets up internal state for the open address and for this client if the call succeeds.
After its successful call to ZwCreateFile returns a file handle to the client and the client has obtained a pointer to the file object with ObReferenceObjectByHandle, it is ready to make certain TDI_XXXIOCTL requests to its underlying transport. For example, the client can send or receive datagrams on such an open address.
Usually, a client must first decide whether to register one or more of its ClientEventXxx handlers and whether it will use the open address to communicate with a remote-node peer process, in which case the client also must open a connection endpoint.
If the client wants to receive notifications of various network events, it can register its ClientEventXxx handler for each type of event by submitting one or more TDI_SET_EVENT_HANDLERrequests, set up with TdiBuildSetEventHandler, to the underlying transport. For more information about setting up IOCTL requests and submitting them to an underlying transport, see Packaging and Submitting IOCTL Requests.
After the client has registered its ClientEventXxx handlers, if any, on the open transport address, it is ready to make preparations for connection-oriented communication by opening a connection endpoint, as described in Opening a Connection Endpoint, or to begin connectionless communication, as described in Sending and Receiving Connectionless Data.
When it is done with network communications on the opened transport address, the client must close the file object that represents that transport address by calling ZwClose with the handle returned by ZwCreateFile, as described later in Closing a Transport Address or Control Channel.
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).