Hardware Dev Center

Collapse the table of content
Expand the table of content
Expand Minimize

IoBuildSynchronousFsdRequest routine

The IoBuildSynchronousFsdRequest routine allocates and sets up an IRP for a synchronously processed I/O request.

Syntax


PIRP IoBuildSynchronousFsdRequest(
  _In_     ULONG            MajorFunction,
  _In_     PDEVICE_OBJECT   DeviceObject,
  _Inout_  PVOID            Buffer,
  _In_opt_ ULONG            Length,
  _In_opt_ PLARGE_INTEGER   StartingOffset,
  _In_     PKEVENT          Event,
  _Out_    PIO_STATUS_BLOCK IoStatusBlock
);

Parameters

MajorFunction [in]

The major function code for the IRP. This code can be IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS, or IRP_MJ_SHUTDOWN.

DeviceObject [in]

A pointer to the DEVICE_OBJECT structure for the next-lower driver's device object, which represents the target device.

Buffer [in, out]

A pointer to a data buffer. If MajorFunction is IRP_MJ_WRITE, the buffer contains data to be written. If MajorFunction is IRP_MJ_READ, the buffer receives data. If MajorFunction is IRP_MJ_FLUSH_BUFFERS or IRP_MJ_SHUTDOWN, this parameter must be NULL.

Length [in, optional]

The length, in bytes, of the buffer pointed to by Buffer. For devices such as disks, this value must be an integer multiple of the sector size. Starting with Windows 8, the sector size can be 4,096 or 512 bytes. In earlier versions of Windows, the sector size is always 512 bytes. This parameter is required for read and write requests, but must be zero for flush and shutdown requests.

StartingOffset [in, optional]

A pointer to the offset on the disk, for read and write requests. The units and meaning of this value are driver-specific. This parameter is required for read and write requests, but must be zero for flush and shutdown requests.

Event [in]

A pointer to a caller-allocated and initialized event object. The I/O manager sets the event to the Signaled state when a lower-level driver completes the requested operation. After calling IoCallDriver, the driver can wait for the event object.

IoStatusBlock [out]

A pointer to a location that receives the I/O status block that is set when the IRP is completed by a lower-level driver.

Return value

If the operation succeeds, IoBuildSynchronousFsdRequest returns a pointer to an initialized IRP structure, with the next-lower driver's I/O stack location set up from the supplied parameters. Otherwise, the routine returns NULL.

Remarks

A file system driver (FSD) or other higher-level driver can call IoBuildSynchronousFsdRequest to set up IRPs that it synchronously sends to lower-level drivers.

IoBuildSynchronousFsdRequest allocates and sets up an IRP that requests lower-level drivers to perform a synchronous read, write, flush, or shutdown operation. The IRP contains enough information to start the operation.

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 integer multiples of the device's sector size.

After calling IoBuildSynchronousFsdRequest to create a request, the driver must call IoCallDriver to send the request to the next-lower driver. If IoCallDriver returns STATUS_PENDING, the driver must wait for the completion of the IRP by calling KeWaitForSingleObject on the given Event. Most drivers do not need to set an IoCompletion routine for the IRP.

IRPs that are created by IoBuildSynchronousFsdRequest must be completed by a driver's call to IoCompleteRequest. A driver that calls IoBuildSynchronousFsdRequest must not call IoFreeIrp, because the I/O manager frees these synchronous IRPs after IoCompleteRequest has been called.

IoBuildSynchronousFsdRequest queues the IRPs that it creates to an IRP queue that is specific to the current thread. If the thread exits, the I/O manager cancels the IRP.

Requirements

Target platform

Universal

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

<= APC_LEVEL

DDI compliance rules

ForwardedAtBadIrqlFsdSync, IoBuildSynchronousFsdRequestNoFree, IoBuildSynchronousFsdRequestWait, IoBuildSynchronousFsdRequestWaitTimeout, PowerIrpDDis, SignalEventInCompletion, HwStorPortProhibitedDDIs

See also

IO_STACK_LOCATION
IoAllocateIrp
IoBuildAsynchronousFsdRequest
IoBuildDeviceIoControlRequest
IoCompleteRequest
IRP
KeInitializeEvent
KeWaitForSingleObject

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft