Funzione NtQueryInformationFile (ntifs.h)

Articolo
07/11/2023

La routine NtQueryInformationFile restituisce vari tipi di informazioni su un oggetto file. Vedere anche NtQueryInformationByName, che può essere usato in modo più efficiente per alcune classi di informazioni sui file.

Sintassi

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

Parametri

[in] FileHandle

Gestire in un oggetto file. L'handle viene creato da una chiamata riuscita a NtCreateFile o NtOpenFile oppure a una routine equivalente di creazione o apertura di file.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e le informazioni sull'operazione. Il membro Information riceve il numero di byte che questa routine scrive effettivamente nel buffer FileInformation .

[out] FileInformation

Puntatore a un buffer allocato dal chiamante in cui la routine scrive le informazioni richieste sull'oggetto file. Il parametro FileInformationClass specifica il tipo di informazioni richieste dal chiamante.

[in] Length

Dimensioni, in byte, del buffer a cui punta FileInformation.

[in] FileInformationClass

Specifica il tipo di informazioni da restituire sul file nel buffer a cui punta FileInformation . I driver di dispositivo e intermedio possono specificare uno dei valori di FILE_INFORMATION_CLASS seguenti (elencati dal valore di enumerazione più basso a quello più alto):

valore FILE_INFORMATION_CLASS	Tipo di informazioni restituite
FileBasicInformation (4)	Struttura FILE_BASIC_INFORMATION . Il chiamante deve avere aperto il file con il flag di FILE_READ_ATTRIBUTES specificato nel parametro DesiredAccess .
FileStandardInformation (5)	Struttura FILE_STANDARD_INFORMATION . Il chiamante può eseguire query su queste informazioni purché il file sia aperto, senza requisiti specifici per DesiredAccess.
FileInternalInformation (6)	Struttura FILE_INTERNAL_INFORMATION . Questa struttura specifica un ID file a 64 bit che identifica in modo univoco un file in NTFS. In altri file system questo ID file non è garantito univoco.
FileEaInformation (7)	Struttura FILE_EA_INFORMATION . Questa struttura specifica le dimensioni del blocco di attributi estesi associato al file.
FileAccessInformation (8)	Struttura FILE_ACCESS_INFORMATION . Questa struttura contiene una maschera di accesso. Per altre informazioni sulle maschere di accesso, vedere ACCESS_MASK.
FileNameInformation (9)	Struttura FILE_NAME_INFORMATION . La struttura può contenere il percorso completo del file o solo una parte di esso. Il chiamante può eseguire query su queste informazioni purché il file sia aperto, senza requisiti specifici per DesiredAccess. Per altre informazioni sulla sintassi del nome file, vedere la sezione Osservazioni più avanti in questo argomento.
FilePositionInformation (14)	Struttura FILE_POSITION_INFORMATION . Il chiamante deve aver aperto il file con il flag DesiredAccess FILE_READ_DATA o FILE_WRITE_DATA specificato nel parametro DesiredAccess e con il flag FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT specificato nel parametro CreateOptions .
FileModeInformation (16)	Struttura FILE_MODE_INFORMATION . Questa struttura contiene un set di flag che specificano la modalità in cui è possibile accedere al file. Questi flag sono un subset delle opzioni che possono essere specificate nel parametro CreateOptions della routine IoCreateFile .
FileAlignmentInformation (17)	Struttura FILE_ALIGNMENT_INFORMATION . Il chiamante può eseguire query su queste informazioni purché il file sia aperto, senza requisiti specifici per DesiredAccess. Queste informazioni sono utili se il file è stato aperto con il flag di FILE_NO_INTERMEDIATE_BUFFERING specificato nel parametro CreateOptions .
FileAllInformation (18)	Struttura FILE_ALL_INFORMATION . Combinando diverse strutture di informazioni sui file in una singola struttura, FILE_ALL_INFORMATION riduce il numero di query necessarie per ottenere informazioni su un file.
FileAlternateNameInformation (21)	Struttura FILE_ALL_INFORMATION in cui restituire le informazioni sul nome alternativo per un file (nome di formato 8.3).
FileStreamInformation (22)	Buffer di strutture FILE_STREAM_INFORMATION in cui enumerare i flussi di dati di un file o di una directory.
FileCompressionInformation (28)	Struttura FILE_COMPRESSION_INFORMATION in cui restituire le informazioni di compressione per un file.
FileNetworkOpenInformation (34)	Struttura FILE_NETWORK_OPEN_INFORMATION . Il chiamante deve avere aperto il file con il flag di FILE_READ_ATTRIBUTES specificato nel parametro DesiredAccess .
FileAttributeTagInformation (35)	Struttura FILE_ATTRIBUTE_TAG_INFORMATION . Il chiamante deve avere aperto il file con il flag di FILE_READ_ATTRIBUTES specificato nel parametro DesiredAccess .
FileIoPriorityHintInformation (43)	Struttura FILE_IO_PRIORITY_HINT_INFORMATION . Il chiamante deve avere aperto il file con il flag FILE_READ_DATA specificato nel parametro DesiredAccess .
FileSfioReserveInformation (44)	Struttura FILE_SFIO_RESERVE_INFORMATION .
FileHardLinkInformation (46)	Struttura FILE_LINKS_INFORMATION .
FileNormalizedNameInformation (48)	Struttura FILE_NAME_INFORMATION in cui restituire il nome normalizzato di un file.
FileIsRemoteDeviceInformation (51)	Struttura FILE_IS_REMOTE_DEVICE_INFORMATION . Il chiamante può eseguire query su queste informazioni purché il file sia aperto, senza requisiti specifici per DesiredAccess.
FileStandardLinkInformation (54)	Struttura FILE_STANDARD_LINK_INFORMATION .
FileIdInformation (59)	Struttura FILE_ID_INFORMATION .
FileDesiredStorageClassInformation (67)	Struttura FILE_DESIRED_STORAGE_CLASS_INFORMATION .
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	Struttura FILE_CASE_SENSITIVE_INFORMATION . Il chiamante deve avere aperto il file con il flag di FILE_READ_ATTRIBUTES specificato nel parametro DesiredAccess . Questo valore è disponibile a partire da Windows 10 versione 1803.
FileStorageReserveIdInformation (74)	Struttura FILE_STORAGE_RESERVE_ID_INFORMATION .
FileCaseSensitiveInformationForceAccessCheck (75)	Struttura FILE_CASE_SENSITIVE_INFORMATION . Il chiamante deve avere aperto il file con il flag di FILE_READ_ATTRIBUTES specificato 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

