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.