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.
PIRP TdiBuildInternalDeviceControlIrp( [in] CCHAR IrpSubFunction, [in] PDEVICE_OBJECT DeviceObject, [in] PFILE_OBJECT FileObject, [in] PKEVENT Event, [in] PIO_STATUS_BLOCK IoStatusBlock );
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:
The caller will pass the returned IRP to TdiBuildAssociateAddress.
The caller will pass the returned IRP to TdiBuildDisassociateAddress.
The caller will pass the returned IRP to TdiBuildConnect.
The caller will pass the returned IRP to TdiBuildListen.
The caller will pass the returned IRP to TdiBuildAccept.
The caller will pass the returned IRP to TdiBuildDisconnect.
The caller will pass the returned IRP to TdiBuildSend.
The caller will pass the returned IRP to TdiBuildReceive.
The caller will pass the returned IRP to TdiBuildSendDatagram.
The caller will pass the returned IRP to TdiBuildReceiveDatagram.
The caller will pass the returned IRP to TdiBuildSetEventHandler.
The caller will pass the returned IRP to TdiBuildQueryInformation.
The caller will pass the returned IRP to TdiBuildSetInformation.
The caller will pass the returned IRP to TdiBuildAction.
Pointer to the device object created by the underlying TDI transport driver.
Pointer to a file object representing an address, connection endpoint, or control channel, depending on the given IrpSubFunction.
Pointer to an initialized event object for which the caller provides the storage.
Pointer to a caller-supplied variable of type IO_STATUS_BLOCK.
TdiBuildInternalDeviceControlIrp returns a pointer to the IRP it allocated, or it returns NULL if the allocation attempt failed.
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).
|Tdikrnl.h (include TdiKrnl.h)|
PASSIVE_LEVEL (see Remarks section)