NtSetInformationFile 函式 (ntifs.h)
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 |
另請參閱
FILE_IO_PRIORITY_HINT_INFORMATION