TdiBuildInternalDeviceControlIrp macro

  • Article

TdiBuildInternalDeviceControlIrp allocates an IRP for a client-initiated internal device control request. After it returns, the client calls another TdiBuildXxx macro with the returned IRP to set up the I/O stack location of the underlying transport driver before making the request with IoCallDriver.

Syntax

PIRP TdiBuildInternalDeviceControlIrp(
  [in] CCHAR            IrpSubFunction,
  [in] PDEVICE_OBJECT   DeviceObject,
  [in] PFILE_OBJECT     FileObject,
  [in] PKEVENT          Event,
  [in] PIO_STATUS_BLOCK IoStatusBlock
);

Parameters

  • IrpSubFunction [in]
    Specifies the TDI_XXX code that will be set in a subsequent call to a TdiBuildXxx macro as the MinorFunction for the returned IRP. This parameter can be one of the following:

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

  • FileObject [in]
    Pointer to a file object representing an address, connection endpoint, or control channel, depending on the given IrpSubFunction.

  • Event [in]
    Pointer to an initialized event object for which the caller provides the storage.

  • IoStatusBlock [in]
    Pointer to a caller-supplied variable of type IO_STATUS_BLOCK.

Return value

TdiBuildInternalDeviceControlIrp returns a pointer to the IRP it allocated, or it returns NULL if the allocation attempt failed.

Remarks

Kernel-mode clients of TDI transports frequently pass IRPs sent down by still higher level network components directly to TdiBuildXxx macros without calling TdiBuildInternalDeviceControlIrp.

However, such a client should never hijack an incoming IRP and reuse it to make an internal device control request to the underlying transport on its own behalf. Instead the client can call TdiBuildInternalDeviceControlIrp to get an IRP of its own with which to make such requests.

After TdiBuildInternalDeviceControlIrp returns a pointer to an IRP, the client must pass the IRP to the appropriate TdiBuildXxx macro, along with the additional parameters the TDI_XXX requires, before it passes the IRP on to the transport with IoCallDriver. TdiBuildInternalDeviceControlIrp partially sets up the I/O stack location of the underlying transport in the IRP it allocates. However, it does not format the I/O stack location according to a TDI transport's expectations for a TDI_XXX request as the TdiBuildXxx macros do.

See IoCallDriver for more information.

If the client supplies an Event pointer when it calls TdiBuildInternalDeviceControlIrp, the I/O manager will set the event to the Signaled state when the IRP is completed by lower drivers. However, the client cannot wait for that event for completion of its IRP unless it waits at IRQL = PASSIVE_LEVEL in an appropriate thread context, either that of a client-created thread or, possibly, that of the thread in which it was executing when it made this call.

Callers of TdiBuildInternalDeviceControlIrp must be running at IRQL = PASSIVE_LEVEL. Consequently, a client should preallocate a few IRPs with this function so the client can use them to submit TDI_XXX requests when it is running at a higher IRQL.

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

 Desktop

Header

 Tdikrnl.h (include TdiKrnl.h)

IRQL

PASSIVE_LEVEL (see Remarks section)

 

 

Send comments about this topic to Microsoft