5.1 Opening a Transport Address

Figure 5.1 shows how a kernel-mode client opens a transport address in its underlying transport driver.

Figure 5.1 Opening a Transport Address

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 TdiDispatchCreate routine 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 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_XXX IOCTL 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_HANDLER requests, set up with TdiBuildSetEventHandler, to the underlying transport. For more information about setting up IOCTL requests and submitting them to an underlying transport, see Section 5.3.

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 Section 5.2, or to begin connectionless communication, as described in Section 5.7.

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 Section 5.13.