IoBuildSynchronousFsdRequest

IoBuildSynchronousFsdRequest

PIRP
IoBuildSynchronousFsdRequest(
IN ULONG MajorFunction,
IN PDEVICE_OBJECT DeviceObject,
IN OUT PVOID Buffer,/* optional */
IN ULONG Length,/* optional */
IN PLARGE_INTEGER StartingOffset,/* optional */
IN PKEVENT Event,
OUT PIO_STATUS_BLOCK IoStatusBlock
);

IoBuildSynchronousFsdRequest allocates and builds IRP to be sent synchronously to lower driver(s).

Parameters

MajorFunction

Specifies the major function code, one of IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS, or IRP_MJ_SHUTDOWN.

DeviceObject

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

Buffer

Points to a buffer containing data to be written when MajorFunction is IRP_MJ_WRITE, or is the location to receive data read when MajorFunction is IRP_MJ_READ. This parameter must be NULL for the MajorFunction IRP_MJ_FLUSH_BUFFERS or IRP_MJ_SHUTDOWN.

Length

Specifies the length, in bytes, of Buffer. For devices such as disks, this value must be an integral of 512. This parameter is required for read/write requests, but must be zero for flush and shutdown requests.

StartingOffset

Points to the offset on the disk to read/write from/to. This parameter is required for read/write requests, but must be zero for flush and shutdown requests.

Event

Points to an initialized event object for which the caller provides the storage. The event is set to the Signaled state when the requested operation completes. The caller can wait on the event object for the completion of the IRP allocated by this routine.

IoStatusBlock

Points to the I/O status block that is set when the IRP is completed by the lower driver(s).

Return Value

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

Comments

Intermediate or highest-level drivers can call IoBuildSynchronousFsdRequest to set up IRPs for requests sent to lower-level drivers, only if the caller is running in a nonarbitrary thread context and at IRQL PASSIVE_LEVEL.

IoBuildSynchronousFsdRequest allocates and sets up an IRP that can be sent to a device driver to perform a synchronous read, write, flush, or shutdown operation. The IRP contains only enough information to get the operation started.

The caller can determine when the I/O has completed by calling KeWaitForSingleObject with the Event. Performing this wait operation causes the current thread to wait. Therefore, this operation can be requested during the initialization of an intermediate driver or from an FSD in the context of a thread requesting a synchronous I/O operation. A driver cannot wait for a nonzero interval on the Event at raised IRQL in an arbitrary thread context.

Because the caller can wait on a given Event, the caller need not set an IoCompletion routine in the caller-allocated IRP before calling IoCallDriver. When the caller completes the IRP, the I/O Manager releases it.