2.2 TDI Driver Dispatch Routines
Kernel-mode TDI requests are handled by the Windows NT I/O Manager. Requests are formatted as IRPs and submitted to the transport driver by calling IoCallDriver. Completed IRPs are returned to the caller when the transport driver calls IoCompleteRequest. The kernel-mode client can set its IoCompletion routine in such an IRP before calling IoCallDriver.
There are four IRP_MJ_XXX codes used to send I/O requests to TDI transport drivers. TDI drivers must handle incoming IRPs in which the MajorFunctionCode is one of the following:
IRP_MJ_CREATE
Opens an address object, connection endpoint object, or control channel object.
IRP_MJ_DEVICE_INTERNAL_CONTROL
Interprets kernel-mode client requests (IOCTLs) and calls internal driver functions that handle operations other than opening and closing objects.
IRP_MJ_CLEANUP
Closes an address, connection endpoint, or control channel object if the Windows NT executive is closing the last handle for the file object.
IRP_MJ_CLOSE
Closes an address, connection endpoint, or control channel object if the executive is removing its last reference to the file object handle.
The actual entry points in the TDI driver are one or more Dispatch routines that handle these IRP_MJ_XXX requests. Because a TDI client communicates with the driver only through IRPs, the driver has Dispatch routines that determine what operation to carry out and, usually, pass the client requests to appropriate internal driver functions for processing.
A TDI transport driver exposes all its TDI Dispatch entry points by setting them in the driver object passed in to its DriverEntry routine. The I/O Manager calls a Dispatch routine whenever a client makes an I/O request. A transport driver can have a separate DispatchXxx to handle each of the possible IRP_MJ_XXX codes or a single Dispatch routine that processes IRPs with all possible IRP_MJ_XXX codes.
Since Dispatch entry points are exported by address in the driver object, not by name, a TDI transport driver writer can name these routines anything. In the discussion of TDI in this chapter and the following chapters on TDI, TDI driver Dispatch routines have the following metanames, describing their basic functionality, to correspond with the preceding IRP_MJ_XXX:
IRP_MJ_CREATE
IRP_MJ_DEVICE_INTERNAL_CONTROL
TdiDispatchInternalDeviceControl
IRP_MJ_CLEANUP
IRP_MJ_CLOSE