Funzione NtSetInformationFile (ntifs.h)

Articolo
02/27/2024

La routine NtSetInformationFile modifica vari tipi di informazioni su un oggetto file.

Sintassi

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

Parametri

[in] FileHandle

Handle all'oggetto file. Questo handle viene creato da una chiamata riuscita a NtCreateFile o NtOpenFile.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e le informazioni sull'operazione richiesta. Il membro Information riceve il numero di byte impostati nel file.

[in] FileInformation

Puntatore a un buffer contenente le informazioni da impostare per il file. La struttura specifica in questo buffer è determinata dal parametro FileInformationClass . Ad esempio, se il parametro FileInformationClass è impostato sulla costante FileDispositionInformationEx, questo parametro deve essere un puntatore a una struttura FILE_DISPOSITION_INFORMATION_EX.

[in] Length

Dimensioni, in byte, del buffer FileInformation .

[in] FileInformationClass

Tipo di informazioni, fornite nel buffer a cui fa riferimento FileInformation, da impostare per il file. I driver di dispositivo e intermedio possono specificare uno dei valori di FILE_INFORMATION_CLASS seguenti.

valore FILE_INFORMATION_CLASS	Tipo di informazioni restituite
FileBasicInformation (4)	Modificare le informazioni fornite in una struttura FILE_BASIC_INFORMATION . Il chiamante deve avere aperto il file con il flag FILE_WRITE_ATTRIBUTES impostato nel parametro DesiredAccess .
FileRenameInformation (10)	Modificare il nome del file corrente, fornito in una struttura FILE_RENAME_INFORMATION . Il chiamante deve avere accesso DELETE al file.
FileDispositionInformation (13)	Richiedere di eliminare il file quando è chiuso o annullare un'eliminazione richiesta in precedenza. La scelta se eliminare o annullare viene fornita in una struttura FILE_DISPOSITION_INFORMATION . Il chiamante deve avere aperto il file con il flag DELETE impostato nel parametro DesiredAccess .
FilePositionInformation (14)	Modificare le informazioni sul file corrente, archiviate in una struttura FILE_POSITION_INFORMATION .
FileEndOfFileInformation (20)	Modificare le informazioni di fine file correnti, fornite in una struttura FILE_END_OF_FILE_INFORMATION . L'operazione può troncare o estendere il file. Il chiamante deve aver aperto il file con il flag FILE_WRITE_DATA impostato nel parametro DesiredAccess .
FileValidDataLengthInformation (39)	Modificare la lunghezza dei dati valida corrente per il file, fornito in una struttura FILE_VALID_DATA_LENGTH_INFORMATION . Il file deve trovarsi in un volume NTFS e il chiamante deve aver aperto il file con il flag di FILE_WRITE_DATA impostato nel parametro DesiredAccess . Gli utenti non amministratori e remoti devono avere il privilegio SeManageVolumePrivilege .
FileShortNameInformation (40)	Modificare il nome del file breve corrente, fornito in una struttura FILE_NAME_INFORMATION . Il file deve trovarsi in un volume NTFS e il chiamante deve aver aperto il file con il flag DesiredAccess DELETE impostato nel parametro DesiredAccess .
FileIoPriorityHintInformation (43)	Modificare l'hint di priorità IRP predefinito corrente per l'handle di file. Il nuovo valore viene fornito in una struttura FILE_IO_PRIORITY_HINT_INFORMATION . Questa struttura deve essere allineata a 8 byte.
FileReplaceCompletionInformation (61)	Modificare o rimuovere la porta di completamento di I/O per l'handle di file specificato. Il chiamante fornisce un puntatore a una struttura FILE_COMPLETION_INFORMATION che specifica un handle di porta e una chiave di completamento. Se l'handle di porta non è NULL, questo handle specifica una nuova porta di completamento di I/O da associare all'handle di file. Per rimuovere la porta di completamento di I/O associata all'handle di file, impostare l'handle di porta nella struttura su NULL. Per ottenere un handle di porta, un chiamante in modalità utente può chiamare la funzione CreateIoCompletionPort .
FileDispositionInformationEx (64)	Richiedere di eliminare il file o annullare un'eliminazione richiesta in precedenza. La scelta se eliminare o annullare, nonché le impostazioni per quando e come eseguire l'eliminazione, vengono fornite in una struttura FILE_DISPOSITION_INFORMATION_EX . Il chiamante deve avere aperto il file con il flag DELETE impostato nel parametro DesiredAccess .
FileCaseSensitiveInformation (71)	Modificare le informazioni fornite in una struttura FILE_CASE_SENSITIVE_INFORMATION . Il chiamante deve avere aperto il file con il flag FILE_WRITE_ATTRIBUTES impostato nel parametro DesiredAccess . Questo valore è disponibile a partire da Windows 10 versione 1803.
FileLinkInformation (72)	Creare un collegamento rigido a un file esistente, specificato in una struttura FILE_LINK_INFORMATION . Non tutti i file system supportano i collegamenti rigidi; ad esempio NTFS non funziona mentre FAT non è.
FileCaseSensitiveInformationForceAccessCheck (75)	Modificare le informazioni fornite in una struttura FILE_CASE_SENSITIVE_INFORMATION . Il chiamante deve avere aperto il file con il flag FILE_WRITE_ATTRIBUTES impostato nel parametro DesiredAccess . Si tratta di una versione speciale dell'operazione FileCaseSensitiveInformation usata per forzare i controlli di accesso per il driver in modalità kernel, analogamente ai controlli che si applicano a un chiamante in modalità utente. Questa operazione viene riconosciuta solo da IOManager e un file system non dovrebbe mai riceverlo. Questo valore è disponibile a partire da Windows 10 versione 1803.
FileKnownFolderInformation (76)	Struttura FILE_KNOWN_FOLDER_INFORMATION . Disponibile a partire da Windows Server 2022.

