TdiMapUserRequest function

Article
06/19/2017

The TdiMapUserRequest function converts a given IRP in which MajorFunction is set to IRP_MJ_DEVICE_CONTROL into an IRP_MJ_INTERNAL_DEVICE_CONTROL request if TdiMapUserRequest recognizes the IOCTL_TDI_XXX code specified in the input IRP.

Syntax

NTSTATUS TdiMapUserRequest(
  _In_ PDEVICE_OBJECT     DeviceObject,
  _In_ PIRP               Irp,
  _In_ PIO_STACK_LOCATION IrpSp
);

Parameters

DeviceObject [in]
Pointer to the device object created by the transport driver.
Irp [in]
Pointer to the user IOCTL_XXX request to be converted.
IrpSp [in]
Pointer 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:

Return code	Description
STATUS_INVALID_PARAMETER	If IOCTL_TDI_SET_EVENT_HANDLER is specified in the given I/O stack location of the input IRP, or the data pointed to by a member in the TDI_CONNECTION_INFORMATION structure exceeds the size of the client-supplied buffer.
STATUS_NOT_IMPLEMENTED	If TdiMapUserRequest does not recognize the IOCTL_XXX code specified in the given I/O stack location of the input IRP.

Remarks

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_SET_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 Using I/O Control Codes.

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	Universal
Header	Tdikrnl.h (include TdiKrnl.h)
Library	Tdi.lib
IRQL	PASSIVE_LEVEL

Share via