Funzione NtSetInformationFile (ntifs.h)

Articolo
02/07/2025

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 per l'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 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, fornito nel buffer a cui punta FileInformation, da impostare per il file. I driver intermedi e del dispositivo 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 aver 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 viene chiuso o annullare un'eliminazione richiesta in precedenza. La scelta se eliminare o annullare viene fornita in una struttura di FILE_DISPOSITION_INFORMATION. Il chiamante deve aver 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 di 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 FILE_WRITE_DATA impostato nel parametro DesiredAccess. Gli utenti non amministratori e remoti devono avere il privilegio SeManageVolumePrivilege.
FileShortNameInformation (40)	Modificare il nome di 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 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 I/O da associare all'handle di file. Per rimuovere la porta di completamento 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 deve essere eseguita l'eliminazione, vengono fornite in una struttura FILE_DISPOSITION_INFORMATION_EX. Il chiamante deve aver 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 aver 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 collegamenti rigidi; ad esempio NTFS fa mentre FAT non lo fa.
FileCaseSensitiveInformationForceAccessCheck (75)	Modificare le informazioni fornite in una struttura FILE_CASE_SENSITIVE_INFORMATION. Il chiamante deve aver 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 applicati 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.

Osservazioni

NtSetInformationFile modifica le informazioni su un file. Ignora qualsiasi membro di una struttura_INFORMATION FILE_XXX non supportata da un particolare dispositivo o file system.

Se imposti FileInformationClass su FileDispositionInformation, puoi successivamente passare FileHandle a NtClose ma non ad altre routine ZwXxxFile. Poiché FileDispositionInformation fa sì che il file venga contrassegnato per l'eliminazione, si tratta di un errore di programmazione per tentare qualsiasi operazione successiva sull'handle diverso da chiuderlo.

Se imposti FileInformationClass su FilePositionInformatione la chiamata precedente a NtCreateFile incluso il flag FILE_NO_INTERMEDIATE_BUFFERING nel parametro CreateOptions, vengono applicate alcune restrizioni sul membro CurrentByteOffset della struttura FILE_POSITION_INFORMATION. Per altre informazioni, vedere NtCreateFile.

Se imposti FileInformationClass su FileEndOfFileInformatione il membro EndOfFile di FILE_END_OF_FILE_INFORMATION specifica un offset oltre la fine del file corrente, NtSetInformationFile estende il file e riempie l'estensione con zeri.

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 viene eseguita in modalità utente, usare il nome "NtSetInformationFile" anziché "ZwSetInformationFile".

Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni 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 ulteriori informazioni sulla relazione tra le versioni NtXxx} e ZwXxx} di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines.

Fabbisogno

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