IoBuildSynchronousFsdRequest 函式 (wdm.h)

發行項
02/29/2024

IoBuildSynchronousFsdRequest 例程會為同步處理的 I/O 要求配置並設定 IRP。

語法

__drv_aliasesMem PIRP IoBuildSynchronousFsdRequest(
  [in]           ULONG            MajorFunction,
  [in]           PDEVICE_OBJECT   DeviceObject,
  [in, out]      PVOID            Buffer,
  [in, optional] ULONG            Length,
  [in, optional] PLARGE_INTEGER   StartingOffset,
  [in]           PKEVENT          Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock
);

參數

[in] MajorFunction

IRP 的主要函式程序代碼。此程式代碼可以是 IRP_MJ_PNP、 IRP_MJ_READ、 IRP_MJ_WRITE、 IRP_MJ_FLUSH_BUFFERS或 IRP_MJ_SHUTDOWN。

[in] DeviceObject

下一個較低驅動程式裝置物件的 DEVICE_OBJECT 結構的指標，代表目標裝置。

[in, out] Buffer

數據緩衝區的指標。如果MajorFunction是IRP_MJ_WRITE，則緩衝區會包含要寫入的數據。如果MajorFunction是IRP_MJ_READ，則緩衝區會接收數據。如果MajorFunction是IRP_MJ_FLUSH_BUFFERS或IRP_MJ_SHUTDOWN，此參數必須是NULL。

[in, optional] Length

Buffer 所指向之緩衝區的長度，以位元組為單位。對於磁碟之類的裝置，此值必須是扇區大小的整數倍數。從 Windows 8 開始，扇區大小可以是 4,096 或 512 個字節。在舊版 Windows 中，扇區大小一律為 512 個字節。讀取和寫入要求需要此參數，但排清和關機要求必須為零。

[in, optional] StartingOffset

磁碟上位移的指標，用於讀取和寫入要求。此值的單位和意義是驅動程式特定的。讀取和寫入要求需要此參數，但排清和關機要求必須為零。

[in] Event

呼叫端配置和初始化事件物件的指標。當較低層級驅動程式完成要求的作業時，I/O 管理員會將事件設定為 Signaled 狀態。呼叫 IoCallDriver之後，驅動程式可以等候事件物件。

[out] IoStatusBlock

接收較低層級驅動程式完成 IRP 時所設定之 I/O 狀態區塊的位置指標。

傳回值

如果作業成功， IoBuildSynchronousFsdRequest 會傳回已初始化 IRP 結構的指標，並從提供的參數設定下一個較低驅動程式的 I/O 堆棧位置。否則，例程會傳回 NULL。

備註

文件系統驅動程式 (FSD) 或其他較高層級驅動程式可以呼叫 IoBuildSynchronousFsdRequest ，以設定同步傳送至較低層級驅動程式的 IRP。

IoBuildSynchronousFsdRequest 會配置並設定 IRP，要求較低層級的驅動程式執行同步讀取、寫入、排清或關機作業。 IRP 包含足夠的資訊來啟動作業。

較低層級的驅動程式可能會對提供給此例程的參數施加限制。例如，磁碟驅動器可能需要為 Length 和 StartingOffset 提供的值是裝置扇區大小的整數倍數。

呼叫 IoBuildSynchronousFsdRequest 以建立要求之後，驅動程式必須呼叫 IoCallDriver ，以將要求傳送至下一個較低的驅動程式。如果 IoCallDriver 傳回STATUS_PENDING，則驅動程式必須在指定的事件上呼叫 KeWaitForSingleObject，等候 IRP 完成。大部分驅動程式不需要為 IRP 設定 IoCompletion 例程。

IoBuildSynchronousFsdRequest 所建立的 IRP 必須由驅動程式呼叫 IoCompleteRequest 來完成。呼叫 IoBuildSynchronousFsdRequest 的驅動程式不得呼叫 IoFreeIrp，因為 I/O 管理員會在 呼叫 IoCompleteRequest 之後釋出這些同步 IRP。

IoBuildSynchronousFsdRequest 會將它建立的 IRP 排入目前線程專屬的 IRP 佇列。如果線程結束，I/O 管理員會取消 IRP。

規格需求

需求	值
最低支援的用戶端	從 Windows 2000 開始提供。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI 合規性規則	ForwardedAtBadIrqlFsdSync (wdm) 、 HwStorPortProhibitedDDIs (storport) 、 IoBuildSynchronousFsdRequestNoFree (wdm) 、 IoBuildSynchronousFsdRequestWait (wdm) 、 IoBuildSynchronousFsdRequestWaitTimeout (wdm) 、 PowerIrpDDis (wdm) 、 SignalEventInCompletion (wdm)