IoBuildAsynchronousFsdRequest

The IoBuildAsynchronousFsdRequest routine allocates and sets up an IRP to be sent to lower-level drivers.

PIRP 
  IoBuildAsynchronousFsdRequest(
    IN ULONG  MajorFunction,
    IN PDEVICE_OBJECT  DeviceObject,
    IN OUT PVOID  Buffer  OPTIONAL,
    IN ULONG  Length  OPTIONAL,
    IN PLARGE_INTEGER  StartingOffset  OPTIONAL,
    IN PIO_STATUS_BLOCK  IoStatusBlock  OPTIONAL
    );

Parameters

MajorFunction

Specifies the major function code to be set in the IRP, one of IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS, or IRP_MJ_SHUTDOWN.

DeviceObject

Pointer to the next-lower driver’s device object, representing the target device for the read, write, flush, or shutdown operation.

Buffer

Pointer to a buffer into which data is read or from which data is written. The value of this argument is NULL for flush and shutdown requests.

Length

Specifies the length in bytes of Buffer. The value of this argument is zero for flush and shutdown requests.

StartingOffset

Pointer to the starting offset on the input/output media. The value of this argument is zero for flush and shutdown requests.

IoStatusBlock

Pointer to the address of an I/O status block in which the to-be-called driver(s) return final status about the requested operation.

Return Value

IoBuildAsynchronousFsdRequest returns a pointer to an IRP or a NULL pointer if the IRP cannot be allocated.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

Intermediate or highest-level drivers can call IoBuildAsynchronousFsdRequest to set up IRPs for requests sent to lower-level drivers. The calling driver must supply anIoCompletion routine for the IRP, so the IRP can be deallocated with IoFreeIrp.

The IRP that gets built contains only enough information to get the operation started and to complete the IRP. No other context information is tracked because an asynchronous request is context-independent.

Lower-level drivers might impose restrictions on parameters supplied to this routine. For example, disk drivers might require that values supplied for Length and StartingOffset be integrals of the device's sector size.

Callers of IoBuildAsynchronousFsdRequest must be running at IRQL <= DISPATCH_LEVEL.

An intermediate or highest-level driver also can call IoBuildDeviceIoControlRequest, IoAllocateIrp, or IoBuildSynchronousFsdRequest to set up requests it sends to lower-level drivers. Only a highest-level driver can call IoMakeAssociatedIrp.

See Also

IO_STACK_LOCATION, IoAllocateIrp, IoBuildDeviceIoControlRequest, IoBuildSynchronousFsdRequest, IoCallDriver, IoFreeIrp, IoMakeAssociatedIrp, IoSetCompletionRoutine, IRP