ZwSetInformationFile 函式（wdm.h）

發行項
11/07/2024

ZwSetInformationFile 例程會變更檔案物件的各種資訊。

語法

NTSYSAPI NTSTATUS ZwSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

參數

[in] FileHandle

檔案物件的句柄。這個句柄是透過成功呼叫 ZwCreateFile 或 ZwOpenFile所建立。

[out] IoStatusBlock

IO_STATUS_BLOCK 結構的指標，該結構會接收最終完成狀態和要求之作業的相關信息。資訊成員會收到檔案上設定的位元元組數目。

[in] FileInformation

緩衝區的指標，其中包含要為檔案設定的資訊。這個緩衝區中的特定結構是由 fileInformationClass 參數所決定。例如，如果 fileInformationClass 參數設定為 FileDispositionInformationEx 常數，此參數應該是 FILE_DISPOSITION_INFORMATION_EX 結構的指標。

[in] Length

FileInformation 緩衝區的大小，以位元組為單位。

[in] FileInformationClass

FileInformation所指向之緩衝區中提供的資訊類型，為檔案設定。裝置和中繼驅動程式可以指定下列任何 FILE_INFORMATION_CLASS 值。

FileInformationClass 值	意義
FileBasicInformation	變更 FILE_BASIC_INFORMATION 結構中提供的資訊。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定FILE_WRITE_ATTRIBUTES旗標。
FileDispositionInformation	當檔案關閉或取消先前要求的刪除時，要求刪除該檔案。選擇是否要在 FILE_DISPOSITION_INFORMATION 結構中提供刪除或取消。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定 DELETE 旗標。
FileDispositionInformationEx	要求刪除檔案或取消先前要求的刪除。選擇是否要刪除或取消，以及何時及應如何執行刪除的設定，都會在 FILE_DISPOSITION_INFORMATION_EX 結構中提供。呼叫端必須開啟檔案，並在 desiredAccess 參數設定 DELETE** 旗標。
FileEndOfFileInformation	變更 FILE_END_OF_FILE_INFORMATION 結構中提供的目前檔尾資訊。作業可以截斷或擴充檔案。呼叫端必須已開啟檔案，並在 desiredAccess 參數中設定FILE_WRITE_DATA旗標。
FileIoPriorityHintInformation	變更檔案句柄目前的預設 IRP 優先順序提示。新值會在 FILE_IO_PRIORITY_HINT_INFORMATION 結構中提供。此結構必須對齊 8 位元組。
FileLinkInformation	建立現有檔案的硬連結，該檔案是在 FILE_LINK_INFORMATION 結構中指定的。並非所有文件系統都支援硬式連結;例如，NTFS 在 FAT 未執行時執行。
FilePositionInformation	變更儲存在 FILE_POSITION_INFORMATION 結構中的目前檔案資訊。
FileRenameInformation	變更 FILE_RENAME_INFORMATION 結構中提供的目前檔名。呼叫端必須具有檔案的 DELETE 存取權。
FileShortNameInformation	變更目前簡短的檔名，其提供於 FILE_NAME_INFORMATION 結構中。檔案必須位於NTFS磁碟區上，而且呼叫端必須已開啟檔案，並在 desiredAccess 參數中設定的 DesiredAccess DELETE 旗標。
FileIoCompletionNotificationInformation	變更檔案 IO 完成通知旗標。支援與 SetFileCompletionNotificationModes相同的旗標。
FileValidDataLengthInformation	變更檔案目前的有效數據長度，該檔案是在 FILE_VALID_DATA_LENGTH_INFORMATION 結構中提供。檔案必須位於NTFS磁碟區上，而且呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定FILE_WRITE_DATA旗標。非系統管理員和遠端用戶必須具有 SeManageVolumePrivilege 許可權。
FileReplaceCompletionInformation	變更或移除指定之檔句柄的 I/O 完成埠。呼叫端會提供指定埠句柄和完成鍵之 FILE_COMPLETION_INFORMATION 結構的指標。如果埠句柄不是 NULL，此句柄會指定新的 I/O 完成埠，以與檔句柄產生關聯。若要移除與檔句柄相關聯的 I/O 完成埠，請將結構中的埠句柄設定為 NULL。若要取得埠句柄，使用者模式呼叫端可以呼叫 createIoCompletionPort 函式。

傳回值

ZwSetInformationFile 會傳回STATUS_SUCCESS或適當的錯誤狀態。

言論

ZwSetInformationFile 變更檔案的相關信息。它會忽略特定裝置或檔案系統不支援 FILE_XXX_INFORMATION 結構的任何成員。

如果您將 FileInformationClass 設定為 FileDispositionInformation，您接著可以將 FileHandle 傳遞至 ZwClose ZwClose，但不會傳遞至任何其他 ZwXxxFile 例程。因為 FileDispositionInformation 導致檔案標示為要刪除，所以程式設計錯誤是在關閉檔案以外的句柄上嘗試任何後續作業。

如果您 將 FileInformationClass 設定為 FilePositionInformation，且上述 ZwCreateFile 的呼叫 包含 CreateOptions 參數中的FILE_NO_INTERMEDIATE_BUFFERING旗標，則會強制執行 CurrentByteOffsetFILE_POSITION_INFORMATION 成員的特定限制。如需詳細資訊，請參閱 ZwCreateFile。

如果您 將 FileInformationClass 設定為 FileEndOfFileInformation，且 FILE_END_OF_FILE_INFORMATION 的 EndOfFile 成員會指定超出目前檔尾標記的位移，ZwSetInformationFile 會擴充檔案，並將擴展名填補為零。

如需使用檔案的詳細資訊，請參閱在驅動程式中使用檔案。

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

如果呼叫此函式發生在使用者模式中，您應該使用名稱「NtSetInformationFile」而不是「ZwSetInformationFile」。。

對於內核模式驅動程式的呼叫，NtXxx 和 ZwXxx 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。如需 nt NtXxx 與 ZwXxx 例程之間關聯性的詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

要求

要求	價值
目標平臺	普遍
標頭	wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL （請參閱一節）
DDI 合規性規則	HwStorPortProhibitedDIs（storport），PowerIrpDDis（wdm）