ZwDeviceIoControlFile 函数（ntifs.h）

项目
12/21/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 返回的文件对象的句柄，表示应向其提供控件信息的设备或从中返回哪些信息。如果调用方指定事件、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（如果已指定），或者完成上下文包含在 I/O 管理器发布到关联的 I/O 完成对象的完成消息中。

此参数是可选的，可以 NULL。如果 ApcRoutineNULL 并且没有与文件对象关联的 I/O 完成对象，则必须 NULL。

[out] IoStatusBlock

指向接收最终完成状态和有关操作信息的变量的指针。对于返回数据的成功调用，在信息成员中返回写入 OutputBuffer 的字节数。

[in] IoControlCode

IOCTL_XXX 代码，该代码指示要对哪些设备 I/O 控制操作执行，通常由基础设备驱动程序执行。此参数的值确定 InputBuffer 和 OutputBuffer的格式和所需长度，以及以下哪些参数对是必需的。有关系统定义、特定于设备类型的IOCTL_XXX 代码的详细信息，请参阅 Microsoft Windows SDK 文档中Microsoft Windows 驱动程序工具包（WDK）文档设备技术特定部分，以及设备输入和输出控制代码。

[in, optional] InputBuffer

指向调用方分配的输入缓冲区的指针，该缓冲区包含要提供给目标设备的特定于设备的信息。如果 IoControlCode 指定不需要输入数据的操作，则可以 NULL此指针。

[in] InputBufferLength

InputBuffer处缓冲区的大小（以字节为单位）。如果 InputBufferNULL，请将 inputBufferLength 设置为零。

[out, optional] OutputBuffer

指向调用方分配的输出缓冲区的指针，在该缓冲区中从目标设备返回信息。如果 IoControlCode 指定不生成输出数据的操作，则可以将此指针 NULL。

[in] OutputBufferLength

OutputBuffer处缓冲区的大小（以字节为单位）。如果 OutputBuffer NULL，请将 outputBufferLength 设置为零。

返回值

如果基础驱动程序成功执行请求的操作，ZwDeviceIoControlFile 返回STATUS_SUCCESS。否则，返回值可以是从基础驱动程序传播的错误状态代码。可能的错误状态代码包括：

言论

ZwDeviceIoControlFile 为系统和内核模式驱动程序提供输入和输出数据的一致视图，同时为应用程序和基础驱动程序提供设备相关的指定通信接口的方法。

有关系统定义IOCTL_XXX 代码以及定义特定于驱动程序的 IOCTL_XXX 或 FSCTL_XXX 值的详细信息，请参阅内核模式体系结构指南和 Windows SDK 文档中 Microsoft的设备输入和输出控制代码使用 I/O 控制代码。

如果调用方为异步 I/O 打开文件（未FILE_SYNCHRONOUS_XXX 创建/打开选项集），则指定事件（如果有）将在设备控制操作完成时设置为信号状态。否则，FileHandle 指定的文件对象将设置为信号状态。如果指定了 ApcRoutine，则会使用 ApcContext 和 IoStatusBlock 指针调用它。

微型筛选器应使用 FltDeviceIoControlFile 而不是 ZwDeviceIoControlFile。

ZwDeviceIoControlFile 的调用方必须在 IRQL = PASSIVE_LEVEL上运行，启用了特殊内核 APC。

注意如果对 ZwDeviceIoControlFile 函数的调用在用户模式下发生，则应使用名称“NtDeviceIoControlFile”而不是“ZwDeviceIoControlFile”。

对于内核模式驱动程序的调用，Windows Native System Services 例程的 **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。
目标平台	普遍
标头	ntifs.h （include Ntifs.h， Ntddk.h）
库	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL（请参阅“备注”部分）
DDI 符合性规则	HwStorPortProhibitedDIS（storport），PowerIrpDDis（wdm）