TDI_LISTEN

TDI_LISTEN

Operation

TDI_LISTEN is a request message a client issues to indicate a listen request for passive listening to an incoming connection request from a remote node client.

Note TdiBuildListen is the macro a client uses to fill in the IRP.

The internal driver listen function that completes the client listen request can either accept the remote node connection request on behalf of the local node client or defer acceptance or rejection to the client. The latter option is referred to as “delayed connection acceptance” and the client requests it by setting the TDI_QUERY_ACCEPT bit flag when it issues the listen request.

To initiate a listen request successfully, the local node client must have its transport address associated with an idle connection endpoint. It can then issue numerous listen requests, which the TDI driver processes in FIFO order. The driver does not define the order of processing for requests from several clients.

Before making a listen request, a client can register ClientEventReceive or ClientEventReceiveExpedited. If it does this, it can receive TSDUs through events even before the I/O subsystem formally completes a listen request. For this reason, the client must be prepared to accept a connection when it makes a listen request.

The TDI driver cannot call ClientEventConnect as long as a listen request is active for the client address object. However, the driver can call ClientEventConnect if a listen operation is pending but the remote address acceptance criteria prevent the listen operation from being completed.

Along with the request message, the TDI client must provide input and output buffers for the IRP, as well as a status block structure the driver uses to write information about the request. These items are described below. For more information about the members of the IRP related to a listen request, see TdiBuildListen.

Input

A listen request uses a TDI_CONNECTION_INFORMATION structure as an input buffer providing connection information, including options and user data the connection uses or sends. Note the request-specific information the client places in the following members:

Member	Description
UserData	Points to a buffer of data the client sends with an accept request (see TDI_ACCEPT). The client does not use this member if the driver supports delayed connection acceptance and the client has set the TDI_QUERY_ACCEPT bit flag.
UserDataLength	Specifies the length, in bytes, of the data in the UserData member. The client does not use this member if the driver supports delayed connection acceptance and the client has set the TDI_QUERY_ACCEPT bit flag.
Options	Points to a bit flag specifying details about the listen request. Only one bit flag, TDI_QUERY_ACCEPT, is currently defined. This bit flag specifies that the TDI driver returns without accepting the connection from the remote node client. The local node client must then make either an accept request to accept the connection or a disconnect request (see TDI_DISCONNECT) to reject it. If the local node client does not set the TDI_QUERY_ACCEPT flag, the driver automatically accepts the connection.

Note The internal driver listen function returns an error code if the local node client makes a listen request with TDI_QUERY_ACCEPT set and the TDI driver does not support delayed connection acceptance.

OptionsLength	Specifies the length, in bytes, of the data in the Options member. The client does not use this field if the driver supports delayed connection acceptance and the client has set the TDI_QUERY_ACCEPT bit flag.
RemoteAddress	Points to a buffer containing the remote node client transport address to which the local node client listens. The local node client can specify a partial address, as described in the comments below.
RemoteAddressLength	Specifies the length, in bytes, of the data in the RemoteAddress member. A value of zero indicates that a connect request from any remote node client is acceptable.

Output

TDI_CONNECTION_INFORMATION structure

I/O Status Block

The driver fills in the Status member of the IRP with one of the following TDI status codes:

STATUS_INSUFFICIENT_RESOURCES
STATUS_INVALID_CONNECTION
STATUS_PENDING
STATUS_SUCCESS

For more information about status codes, see Part II, Chapter 10.

Comments

Remote node client addressing information acts as a filter that the driver applies before checking the TDI_QUERY_ACCEPT bit flag. If the incoming connect request does not match the address specified in the listen request, the driver listen function cannot finish (regardless of the state of the bit flag). If the connect request matches the address and TDI_QUERY_ACCEPT is set, the driver listen function returns and the local node client must either accept or reject the connect request. If the connect request matches the address and TDI_QUERY_ACCEPT is not set (or the driver does not support delayed connection acceptance), the driver listen function accepts the connection and returns.

The local node client can optionally specify a partial address for the remote node client. TDI drivers vary in their ability to handle partial addresses. Because the syntax of a transport address is TDI driver-specific, the mechanism for specifying a partial address is also specific to the driver.

Another listen option available to the client is specifying of QOS options. The client can do this using a variable-length counted string with TDI driver-specific syntax and semantics.