5.2 Opening a Connection Endpoint

Figure 5.2 shows how a kernel-mode client opens a connection endpoint in its underlying transport driver.

Figure 5.2 Opening a Connection Endpoint

If a local-node client requires connection-oriented communication with a remote-node peer process, the local-node client must first open a transport address and then open a connection endpoint in its underlying transport. The client makes two calls to ZwCreateFile, first to open an address and, then, a connection endpoint.

When opening a connection endpoint, the client passes a client-supplied context for the connection in the EA (extended attributes) buffer parameter to ZwCreateFile. Within the EA buffer, the client sets the EaName member to the system-defined value TdiConnectionContext followed by an EA value that is usually the address of a client-allocated context area in which the client will subsequently maintain state about the endpoint-to-endpoint connection to be established.

The client's call to ZwCreateFile causes the I/O Manager to create a client-process-specific file object to represent the connection endpoint 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 connection endpoint of 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 the underlying transport to establish an endpoint-to-endpoint connection with a remote-node peer.

First, the client must associate the connection endpoint with its open transport address by submitting a TDI_ASSOCIATE_ADDRESS request, set up with TdiBuildAssociateAddress, to its underlying transport.

For more information about setting up TDI_XXX IOCTL IRPs, see Section 5.3, next. For more information about how to establish an endpoint-to-endpoint connection, see Section 5.5.

When the endpoint-to-endpoint connection has been disconnected and the client no longer will use any connection-oriented communications, the client must close the connection endpoint by passing the file handle that was returned by ZwCreateFile to ZwClose, as described later in Section 5.12.