TDI_CONNECTION_INFORMATION

TDI_CONNECTION_INFORMATION

typedef struct _TDI_CONNECTION_INFORMATION {

LONG UserDataLength;

PVOID UserData;

LONG OptionsLength;

PVOID Options;

LONG RemoteAddressLength;

PVOID RemoteAddress;

} TDI_CONNECTION_INFORMATION, *PTDI_CONNECTION_INFORMATION;

TDI_CONNECTION_INFORMATION defines the structure of information that a kernel-mode client passes to or receives from the underlying transport for a subset of the TDI_XXX internal-device-control requests, particularly those relevant to endpoint-to-endpoint connections.

Members

UserDataLength

Specifies the size in bytes of the buffer at UserData or zero if UserData is NULL.

UserData

Points to client-supplied buffer for user data, generally sent or received when an endpoint-to-endpoint connection is being established or, possibly, disconnected.

OptionsLength

Specifies the size in bytes of the buffer at Options.

Options

Points to a client-supplied buffer, either containing client-supplied data or awaiting transport-returned data for the given IOCTL request.

RemoteAddressLength

Specifies the size in bytes of the buffer at RemoteAddress.

RemoteAddress

Points to a buffer containing a remote-node transport address either specified by the client or returned by the transport to the client. The syntax of this address depends on the type of network and/or the underlying transport (see TA_ADDRESS).

Comments

While several TdiBuildXxx macros and the corresponding TDI_XXX IOCTL requests use this structure to pass information between TDI transports and their clients, each does not use every member of the TDI_CONNECTION_INFORMATION structure.

As a general rule, a transport does not return any information in this structure if it returns STATUS_PENDING for a given IOCTL request. Instead, the driver defers setting the data in this structure until just before it completes the IRP.

Supplying and Receiving UserData

After an endpoint-to-endpoint connection is established, a local-node client can send TSDUs to its remote-node peer by submitting TDI_SEND requests to the underlying transport. The local-node client can either receive TSDUs from its remote-node peer by submitting TDI_RECEIVE requests or through calls to its registered ClientEvent(Chained)Receive(Expedited) handlers.

However, until such a connection is established, two TDI clients in the process of establishing an endpoint-to-endpoint connection can send data to each other by supplying it in a buffer at UserData with their TDI_CONNECT, TDI_LISTEN, and, possibly, TDI_ACCEPT requests to their respective underlying transports. In a similar manner, two such clients also can supply disconnection data to each other in the process of controlled-disconnect operation, assuming their respective transports support controlled disconnections.

A client can determine the transport-specific limit on the amount of user data by submitting a query-information request, set up with TdiBuildQueryInformation for the QType TDI_QUERY_PROVIDER_INFO.

When the client can send user data with a particular TDI IOCTL request, a UserDataLength set to zero implies that the client has provided no user data in its request to the transport. When the client can receive user data with a particular TDI IOCTL request, a UserDataLength set to zero implies that the transport returned no data in the buffer at UserData. Otherwise, the transport sets UserDataLength to the number of bytes of data it received for the client.

If the client specifies a nonzero UserDataLength and the transport receives more data from the remote node than it can fit into the client-supplied buffer, the transport returns as much data as it can in the client's buffer. In this case, the transport completes the operation normally but returns a status indicating data truncation to its client.

UserDataLength must be zero and UserData must NULL for the following TDI_XXX IOCTL requests:

TDI_RECEIVE_DATAGRAM and TDI_SEND_DATAGRAM

The TDI_CONNECTION_INFORMATION structure is used only to specify the remote-node address for these requests.

TDI_LISTEN if the client requests a delayed-connection acceptance

Such a client can supply any necessary user data with its subsequent TDI_ACCEPT request when it accepts a connection offer from a remote-node peer.

When the transport does not allow its clients to supply user data for a particular TDI IOCTL request, the transport fails all such requests in which a client specifies a nonzero UserDataLength.

Using Options and OptionsLength

For a TDI_LISTEN request, the OptionsLength is either zero or sizeof(ULONG) if the client set TDI_QUERY_ACCEPT in the Flags parameter to TdiBuildListen, and Options is either NULL or the buffer contains TDI_QUERY_ACCEPT.

Except for the TDI_LISTEN request, the transport defines the syntax and semantics of any additional options it supports for its clients, usually along the following lines:

·When a client can supply transport-specific information at Options, setting OptionsLength to zero implies that the underlying driver can use its default values for options. When the transport can return information at Options, setting OptionsLength to zero implies that the client would not use the returned data so the transport should ignore Options.

·If such a client sets OptionsLength to a nonzero value, but the transport receives an option string too large for the client-supplied buffer, the transport truncates the options string and completes the client's request normally with a status that indicates data truncation occurred.

·When the client of such a transport uses Options to specify option values for the driver to transfer, the values the driver actually writes can be different from the client-specified values.

Using RemoteAddress and RemoteAddressLength

Use of these members depends on the TDI_XXX IOCTL and on the size of the transport-specific address. In general, a local-node client uses RemoteAddress to specify the target remote-node address when it initiates network-transfer operations, such as connection offers and sends. The transport returns information to RemoteAddress when such an operation was initiated at the remote node, such as to satisfy listen and receive requests.

If the client specifies zero for RemoteAddressLength, the transport assumes RemoteAddress is NULL. If the client specifies a nonzero value for RemoteAddressLength but the transport has received an address too long for the client-supplied buffer, the driver function truncates the address to fit in the client's buffer. In this case, the transport completes the operation normally but returns a status code indicating data truncation to the client.