ZwFsControlFile 函数 (ntifs.h)

ZwFsControlFile 例程将控制代码直接发送到指定的文件系统或文件系统筛选器驱动程序,导致相应的驱动程序执行指定的操作。

语法

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

参数

[in] FileHandle

ZwCreateFileZwOpenFile 为表示要对其执行指定操作的文件或目录的文件对象返回的句柄。 如果调用方在 ApcContext) 中指定事件ApcRoutine 和 APC 上下文 (,或 ApcContext) 中的完成上下文 (,则必须为异步 I/O 打开文件对象。

[in, optional] Event

调用方创建的事件的句柄。 如果提供了此参数,则调用方将处于等待状态,直到请求的操作完成,并且给定事件设置为 Signaled 状态。 此参数是可选的,可为 NULL。 如果调用方将等待 FileHandle 设置为信号状态,则必须为 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

指向接收最终完成状态和操作信息IO_STATUS_BLOCK结构的指针。 对于返回数据的成功调用,将在此结构的信息成员中返回写入 OutputBuffer 的字节数。

[in] FsControlCode

FSCTL_XXX 代码,指示要执行哪个文件系统控制操作。此参数的值确定 InputBufferOutputBuffer 的格式和所需长度,以及以下哪些参数对是必需的。 有关系统定义的FSCTL_XXX 代码的详细信息,请参阅 Microsoft Windows SDK 文档中 DeviceIoControl 参考条目的“备注”部分。

[in, optional] InputBuffer

指向调用方分配的输入缓冲区的指针,其中包含要提供给目标驱动程序的设备特定信息。 如果 FsControlCode 指定不需要输入数据的操作,则此指针是可选的,可为 NULL

[in] InputBufferLength

InputBuffer 上的缓冲区的大小(以字节为单位)。 如果 InputBufferNULL,则忽略此值。

[out, optional] OutputBuffer

指向调用方分配的输出缓冲区的指针,在该缓冲区中从目标驱动程序返回信息。 如果 FsControlCode 指定不生成输出数据的操作,则此指针是可选的,可为 NULL

[in] OutputBufferLength

OutputBuffer 上的缓冲区的大小(以字节为单位)。 如果 OutputBufferNULL,则忽略此值。

返回值

ZwFsControlFile 返回STATUS_SUCCESS或相应的 NTSTATUS 值,例如以下值之一:

注解

ZwFsControlFile 为系统和内核模式驱动程序提供输入和输出数据的一致视图,同时为应用程序和基础驱动程序提供依赖于驱动程序的方法来指定通信接口。

如果调用方未FILE_SYNCHRONOUS_XXX 创建/打开选项集) 打开 (文件,则设备控制操作完成时,指定的事件(如果有)将设置为信号状态。 否则, FileHandle 指定的文件对象将设置为信号状态。 如果指定 了 ApcRoutine ,则会使用 ApcContextIoStatusBlock 指针调用它。

内核模式驱动程序目前记录了以下 FSCTL 代码:

FSCTL_DELETE_REPARSE_POINT

FSCTL_GET_REPARSE_POINT

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FSCTL_SET_REPARSE_POINT

有关系统定义FSCTL_XXX 代码的详细信息,请参阅 Microsoft Windows SDK 文档中 DeviceIoControl 参考条目的“备注”部分。

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

微型筛选器应使用 FltFsControlFile 而不是 ZwFsControlFile

ZwFsControlFile 的调用方必须在 IRQL = PASSIVE_LEVEL且启用了特殊内核 APC 的情况下运行。

注意 如果在用户模式下调用 ZwFsControlFile 函数,则应使用名称“NtFsControlFile”而不是“ZwFsControlFile”。
 
对于内核模式驱动程序的调用,Windows Native System Services 例程的 NtXxxZwXxx 版本在处理和解释输入参数的方式可能有所不同。 有关例程 的 NtXxxZwXxx 版本之间的关系的详细信息,请参阅 使用本机系统服务例程的 Nt 和 Zw 版本

要求

   
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 ntifs.h (包括 Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (请参阅“备注”部分)
DDI 符合性规则 HwStorPortProhibitedDDIs (storport) PowerIrpDDis (wdm)

请参阅

FltFsControlFile

IRP_MJ_FILE_SYSTEM_CONTROL

IoGetFunctionCodeFromCtlCode

IoIsOperationSynchronous

使用 I/O 控制代码

使用本机系统服务例程的 Nt 和 Zw 版本

ZwClose

ZwCreateFile

ZwDeviceIoControlFile

ZwOpenFile