NTSTATUS
TdiMapUserRequest(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PIO_STACK_LOCATION IrpSp
);
TdiMapUserRequest converts a given IRP in which MajorFunction is set to IRP_MJ_DEVICE_CONTROL into an IRP_MJ_INTERNAL_DEVICE_CONTROL request if it recognizes the IOCTL_TDI_XXX code specified in the input IRP.
Parameters
DeviceObject
Points to the device object created by the transport driver.
Irp
Points to the user IOCTL_XXX request to be converted.
IrpSp
Points to the I/O stack location to be converted.
The transport's TdiDispatchDeviceControl routine already called IoGetCurrentIrpStackLocation to obtain this pointer.
Return Value
TdiMapUserRequest returns STATUS_SUCCESS if it converted the given IOCTL_TDI_XXX device-control request into a TDI_XXX internal device-control request. Otherwise, it can return either of the following:
STATUS_INVALID_PARAMETER
If IOCTL_TDI_SET_EVENT_HANDLER is specified in the given I/O stack location of the input IRP
STATUS_NOT_IMPLEMENTED
If TdiMapUserRequest does not recognize the IOCTL_XXX code specified in the given I/O stack location of the input IRP
Comments
For the majority of system-defined IOCTL_TDI_XXX codes that can be set in IRPs passed to a transport's TdiDispatchDeviceControl routine, TdiMapUserRequest converts the current I/O stack location into the format of the corresponding kernel-mode TDI_XXX request.
For example, if IrpSp->Parameters.DeviceIoControl.IoControlCode is set to IOCTL_TDI_LISTEN in the input IRP, TdiMapUserRequest reformats the I/O stack location as follows:
·Resets MajorFunction to IRP_MJ_INTERNAL_DEVICE_CONTROL
·Sets MinorFunction to TDI_LISTEN
·If the input Irp->AssociatedIrp.SystemBuffer is not NULL, sets IrpSp->Parameters to the address of a TDI_REQUEST_KERNEL_LISTEN structure, which it sets up with the caller-supplied information
TdiDispatchDeviceControl can call TdiDispatchInternalDeviceControl with such a converted IRP, thereby saving the transport from having duplicate code paths for processing system-defined IOCTL_TDI_XXX and the corresponding TDI_XXX requests.
While the kernel-mode TDI_REGISTER_EVENT_HANDLER has a corresponding user IOCTL_TDI_REGISTER_EVENT_HANDLER, TdiMapUserRequest fails any attempt to map such an input IRP. Only kernel-mode clients can register event handlers with a TDI transport, so a transport's TdiDispatchDeviceControl routine cannot be called with a valid request to set up an event handler.
If a transport defines any private IOCTL_XXX codes to be used by a transport-dedicated Win32 application for communication with the transport, its TdiDispatchDeviceControl routine can process such a request whenever TdiMapUserRequest returns STATUS_NOT_SUPPORTED. For more information about defining driver-specific, private IOCTLs, see the Kernel-Mode Driver Reference.
Callers of TdiMapUserRequest run at IRQL PASSIVE_LEVEL.
See Also