NtSetInformationFile 函式 (ntifs.h)

發行項
02/26/2024

NtSetInformationFile 例程會變更各種有關檔案對象的資訊。

語法

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

參數

[in] FileHandle

檔案物件的句柄。此句柄是由 成功呼叫 NtCreateFile 或 NtOpenFile 所建立。

[out] IoStatusBlock

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

[in] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

FILE_INFORMATION_CLASS值	傳回的信息類型
FileBasicInformation (4)	變更 FILE_BASIC_INFORMATION 結構中提供的資訊。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定FILE_WRITE_ATTRIBUTES旗標。
FileRenameInformation (10)	變更目前提供於 FILE_RENAME_INFORMATION 結構中的檔名。呼叫端必須具有檔案的 DELETE 存取權。
FileDispositionInformation (13)	當檔案關閉或取消先前要求的刪除時，要求刪除檔案。選擇是否要在 FILE_DISPOSITION_INFORMATION 結構中提供刪除或取消。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定 DELETE 旗標。
FilePositionInformation (14)	變更儲存在 FILE_POSITION_INFORMATION 結構中的目前檔案資訊。
FileEndOfFileInformation (20)	變更 FILE_END_OF_FILE_INFORMATION結構中提供的目前檔尾資訊。作業可以截斷或擴充檔案。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定FILE_WRITE_DATA旗標。
FileValidDataLengthInformation (39)	變更檔案的目前有效數據長度，這是在 FILE_VALID_DATA_LENGTH_INFORMATION 結構中提供。檔案必須位於NTFS磁碟區上，而且呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定FILE_WRITE_DATA旗標。非系統管理員和遠端用戶必須具有 SeManageVolumePrivilege 許可權。
FileShortNameInformation (40)	變更 FILE_NAME_INFORMATION結構中提供的目前簡短檔名。檔案必須位於NTFS磁碟區上，而且呼叫端必須已開啟在 DesiredAccess 參數中設定 DesiredAccess DELETE 旗標的檔案。
FileIoPriorityHintInformation (43)	變更檔案句柄目前的預設 IRP 優先順序提示。新值會以 FILE_IO_PRIORITY_HINT_INFORMATION 結構提供。這個結構必須對齊 8 位元組。
FileReplaceCompletionInformation (61)	變更或移除指定之檔句柄的 I/O 完成埠。呼叫端會提供指定埠句柄和完成索引鍵之FILE_COMPLETION_INFORMATION 結構的指標。如果埠句柄不是 NULL，此句柄會指定新的 I/O 完成埠，以與檔句柄產生關聯。若要移除與檔句柄相關聯的 I/O 完成埠，請將結構中的埠句柄設定為 NULL。若要取得埠句柄，使用者模式呼叫端可以呼叫 CreateIoCompletionPort 函式。
FileDispositionInformationEx (64)	要求刪除檔案或取消先前要求的刪除。是否要在FILE_DISPOSITION_INFORMATION_EX結構中提供刪除或取消的選項，以及何時及如何執行刪除的設定。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定 DELETE 旗標。
FileCaseSensitiveInformation (71)	變更 FILE_CASE_SENSITIVE_INFORMATION 結構中提供的資訊。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定FILE_WRITE_ATTRIBUTES旗標。此值從 Windows 10 1803 版開始提供。
FileLinkInformation (72)	建立現有檔案的硬式連結，該檔案是在FILE_LINK_INFORMATION 結構中指定的。並非所有文件系統都支援硬式連結;例如，NTFS 會執行，但 FAT 則不會。
FileCaseSensitiveInformationForceAccessCheck (75)	變更 FILE_CASE_SENSITIVE_INFORMATION 結構中提供的資訊。呼叫端必須已開啟檔案，並在 DesiredAccess 參數中設定FILE_WRITE_ATTRIBUTES旗標。這是 FileCaseSensitiveInformation 作業的特殊版本，可用來強制 IOManager 執行核心模式驅動程式的存取檢查，類似於套用至使用者模式呼叫端的檢查。這項作業只能由IOManager辨識，而且文件系統絕對不會收到。此值從 Windows 10 1803 版開始提供。
FileKnownFolderInformation (76)	FILE_KNOWN_FOLDER_INFORMATION 結構。從 Windows Server 2022 開始提供。

傳回值

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

備註

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

如果您將 FileInformationClass 設定為 FileDispositionInformation，您後續可以將 FileHandle 傳遞至 NtClose ，但不能傳遞至任何其他 ZwXxx 檔案例程。由於 FileDispositionInformation 會導致檔案標示為要刪除，因此程式設計錯誤是嘗試在句柄上執行任何後續作業，而不是將其關閉。

如果您將 FileInformationClass 設定為 FilePositionInformation，且上述對 NtCreateFile 的呼叫包含 CreateOptions 參數中的 FILE_NO_INTERMEDIATE_BUFFERING 旗標，則會強制執行FILE_POSITION_INFORMATION 結構的 CurrentByteOffset 成員某些限制。如需詳細資訊，請參閱 NtCreateFile。

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

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

NtSetInformationFile 的呼叫端必須在 IRQL = PASSIVE_LEVEL且啟用特殊核心 APC 時執行。

注意

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

針對來自內核模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本會以處理和解譯輸入參數的方式，以不同的方式運作。如需 NtXxx*** 和 ZwXxx*** 例程版本之間關聯性的詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

規格需求

需求	值
最低支援的用戶端	Windows 2000。
目標平台	Universal
標頭	ntifs.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則	HwStorPortProhibitedDIS、 PowerIrpDDis