PIRP
TdiBuildInternalDeviceControlIrp (
IN CCHAR IrpSubFunction,
IN PDEVICE_OBJECT DeviceObject,
IN PFILE_OBJECT FileObject,
IN PKEVENT Event,
IN PIO_STATUS_BLOCK IoStatusBlock
);
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.
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 TdiBuildInternalDeviceControl 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. TdiBuildInternalDeviceControl 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.
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 on 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.