TdiBuildSetEventHandler macro
TdiBuildSetEventHandler sets up an internal device control IRP for a TDI_SET_EVENT_HANDLER request to the underlying transport in which the local-node client has already opened a file object representing an address.
Syntax
VOID TdiBuildSetEventHandler(
[in] PIRP Irp,
[in] PDEVICE_OBJECT DevObj,
[in] PFILE_OBJECT FileObj,
[in] PVOID CompRoutine,
[in] PVOID Contxt,
[in] LONG InEventType,
[in] PVOID InEventHandler,
[in] PVOID InEventContext
);
Parameters
Irp [in]
Pointer to a client-supplied IRP, either originating in a higher level network component or, more commonly, 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 an 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 IoCompletion routine when it is called with the completed IRP. Contxt is NULL if CompRoutine is NULL.InEventType [in]
Specifies the type of event handler being registered as one of the following:TDI_EVENT_CONNECT
Register the given ClientEventConnect handler to be called when an endpoint-to-endpoint connection is offered by a remote-node peer.TDI_EVENT_DISCONNECT
Register the given ClientEventDisconnect handler to be called when an established endpoint-to-endpoint connection is being closed by the remote-node peer.TDI_EVENT_RECEIVE
Register the given ClientEventReceive handler to be called when a normal receive comes in on an endpoint-to-endpoint connection from the remote node and the client will be given the opportunity to copy all or part of the buffered TSDU.TDI_EVENT_CHAINED_RECEIVE
Register the given ClientEventChainedReceive handler to be called when a normal receive comes in on an endpoint-to-endpoint connection from the remote node and the client will be given read-only access to the buffered full TSDU until it calls TdiReturnChainedReceives.TDI_EVENT_RECEIVE_EXPEDITED
Register the given ClientEventReceiveExpedited handler to be called when an expedited receive comes in on an endpoint-to-endpoint connection from the remote node and the client will be given the opportunity to copy all or part of the buffered TSDU.TDI_EVENT_CHAINED_RECEIVE_EXPEDITED
Register the given ClientEventChainedReceiveExpedited handler to be called when an expedited receive comes in on an endpoint-to-endpoint connection from the remote node and the client will be given read-only access to the buffered full TSDU until it calls TdiReturnChainedReceives.TDI_EVENT_RECEIVE_DATAGRAM
Register the given ClientEventReceiveDatagram handler to be called when a datagram comes in from a remote node and the client will be given the opportunity to copy all or part of the buffered TSDU.TDI_EVENT_CHAINED_RECEIVE_DATAGRAM
Register the given ClientEventChainedReceiveDatagram handler to be called when a datagram comes in from a remote node and the client will be given read-only access to the buffered full TSDU until it calls TdiReturnChainedReceives.TDI_EVENT_SEND_POSSIBLE
Register the given ClientEventSendPossible handler to be called when the underlying transport, which previously returned a submitted send request with STATUS_DEVICE_NOT_READY, again has internal buffer space available into which it can copy the resubmitted client-supplied data to be sent.TDI_EVENT_ERROR
Register the given ClientEventError handler to be called if an error occurs in an underlying driver such that network I/O on this local-node address has become unreliable or impossible.TDI_EVENT_ERROR_EX
Register the given ClientEventErrorEx handler to be called if an error occurs such that network I/O on this local-node address has become unreliable or impossible. If it supports these indications, the underlying transport supplies additional buffered information about such an error to ClientEventErrorEx than to ClientEventError.
In addition to the preceding system-defined events, a transport can extend this interface to support transport-specific notifications of events to its clients. Such a transport must define TDI_EVENT_XXX codes in which the most significant bit is set.
InEventHandler [in]
Specifies the entry point of the ClientEventXxx handler being registered. The client can set this parameter to NULL to disable notifications to a previously registered event handler.InEventContext [in]
Pointer to caller-determined context to be passed in to the ClientEventXxx routine when it is called by the transport. This parameter must be NULL if InEventHandler is NULL.
Return value
None
Remarks
When its client first opens a file object that represents an address, the underlying transport initializes all event handlers to NULL.
TdiBuildSetEventHandler sets IRP_MJ_INTERNAL_DEVICE_CONTROL as the MajorFunction and TDI_SET_EVENT_HANDLER as the MinorFunction codes in the transport's I/O stack location of the given IRP.
With each IRP set up by TdiBuildSetEventHandler and submitted to the underlying transport with IoCallDriver, the client registers one event handler for a given event type that can occur on a particular transport address. Indications from lower level NDIS drivers that are forwarded by the transport to ClientEventXxx routines usually occur at IRQL = DISPATCH_LEVEL. For these client-supplied event handlers, the caller should allocate the area at InEventContext from nonpaged pool.
A client can register its ClientEvent(Chained)ReceiveDatagram and ClientEventError(Ex) handlers as soon as it has opened a file object representing an address with a successful call to ZwCreateFile. It can register its ClientEventConnect handler as soon as it has opened file objects representing an address and a connection endpoint and made a successful associate-address request to the underlying transport.
For some InEventType values, the address represented by the given file object should be associated with a connection endpoint by the client before it registers certain ClientEventXxx handlers. In particular, a client should associate a connection endpoint with a local-node address before it registers its ClientEvent(Chained)Receive(Expedited), ClientEventDisconnect, and/or ClientEventSendPossible handlers for network transfers that are made on a connection-specific basis. Unless its transport supports delayed-connection acceptances, the client should assume that an endpoint-to-endpoint connection, already associated with the open file object representing the address, is active when it makes the set-event-handler request to register any of these event handlers.
Only clients of transports that buffer send data internally can register a ClientEventSendPossible handler.
In general, a TDI transport can indicate an event to a client while an event of the same kind is in progress. In other words, ClientEventXxx handlers are reentrant. The transport also can call ClientEvent(Chained)Receive(Expedited) or ClientEvent(Chained)Receive(Datagram) before the client's set-event-handler IRP to register one of these routines is fully completed. Consequently, the client must be prepared to handle receives as soon as it requests the registration of a ClientEvent(Chained)Receive(Xxx) handler.
Calls to registered ClientEvent(Chained)Receive(Xxx) handlers are disabled whenever the client submits a receive or receive-datagram IRP set up with TdiBuildReceive or TdiBuildReceiveDatagram to the underlying transport. After it is called with such an IRP, the underlying transport carries out all operations necessary to complete that IRP before it resumes calling registered ClientEvent(Chained)Receive(Xxx) routine(s) with incoming receive indications.
A client can disable any registered event handler by making another set-event-handler request with the same InEventType but specifying NULL as the InEventHandler and InEventContext parameters to TdiBuildSetEventHandler.
To register its ClientPnPXxx handlers for Plug and Play and power-state-change notifications, a client calls TdiRegisterPnPHandlers rather than TdiBuildSetEventHandler followed by IoCallDriver.
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
ClientEventChainedReceiveDatagram
ClientEventChainedReceiveExpedited
TdiBuildInternalDeviceControlIrp