TDI_CONNECTION_INFORMATION structure
The TDI_CONNECTION_INFORMATION structure 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.
Syntax
typedef struct _TDI_CONNECTION_INFORMATION {
LONG UserDataLength;
PVOID UserData;
LONG OptionsLength;
PVOID Options;
LONG RemoteAddressLength;
PVOID RemoteAddress;
} TDI_CONNECTION_INFORMATION, *PTDI_CONNECTION_INFORMATION;
Members
UserDataLength
Specifies the size in bytes of the buffer at UserData or zero if UserData is NULL.UserData
Pointer 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
Pointer 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
Pointer 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).
Remarks
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 UserDatawith 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 TdiBuildQueryInformationfor the QTypeTDI_QUERY_PROVIDER_INFO.
When the client can send user data with a particular TDI IOCTL request, a UserDataLengthset 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 UserDataLengthset to zero implies that the transport returned no data in the buffer at UserData. Otherwise, the transport sets UserDataLengthto the number of bytes of data it received for the client.
If the client specifies a nonzero UserDataLengthand 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.
UserDataLengthmust be zero and UserDatamust 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 OptionsLengthis either zero or sizeof(ULONG)if the client set TDI_QUERY_ACCEPT in the Flagsparameter to TdiBuildListen, and Optionsis 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 RemoteAddressto specify the target remote-node address when it initiates network-transfer operations, such as connection offers and sends. The transport returns information to RemoteAddresswhen 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 RemoteAddressis NULL. If the client specifies a nonzero value for RemoteAddressLengthbut 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.
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).
Requirements
Header |
Tdi.h (include Tdi.h or TdiKrnl.h) |
See also