ZwSetInformationFile 函式 (wdm.h)

發行項
02/27/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 結構的指標。 Information 成員會收到檔案上設定的位元組數目。

[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 旗標。
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 ，但無法傳遞至任何其他 ZwXxx 檔案 例程。因為 FileDispositionInformation 會導致檔案標示為要刪除，所以程式設計錯誤是在關閉檔案以外的句柄上嘗試任何後續作業。

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

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

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

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

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

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

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)