ClientEventErrorEx routine

Article
06/19/2017

The ClientEventErrorEx routine is an event handler that the underlying TDI transport calls in response to an error, either in the transport itself or in a still lower network driver, that makes I/O on a particular local transport address unreliable or impossible.

Syntax

NTSTATUS ClientEventErrorEx(
  _In_ PVOID    TdiEventContext,
  _In_ NTSTATUS Status,
  _In_ PVOID    Buffer
);

Parameters

TdiEventContext [in]
Pointer to the client-supplied context provided in the IRP that was set up with TdiBuildSetEventHandler when ClientEventErrorEx was registered with the underlying transport.
Status [in]
Specifies an NTSTATUS value that provides information about the condition that caused this call to ClientEventErrorEx.
Buffer [in]
Pointer to a buffer containing additional transport-supplied information about the error. For example, the system TCP/IP transport can supply information that identifies the port when it indicates that a destination port is unreachable.

Return value

ClientEventErrorEx can return STATUS_SUCCESS.

Remarks

A call to ClientEventErrorEx notifies the local-node client of an error condition in the underlying TDI transport, in one of the lower protocol layers of the transport stack, or in the underlying NDIS NIC driver to which the transport stack is bound. If such an error occurs, the TDI transport calls all currently registered ClientEventErrorEx handlers for each client on every open address that depends on the underlying driver that encountered the error condition.

A call to ClientEventErrorEx can indicate a catastrophic failure. After such a call, the client should cease to use, and in some cases close, the file object representing the transport address associated with this notification. If this address is associated with an endpoint-to-endpoint connection, ClientEventErrorEx can assume the connection is broken as well. However, such a call does not necessarily indicate a fatal error. For example, the TCP/IP notification of an "unreachable port" is not a catastrophic error. The client might set a timer and make another attempt to connect to the port when its timer expires.

When notified of a catastrophic error, the ClientEventErrorEx handler usually cleans up any state it was maintaining for the address and for all connection endpoints it has associated with that address. That is, the client notifies higher level components for which it is handling pending operations on the address of the failure. For example, the client might forward such an indication to a Windows Sockets application that was using a particular port. Then, the client releases all resources it previously allocated that are relevant to those operations.

ClientEventErrorEx 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

Target platform	Desktop
Header	Tdikrnl.h (include TdiKrnl.h)
IRQL	DISPATCH_LEVEL (see Remarks section)

Partager via