TdiBuildListen macro
TdiBuildListen sets up an internal device control IRP for a TDI_LISTEN request to the underlying transport in which the local-node client has already associated an address and a connection endpoint.
Syntax
VOID TdiBuildListen(
[in] PIRP Irp,
[in] PDEVICE_OBJECT DevObj,
[in] PFILE_OBJECT FileObj,
[in] PVOID CompRoutine,
[in] PVOID Contxt,
[in] ULONG Flags,
[in] PTDI_CONNECTION_INFORMATION RequestConnectionInfo,
[out] PTDI_CONNECTION_INFORMATION ReturnConnectionInfo
);
Parameters
Irp [in]
Pointer to a client-supplied IRP, either originating in a higher level network component or allocated with TdiBuildInternalDeviceControlIrp.DevObj [in]
Pointer to the device object created by the underlying TDI transport driver.FileObj [in]
Pointer to a file object representing the connection endpoint. The client previously made a successful request, set up with TdiBuildAssociateAddress, to the transport to set up an association between this connection and a local-node address.CompRoutine [in]
Specifies the entry point of a client-supplied IoCompletion routine or NULL. The I/O manager calls this routine when the given IRP is completed, unless the client sets this parameter to NULL.Contxt [in]
Pointer to a client-determined context. This client-supplied pointer is passed in to the client's IoCompletion routine when it is called with the completed IRP. Contxt is NULL if CompRoutine is NULL.Flags [in]
Specifies zero or, possibly, TDI_QUERY_ACCEPT if the underlying transport supports delayed-connection acceptances.If Flags is zero, the underlying transport accepts the connection from the remote node as soon as it is offered. The client can assume the endpoint-to-endpoint connection is fully operational when its listen request completes. In fact, receives on the connection endpoint can occur even before this listen IRP is fully completed back to the client.
If the transport supports delayed-connection acceptances and its client sets TDI_QUERY_ACCEPT, that client must either accept or reject the offered connection as quickly as possible when the listen request completes. That is, on completion of this IRP, the client must set up another request to the transport with either TdiBuildAccept or TdiBuildDisconnect, respectively.
RequestConnectionInfo [in]
Pointer to a client-supplied buffer containing a TDI_CONNECTION_INFORMATION structure that specifies the remote-node client address from which the local-node client expects an endpoint-to-endpoint connection offer.Depending on the value of Flags, the client also provides additional information in the following members of this structure:
UserData
Pointer to a buffer of data the client wants sent with its acceptance of the connection offer from the remote node if Flags is zero.A client sets this member to NULL if the underlying transport supports delayed-connection acceptances and the client sets Flags to TDI_QUERY_ACCEPT. Such a client can provide accept data when it subsequently accepts an offered connection, assuming it does.
UserDataLength
Specifies the size in bytes of the buffer at UserData. This member is zero if UserData is NULL.Options
Set to the same value as Flags.OptionsLength
Set to sizeof(ULONG).RemoteAddress
Pointer to a buffer specifying the remote-node address from which the local-node client expects a connection offer that the local-node client will accept. This member can be NULL if an offered connection from any remote node is acceptable to the client.For some transports, a local-node client can specify a partial address. However, TDI drivers vary in their ability to handle partial addresses. Because the syntax of any such address is protocol-specific, the underlying TDI transport defines the conventions for specifying a partial address if it supports partial-address specifications.
RemoteAddressLength
Specifies the size in bytes of the buffer at RemoteAddress. This member should be set to zero if RemoteAddress is NULL.
ReturnConnectionInfo [out]
Pointer to a caller-supplied buffer in which the transport returns the remote-node address from which a connection offer was made. This buffer is also formatted as TDI_CONNECTION_INFORMATION structure.If the local-node client set Flags to TDI_QUERY_ACCEPT, it examines the returned information to determine whether to accept or reject the connection when this listen request completes.
If the client requires no output information or if the underlying transport does not return such information, this parameter should be NULL.
Return value
None
Remarks
TdiBuildListen sets IRP_MJ_INTERNAL_DEVICE_CONTROL as the MajorFunction and TDI_LISTEN as the MinorFunction codes in the transport's I/O stack location of the given IRP.
Before it calls the underlying transport with the IRP set up by TdiBuildListen, a client must make a preceding associate-address request, set up with TdiBuildAssociateAddress, that succeeded in associating an idle connection endpoint with a local-node address. After this association is established, a client can issue numerous listen requests until it accepts an offered endpoint-to-endpoint connection.
The underlying transport usually processes each client's listen requests in FIFO order unless it supports quality-of-service (QoS) for its clients and, therefore, prioritizes incoming listen requests. However, a client cannot make assumptions about the order in which the underlying transport processes requests from all its current clients.
Client-supplied addressing information at RequestConnectionInfo acts as a filter that the underlying transport driver applies, before checking whether the client set TDI_QUERY_ACCEPT if the transport supports delayed-connection acceptances. If an incoming connection offer does not match an address specified in the client's listen request, the transport cannot complete the listen request for the client. Otherwise, when an incoming connection offer is made from a specified remote-node address, the local-node client's listen request is completed in one of the following ways:
If the client set Flags to TDI_QUERY_ACCEPT indicating delayed-connection acceptance, the transport completes the listen request, and the client must either accept or reject the offered endpoint-to-endpoint connection by issuing a TDI_ACCEPT or TDI_DISCONNECT request to the transport immediately.
If the client set Flags to zero, possibly because the underlying transport does not support delayed-connection acceptances, the transport transmits an acceptance, along with any accept data the client supplied, to the remote node and completes the listen request.
Before making a listen request, a client can set up one or more IRPs with TdiBuildSetEventHandler and register its ClientEvent(Chained)Receive(Expedited) handler(s) for the local address associated with the connection endpoint. If it does this, the ClientEvent(Chained)Receive(Expedited) routine(s) can receive TSDUs before the client's listen request completes. Such a client must be prepared to accept an immediate connection when it makes a listen request.
While a listen for a client's connection endpoint is pending on a particular local-node address, that client's ClientEventConnect function cannot be called except under special circumstances. That is, the underlying transport can call ClientEventConnect if a listen operation is pending and the transport determines that the remote address acceptance criteria would prevent the listen operation from being completed.
As mentioned previously, some transports support the specification of remote-node partial addresses on listens. A transport also might support the specification of QoS options. For example, such a TDI transport's clients might specify the QoS for a listen using a variable-length counted string with transport-defined syntax and semantics.
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
Target platform |
Desktop |
Header |
Tdikrnl.h (include TdiKrnl.h) |
See also
ClientEventChainedReceiveExpedited
TdiBuildInternalDeviceControlIrp