NtQueryInformationFile restituisce STATUS_SUCCESS o un codice di errore NTSTATUS appropriato.

Commenti

NtQueryInformationFile restituisce informazioni sull'oggetto file specificato. Si noti che restituisce zero in qualsiasi membro di una struttura FILE_XXX_INFORMATION non supportata da un determinato dispositivo o file system.

Quando FileInformationClass = FileNameInformation, il nome del file viene restituito nella struttura FILE_NAME_INFORMATION . La sintassi precisa del nome del file dipende da un numero di fattori:

Se si apre il file inviando un percorso completo a NtCreateFile, NtQueryInformationFile restituisce il percorso completo.
Se l'handle ObjectAttributes-RootDirectory> è stato aperto per nome in una chiamata a NtCreateFile e successivamente il file è stato aperto da NtCreateFile rispetto a questo handle di directory radice, NtQueryInformationFile restituisce il percorso completo.
Se l'handle ObjectAttributes-RootDirectory> è stato aperto da ID file (usando il flag FILE_OPEN_BY_FILE_ID) in una chiamata a NtCreateFile e successivamente il file è stato aperto da NtCreateFile rispetto a questo handle di directory radice, NtQueryInformationFile restituisce il percorso relativo.
Tuttavia, se l'utente ha SeChangeNotifyPrivilege (descritto nella documentazione di Microsoft Windows SDK), NtQueryInformationFile restituisce il percorso completo in tutti i casi.
Se viene restituito solo il percorso relativo, la stringa nome file non inizierà con una barra rovesciata.
Se viene restituito il percorso completo e il nome del file, la stringa inizierà con una singola barra rovesciata, indipendentemente dalla posizione. Pertanto il file C:\dir1\dir2\filename.ext verrà visualizzato come \dir1\dir2\filename.ext, mentre il file \server\share\dir1\dir2\filename.ext verrà visualizzato come \server\share\dir1\dir2\filename.ext.

Se NtQueryInformationFile ha esito negativo a causa di un overflow del buffer, i driver che implementano FileNameInformation devono restituire il numero di caratteri WCHAR del nome file che si adattano al buffer e specificare la lunghezza completa necessaria nel parametro FileNameLength della struttura FILE_NAME_INFORMATION . È necessario riemettere la query usando la lunghezza del nome file in modo che sia possibile recuperare il nome completo del file. I driver che non seguono questo modello potrebbero richiedere un aumento graduale della lunghezza fino a quando non recuperano il nome completo del file. Per altre informazioni sull'uso dei file, vedere Uso di file in un driver.

I chiamanti di NtQueryInformationFile 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, è necessario usare il nome "NtQueryInformationFile" anziché "ZwQueryInformationFile".

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 delle routine di Servizi di sistema nativo.

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