TdiMapUserRequest

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.