ZwFsControlFile 函式（ntifs.h）

發行項
12/21/2024

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

ZwCreateFile 或 ZwOpenFile 所傳回的句柄，代表要執行指定動作之檔案或目錄的檔案物件。如果呼叫端指定事件、ApcRoutine，以及 APC 內容（ApcContext），或完成內容（ApcContext），則檔案對象必須已針對異步 I/O 開啟。

[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。如果 ApcRoutineNULL，而且沒有與檔案對象相關聯的 I/O 完成物件，則必須 NULL。

[out] IoStatusBlock

IO_STATUS_BLOCK結構的指標，該結構會接收最終完成狀態和作業的相關信息。對於傳回數據的成功呼叫，寫入至 OutputBuffer 的位元組數目會傳回至這個結構的 Information 成員中。

[in] FsControlCode

FSCTL_XXX 程式代碼，指出要執行的文件系統控制作業。此參數的值會決定 InputBuffer和 outputBuffer的格式和必要長度，以及下列哪一個參數位是必要的。如需系統定義FSCTL_XXX 程式代碼的詳細資訊，請參閱 Microsoft Windows SDK 檔中 DeviceIoControl 參考專案的一節。

[in, optional] InputBuffer

呼叫端配置的輸入緩衝區指標，其中包含要提供給目標驅動程式的裝置特定資訊。如果 FsControlCode 指定不需要輸入資料的作業，則此指標是選擇性的，而且可以 NULL。

[in] InputBufferLength

InputBuffer緩衝區的大小，以位元組為單位。如果 InputBufferNULL，則會忽略這個值。

[out, optional] OutputBuffer

呼叫端配置的輸出緩衝區指標，其中資訊會從目標驅動程式傳回。如果 FsControlCode 指定不產生輸出資料的作業，則此指標是選擇性的，而且可以 NULL。

[in] OutputBufferLength

OutputBuffer緩衝區的大小，以位元組為單位。如果 outputBuffer NULL，則會忽略此值。

傳回值

ZwFsControlFile 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值，例如下列其中一項：

言論

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

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

核心模式驅動程式目前記載了下列 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 控制碼。

Minifilters 應該使用 FltFsControlFile，而不是 ZwFsControlFile。

ZwFsControlFile 的呼叫端必須在 IRQL = PASSIVE_LEVEL，且啟用特殊核心 APC。

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

對於來自內核模式驅動程式的呼叫，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）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL （請參閱一節）
DDI 合規性規則	HwStorPortProhibitedDIs（storport），PowerIrpDDis（wdm）