ZwDeviceIoControlFile 函数 (ntifs.h)
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_
[in, optional] InputBuffer
指向调用方分配的输入缓冲区的指针,该缓冲区包含要提供给目标设备的特定于设备的信息。 如果 IoControlCode 指定不需要输入数据的操作,则可以 NULL此指针。
[in] InputBufferLength
InputBuffer处缓冲区的大小(以字节为单位)。 如果 InputBufferNULL,请将 inputBufferLength 设置为零。
[out, optional] OutputBuffer
指向调用方分配的输出缓冲区的指针,在该缓冲区中从目标设备返回信息。 如果 IoControlCode 指定不生成输出数据的操作,则可以将此指针 NULL。
[in] OutputBufferLength
OutputBuffer处缓冲区的大小(以字节为单位)。 如果
返回值
如果基础驱动程序成功执行请求的操作,ZwDeviceIoControlFile 返回STATUS_SUCCESS。 否则,返回值可以是从基础驱动程序传播的错误状态代码。 可能的错误状态代码包括:
言论
ZwDeviceIoControlFile 为系统和内核模式驱动程序提供输入和输出数据的一致视图,同时为应用程序和基础驱动程序提供设备相关的指定通信接口的方法。
有关系统定义IOCTL_
如果调用方为异步 I/O 打开文件(未FILE_SYNCHRONOUS_XXX 创建/打开选项集),则指定事件(如果有)将在设备控制操作完成时设置为信号状态。 否则,FileHandle 指定的文件对象将设置为信号状态。 如果指定了 ApcRoutine,则会使用 ApcContext 和 IoStatusBlock 指针调用它。
微型筛选器应使用 FltDeviceIoControlFile 而不是 ZwDeviceIoControlFile。
ZwDeviceIoControlFile 的调用方必须在 IRQL = PASSIVE_LEVEL上运行,启用了特殊内核 APC。
要求
要求 | 价值 |
---|---|
最低支持的客户端 | Windows 2000。 |
目标平台 | 普遍 |
标头 | ntifs.h (include Ntifs.h, Ntddk.h) |
库 | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL(请参阅“备注”部分) |
DDI 符合性规则 | HwStorPortProhibitedDIS(storport),PowerIrpDDis(wdm) |
另请参阅
使用 I/O 控制代码