TdiMapUserRequest function

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:

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

See also

TDI_CONNECTION_INFORMATION

TdiDispatchDeviceControl

TdiDispatchInternalDeviceControl

Send comments about this topic to Microsoft