TdiDispatchInternalDeviceControl routine

The TdiDispatchInternalDeviceControl routine handles TDI_XXX device-control requests from kernel-mode clients.

Syntax

NTSTATUS TdiDispatchInternalDeviceControl(
  _In_ PDEVICE_OBJECT DeviceObject,
  _In_ PIRP           Irp
);

Parameters

• DeviceObject [in]
  Pointer to the device object created by the TDI driver.

• Irp [in]
  Pointer to the IRP.

  A transport calls IoGetCurrentIrpStackLocation with the given Irp to get a pointer to its own I/O stack location in the IRP, shown in the following list as IrpSp. The transport can use the information set in the following members of the IRP in processing an internal device-control request:

  • IoStatus.Status
    Specifies the final status of the operation. The transport sets this member to the same value that will be returned by TdiDispatchInternalDeviceControl.

  • IoStatus.Information
    Usually, this member is initialized to zero. Depending on the IrpSp-> MinorFunction value, the transport resets this member to the number of bytes of data it is returning to the client or to the number of bytes of data it transferred before the transport completes this IRP.

  • IrpSp-> MajorFunction
    Specifies IRP_MJ_INTERNAL_DEVICE_CONTROL. The transport can ignore this member if it exports a TdiDispatchInternalDeviceControl routine that handles only these requests.

  • IrpSp > MinorFunction
    Specifies the TDI_XXX code for the operation to be carried out.

  • IrpSp-> FileObject
    Pointer to the file object representing an address, connection endpoint, or control channel. The transport driver uses the values of the FsContext and possibly FsContext2 fields in this file object to access any driver-allocated state for operations on the address, connection endpoint, or control channel.

Return value

TdiDispatchInternalDeviceControl returns STATUS_SUCCESS if it completed the requested operation successfully. Otherwise, it returns a driver-determined error status, such as STATUS_INVALID_DEVICE_REQUEST or STATUS_INVALID_DEVICE_STATE.

Remarks

When preparing a request, a kernel-mode client either allocates an IRP with TdiBuildInternalDeviceControlIrp or uses an IRP passed in from a higher network layer. The client calls a TdiBuildXxx macro to set up the IRP for the underlying transport with the corresponding TDI_XXX as the MinorFunction code and IRP_MJ_INTERNAL_DEVICE_CONTROL as the MajorFunction code in the IRP. When it has set up the IRP, the client calls IoCallDriver to submit the request to the underlying transport's TdiDispatchInternalDeviceControl routine.

Usually, a transport's TdiDispatchInternalDeviceControl routine determines whether the given file object at IrpSp-> FileObject represents an address, connection endpoint, or control channel, because certain TDI_XXX are relevant only to addresses, others are relevant only to connection endpoints, and a subset of TDI_XXX codes are relevant to both and to control channels. The following summarizes which TDI_XXX codes are likely to be processed for each:

FileObject represents an address

TDI_SEND_DATAGRAM

TDI_RECEIVE_DATAGRAM

TDI_SET_EVENT_HANDLER

FileObject represents a connection endpoint

TDI_SEND

TDI_RECEIVE

TDI_ASSOCIATE_ADDRESS

TDI_DISASSOCIATE_ADDRESS

TDI_CONNECT

TDI_DISCONNECT

TDI_LISTEN

TDI_ACCEPT

FileObject represents an address, connection endpoint, or control channel

TDI_QUERY_INFORMATION

TDI_SET_INFORMATION

TDI_ACTION

For each TDI_XXX the transport handles, its TdiDispatchInternalDeviceControl routine usually calls an internal driver function to carry out the requested operation. Possibly, the internal driver function also complete the IRP, particularly if that function transfers data because it then can set IoStatus.Information to the appropriate value, leaving TdiDispatchInternalDeviceControl to complete IRPs in which this member is set to zero. Each such internal function usually returns an NTSTATUS-type value, which TdiDispatchInternalDeviceControl propagates when it returns control.

For more information about each of the TDI_XXX mentioned here, see TDI IOCTLs for Transport Drivers, next.

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

TdiBuildInternalDeviceControlIrp

TdiDispatchDeviceControl

Send comments about this topic to Microsoft