ZwDeviceIoControlFile 函式 (ntifs.h)

發行項
02/29/2024

ZwDeviceIoControlFile 例程會將控件程式代碼直接傳送至指定的設備驅動器，導致對應的驅動程式執行指定的作業。

語法

NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            IoControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

參數

[in] FileHandle

ZwCreateFile 或 ZwOpenFile 所傳回的檔案物件句柄，代表應該提供控件資訊的裝置，或從中傳回哪些資訊。如果呼叫端指定 Event、 ApcRoutine 和 APC 內容 (ApcContext) ，或 ApcContext) 中的完成內容 (，則必須開啟檔案對象以進行異步 I/O。針對基礎大量儲存裝置的 I/O，檔案對象必須已開啟，才能直接存取記憶體裝置 (DASD) 存取。

[in, optional] Event

呼叫端所建立事件的句柄。如果提供此參數，呼叫端將會進入等候狀態，直到要求的作業完成，且指定的事件設定為 Signaled 狀態。此參數是選擇性的，可以是 NULL。如果呼叫端等候 FileHandle 設定為 Signaled 狀態，它必須是 NULL。

[in, optional] ApcRoutine

要求作業完成時，要呼叫的選擇性呼叫端提供APC例程的位址。此參數可以是 Null。如果有與檔案對象相關聯的 I/O 完成物件，則必須是 NULL 。

[in, optional] ApcContext

呼叫端決定內容區域的指標。如果呼叫端提供 APC，這個參數值會當做 APC 內容使用，如果 I/O 完成對象已經與檔案對象相關聯，則會當做完成內容使用。當作業完成時，如果已指定 APC 內容，則會將 APC 內容傳遞至 APC，或者完成內容會包含在 I/O 管理員張貼至相關聯 I/O 完成物件的完成訊息中。

此參數是選擇性的，可以是 NULL。如果 ApcRoutine 是 NULL，而且沒有與檔案對象相關聯的 I/O 完成物件，則必須是 NULL。

[out] IoStatusBlock

接收最終完成狀態和作業相關信息之變數的指標。對於傳回數據的成功呼叫，則會在 Information 成員中傳回寫入 OutputBuffer 的位元元數目。

[in] IoControlCode

IOCTL_XXX 程式代碼，指出要執行哪些裝置 I/O 控制作業，通常是由基礎設備驅動器執行。此參數的值會決定 InputBuffer 和 OutputBuffer 的格式和必要長度，以及下列哪一個參數位是必要的。如需系統定義、裝置類型特定IOCTL_XXX 代碼的詳細資訊，請參閱 Microsoft Windows SDK 檔中 Microsoft Windows Driver Kit (WDK) 檔和裝置輸入和輸出控制代碼的裝置技術特定一節。

[in, optional] InputBuffer

呼叫端配置的輸入緩衝區指標，其中包含要提供給目標裝置的裝置特定資訊。如果 IoControlCode 指定不需要輸入資料的作業，此指標可以是 NULL。

[in] InputBufferLength

InputBuffer 緩衝區的大小，以位元組為單位。如果 InputBuffer 為 NULL，請將 InputBufferLength 設定為零。

[out, optional] OutputBuffer

呼叫端配置的輸出緩衝區指標，其中會從目標裝置傳回資訊。如果 IoControlCode 指定不產生輸出資料的作業，此指標可以是 NULL。

[in] OutputBufferLength

在 OutputBuffer 緩衝區的大小，以位元組為單位。如果 OutputBuffer 為 NULL，請將 OutputBufferLength 設定為零。

傳回值

如果基礎驅動程式 (成功執行要求的作業，ZwDeviceIoControlFile 會傳回STATUS_SUCCESS) 。否則，傳回值可以是從基礎驅動程式傳播的錯誤狀態代碼。可能的錯誤狀態代碼包括：

備註

ZwDeviceIoControlFile 提供系統輸入和輸出數據與核心模式驅動程式的一致檢視，同時為應用程式和基礎驅動程式提供裝置相依方法，以指定通訊介面。

如需系統定義IOCTL_XXX程式代碼的詳細資訊，以及定義驅動程式特定IOCTL_XXX或 FSCTL_XXX值的詳細資訊，請參閱在核心模式架構指南中使用 I/O 控件代碼，以及 Microsoft Windows SDK 檔中的裝置輸入和輸出控制代碼。

如果呼叫端針對異步 I/O (開啟檔案，且FILE_SYNCHRONOUS_XXX 建立/開啟選項都未設定) ，則指定的事件如果有任何，則會在裝置控制作業完成時設定為訊號狀態。否則， FileHandle 指定的檔案物件將會設定為訊號狀態。如果指定 了 ApcRoutine ，則會使用 ApcContext 和 IoStatusBlock 指標呼叫它。

Minifilters 應該使用 FltDeviceIoControlFile ，而不是 ZwDeviceIoControlFile。

ZwDeviceIoControlFile 的呼叫端必須在 IRQL = PASSIVE_LEVEL且啟用特殊核心 APC 時執行。

注意如果在使用者模式中呼叫 ZwDeviceIoControlFile 函式，您應該使用名稱 “NtDeviceIoControlFile”，而不是 “ZwDeviceIoControlFile”。

針對核心模式驅動程式的呼叫，Windows 原生系統服務例程的 **Nt*Xxx** 和 **Zw*Xxx** 版本會以處理和解譯輸入參數的方式不同。如需例程之 **Nt*Xxx** 和 **Zw*Xxx** 版本之間的關聯性詳細資訊，請參閱 [使用 Nt 和 Zw 版本的原生系統服務例程] (/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines) 。

規格需求

需求	值
最低支援的用戶端	Windows 2000。
目標平台	Universal
標頭	ntifs.h (包含 Ntifs.h、Ntddk.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)