Valore restituito

NtSetInformationFile restituisce STATUS_SUCCESS o uno stato di errore appropriato.

Commenti

NtSetInformationFile modifica le informazioni su un file. Ignora qualsiasi membro di una struttura FILE_XXX_INFORMATION non supportata da un determinato dispositivo o file system.

Se si imposta FileInformationClass su FileDispositionInformation, è successivamente possibile passare FileHandle a NtClose ma non ad altre routinedi Zw XxxFile. Poiché FileDispositionInformation determina che il file deve essere contrassegnato per l'eliminazione, si tratta di un errore di programmazione per tentare qualsiasi operazione successiva nell'handle diverso da chiuderlo.

Se si imposta FileInformationClass su FilePositionInformation e la chiamata precedente a NtCreateFile include il flag FILE_NO_INTERMEDIATE_BUFFERING nel parametro CreateOptions , vengono applicate alcune restrizioni per il membro CurrentByteOffset della struttura FILE_POSITION_INFORMATION . Per altre informazioni, vedere NtCreateFile.

Se si imposta FileInformationClass su FileEndOfFileInformation e il membro EndOfFile di FILE_END_OF_FILE_INFORMATION specifica un offset oltre il contrassegno finale del file corrente, NtSetInformationFile estende il file e esegue il pad dell'estensione con zero.

Per altre informazioni sull'uso dei file, vedere Uso di file in un driver.

I chiamanti di NtSetInformationFile devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.

Nota

Se la chiamata a questa funzione si verifica in modalità utente, usare il nome "NtSetInformationFile" anziché "ZwSetInformationFile".

Per le chiamate dai driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Windows Native System Services possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx* e ZwXxx* di una routine, vedere Uso di nt e zw versioni di Native System Services.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000.
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)
Regole di conformità DDI	HwStorPortProhibitedDDIs, PowerIrpDDis