ClientEventConnect

ClientEventConnect

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
       );

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

Parameters

TdiEventContext

Points to the client-supplied context provided in the IRP that was set up with TdiBuildSetEventHandler when ClientEventConnect was registered with the underlying transport.

RemoteAddressLength

Specifies the size in bytes of the buffer at RemoteAddress.

RemoteAddress

Points to a buffer containing the transport address of the remote-node client that offered this connection.

UserDataLength

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

Points 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

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

Options

Points to a buffer containing options for the connection in a transport-specific format. This parameter is NULL if OptionsLength is zero.

ConnectionContext

Points 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

Points 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 the following:

STATUS_MORE_PROCESSING_REQUIRED

ClientEventConnect is accepting the offered connection and has supplied an accept request at AcceptIrp.

Some transports assume the connection offer is being rejected if ClientEventConnect returns anything other than this value.

STATUS_CONNECTION_REFUSED

ClientEventConnect is rejecting the offered connection.

STATUS_INSUFFICIENT_RESOURCES

ClientEventConnect could not allocate sufficient resources to accept the offered connection. The transport will send a rejection to the remote node.

Comments

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.

By default, ClientEventConnect runs at IRQL DISPATCH_LEVEL.