IoInitializeIrpEx

This function initialises caller-supplied memory for use as an I/O Request Packet (IRP).

Declaration

VOID 
IoInitializeIrpEx (
    IRP *Irp,
    DEVICE_OBJECT *DeviceObject, 
    USHORT PacketSize, 
    CHAR StackSize);

Parameters

The Irp argument is the address at which to prepare an IRP and supporting structures.

The DeviceObject argument is the address of a DEVICE_OBJECT that represents the device that the request will be sent to. This argument can be NULL.

The PacketSize argument tells how many bytes are available at the address given by Irp.

The StackSize argument is the number of I/O stack locations to provide for the IRP.

Return Value

This function returns nothing.

Availability

The IoInitializeIrpEx function is exported by name from the kernel in version 10.0 and higher.

Documentation Status

The IoInitializeIrpEx function is not documented. It is, however, declared in WDM.H.

Behaviour

The IoInitializeIrpEx function is the ancient, documented IoInitializeIrp function except for having the DeviceObject argument as an elaboration. The only known purpose to the elaboration is to help device objects that anticipate receiving requests that carry additional parameters in an IRP extension. Such a DEVICE_OBJECT has a set DO_DEVICE_IRP_REQUIRES_EXTENSION bit (0x08000000) in its Flags. Requests for such device objects are prepared and managed more efficiently if the IRP extension is in the same memory block as the IRP and its I/O stack locations.

The function prepares the PacketSize bytes at the address Irp to contain the following items in the following order:

• the fixed-size IRP initialised for StackSize I/O stack locations;
• an array of StackSize IO_STACK_LOCATION structures;
• if the DeviceObject requires it, space for as many additional IO_STACK_LOCATION structures as can instead contain one IOP_IRP_EXTENSION.

Beware that the function simply assumes that PacketSize is large enough for these items. To discover in advance what PacketSize suffices, present the same DeviceObject and StackSize to the IoSizeOfIrpEx function.