TdiBuildInternalDeviceControlIrp

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.

Parameters

IrpSubFunction
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:
TDI_ASSOCIATE_ADDRESS
The caller will pass the returned IRP to TdiBuildAssociateAddress.
TDI_DISASSOCIATE_ADDRESS
The caller will pass the returned IRP to TdiBuildDisassociateAddress.
TDI_CONNECT
The caller will pass the returned IRP to TdiBuildConnect.
TDI_LISTEN
The caller will pass the returned IRP to TdiBuildListen.
TDI_ACCEPT
The caller will pass the returned IRP to TdiBuildAccept.
TDI_DISCONNECT
The caller will pass the returned IRP to TdiBuildDisconnect.
TDI_SEND
The caller will pass the returned IRP to TdiBuildSend.
TDI_RECEIVE
The caller will pass the returned IRP to TdiBuildReceive.
TDI_SEND_DATAGRAM
The caller will pass the returned IRP to TdiBuildSendDatagram.
TDI_RECEIVE_DATAGRAM
The caller will pass the returned IRP to TdiBuildReceiveDatagram.
TDI_SET_EVENT_HANDLER
The caller will pass the returned IRP to TdiBuildSetEventHandler.
TDI_QUERY_INFORMATION
The caller will pass the returned IRP to TdiBuildQueryInformation.
TDI_SET_INFORMATION
The caller will pass the returned IRP to TdiBuildSetInformation.
TDI_ACTION
The caller will pass the returned IRP to TdiBuildAction.
DeviceObject
Points to the device object created by the next lower TDI transport driver.
FileObject
Points to a file object representing an address, connection endpoint, or control channel, depending on the given IrpSubFunction.
Event
Points to an initialized event object for which the caller provides the storage.
IoStatusBlock
Points 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.

Comments

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.