ioBuildDeviceIoControlRequest 函式 (wdm.h)

發行項
02/27/2024

IoBuildDeviceIoControlRequest 例程會配置並設定 IRP，以取得同步處理的裝置控制要求。

語法

__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
  [in]            ULONG            IoControlCode,
  [in]            PDEVICE_OBJECT   DeviceObject,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength,
  [in]            BOOLEAN          InternalDeviceIoControl,
  [in, optional]  PKEVENT          Event,
  [out]           PIO_STATUS_BLOCK IoStatusBlock
);

參數

[in] IoControlCode

提供 I/O 控制項程式代碼， (IOCTL) 用於要求中。如需裝置類型特定 I/O 控制碼的相關信息，請參閱 Windows 驅動程式套件 (WDK) 中的裝置類型特定區段。

[in] DeviceObject

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

[in, optional] InputBuffer

提供要傳遞至較低驅動程式之輸入緩衝區的指標，如果要求未將輸入數據傳遞至較低的驅動程式，則為 NULL 。

[in] InputBufferLength

提供輸入緩衝區的長度，以位元組為單位。如果 InputBuffer 為 NULL，InputBufferLength 必須為零。

[out, optional] OutputBuffer

提供輸出緩衝區的指標，其中較低驅動程式會傳回數據，如果要求不需要較低的驅動程式傳回數據，則為 NULL 。

[in] OutputBufferLength

提供輸出緩衝區的長度，以位元組為單位。如果 OutputBuffer 為 NULL，OutputBufferLength 必須為零。

[in] InternalDeviceIoControl

如果為 TRUE，則例程會將 IRP 的主要函式程式碼設定為IRP_MJ_INTERNAL_DEVICE_CONTROL。否則，例程會將 IRP 的主要函式程式代碼設定為 IRP_MJ_DEVICE_CONTROL。

[in, optional] Event

提供呼叫端配置和初始化事件物件的指標。當較低層級驅動程式完成要求的作業時，I/O 管理員會將事件設定為 Signaled 狀態。呼叫 IoCallDriver之後，驅動程式可以等候事件物件。 Event 參數是選擇性的，而且可以設定為 NULL。不過，如果 Event 為 NULL，呼叫端必須提供 IoCompletion 例程給 IRP，以在作業完成時通知呼叫端。

[out] IoStatusBlock

指定當要求由較低驅動程式完成時要設定的 I/O 狀態區塊。

傳回值

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

備註

驅動程式可以呼叫 IoBuildDeviceIoControlRequest ，為裝置控制要求設定 IRP，以同步傳送至較低層級的驅動程式。

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

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

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

如果呼叫端提供 InputBuffer 或 OutputBuffer 參數，此參數必須指向位於系統記憶體中的緩衝區。呼叫端負責驗證從使用者模式緩衝區複製到輸入緩衝區的任何參數值。輸入緩衝區可能包含參數值，根據要求的來源是使用者模式應用程式或內核模式驅動程式而定，以不同的方式解譯。在 IoBuildDeviceIoControlRequest 傳回的 IRP 中， RequestorMode 字段一律會設定為 KernelMode。這個值表示要求和要求中包含的任何資訊都是來自受信任的內核模式元件。

如果呼叫端無法驗證其從使用者模式緩衝區複製到輸入緩衝區的參數值，或如果這些值不得解譯為來自內核模式元件，則呼叫端應該將 IRP 中的 RequestorMode 字段設定為 UserMode。此設定會通知驅動程式處理緩衝區包含不受信任、使用者模式數據的 I/O 控制項要求。

在 IRP 中儲存 InputBuffer 和 OutputBuffer 參數內容的實際方法，取決於 IOCTL 的 TransferType 值。如需此值的詳細資訊，請參閱 I/O 控制代碼的緩衝區描述。

規格需求

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