ClientEventConnect routine

The ClientEventConnect routine is an event handler the TDI driver calls in response to an incoming endpoint-to-endpoint connection offer from a remote node.

Syntax

NTSTATUS ClientEventConnect(
  _In_  PVOID              TdiEventContext,
  _In_  LONG               RemoteAddressLength,
  _In_  PVOID              RemoteAddress,
  _In_  LONG               UserDataLength,
  _In_  PVOID              UserData,
  _In_  LONG               OptionsLength,
  _In_  PVOID              Options,
  _Out_ CONNECTION_CONTEXT *ConnectionContext,
  _Out_ PIRP               *AcceptIrp
);

Parameters

• TdiEventContext [in]
  Pointer to the client-supplied context provided in the IRP that was set up with TdiBuildSetEventHandler when ClientEventConnect was registered with the underlying transport.

• RemoteAddressLength [in]
  Specifies the size in bytes of the buffer at RemoteAddress.

• RemoteAddress [in]
  Pointer to a buffer containing the transport address of the remote-node client that offered this connection.

• UserDataLength [in]
  Specifies the size in bytes of the buffer at UserData. Zero indicates either that no data is available or that the underlying transport(s) do not support sending data with an offered connection. UserData is NULL if this parameter is zero.

• UserData [in]
  Pointer to a buffer containing connect data provided by the remote-node client with its connection offer. This parameter is NULL if UserDataLength is zero.

• OptionsLength [in]
  Specifies the size in bytes of the buffer at Options. Zero implies no option string. Options is NULL if this parameter is zero.

• Options [in]
  Pointer to a buffer containing options for the connection in a transport-specific format. This parameter is NULL if OptionsLength is zero.

• ConnectionContext [out]
  Pointer to a caller-supplied variable in which ClientEventConnect returns a pointer to the client's context area in which it maintains client-determined state for this connection endpoint. Usually, the specified address is identical to the value that the client set for the value at EaBuffer when it originally called ZwCreateFile to open the local connection endpoint. If ClientEventConnect rejects the offered connection, the value it returns is NULL.

• AcceptIrp [out]
  Pointer to a caller-supplied variable in which ClientEventConnect returns a pointer to an IRP, set up by ClientEventConnect with TdiBuildAccept. The transport completes this IRP if it is supplied as it does any normal accept request. If ClientEventConnect rejects the connection offer, this parameter is NULL.

Return value

ClientEventConnect can return one of the following:

Remarks

This call notifies the local-node client of an incoming connection offer from a remote-node peer process. The local-node ClientEventConnect handler inspects the transport-supplied address information identifying the remote-node client and any data at UserData and/or Options to determine whether to accept this connection offer.

To accept an offered endpoint-to-endpoint connection, ClientEventConnect must set up the buffer at ConnectionContext, together with a TDI_ACCEPT request, and, then, return STATUS_MORE_PROCESSING_REQUIRED. The local-node transport notifies the remote node of the acceptance, transmitting any connect data that its client supplied in the accept IRP, and completes the TDI_ACCEPT request normally.

A client should preallocate the IRP it will use to accept a connection offer before its ClientEventConnect handler is called. In general, any client should preallocate a few IRPs for the TDI_XXX IOCTL requests it might subsequently submit to the underlying transport while running at IRQL = DISPATCH_LEVEL. Client calls to TdiBuildInternalDeviceControlIrp can occur at IRQL = PASSIVE_LEVEL.

When ClientEventConnect returns control with STATUS_MORE_PROCESSING_REQUIRED, the underlying transport can indicate incoming receives on the endpoint-to-endpoint connection to the client's registered ClientEvent(Chained)Receive(Expedited) handler(s), even before the transport completes the given accept IRP back to its local-node client. A client must be prepared to accept received data as soon as it agrees to accept an endpoint-to-endpoint connection offer from a remote-node peer.

To reject an offered endpoint-to-endpoint connection, ClientEventConnect can simply return STATUS_CONNECTION_REFUSED. For this return status, the local-node transport notifies the remote-node transport that the connection offer has been rejected.

If the client either does not have or cannot allocate sufficient resources to accept the connection offer, ClientEventConnect returns STATUS_INSUFFICIENT_RESOURCES. For this return status, the TDI transport either sends a rejection of the remote-node client's connection offer to the corresponding transport on the remote node or simply drops the connection offer.

ClientEventConnect must be capable of carrying out its operations at IRQL = DISPATCH_LEVEL.

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

See also

ClientEventChainedReceive

ClientEventChainedReceiveExpedited

ClientEventReceive

ClientEventReceiveExpedited

TDI_ACCEPT

TdiBuildAccept

TdiBuildInternalDeviceControlIrp

TdiBuildListen

TdiBuildSetEventHandler

TdiDispatchCreate

TA_ADDRESS

Send comments about this topic to Microsoft