Funzione ZwQueryInformationFile (wdm.h)

Articolo
08/08/2023

La routine ZwQueryInformationFile restituisce vari tipi di informazioni su un oggetto file.

Sintassi

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [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 ZwCreateFile o ZwOpenFile.

[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.

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.
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 .
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.
FileKnownFolderInformation (76)	Struttura FILE_KNOWN_FOLDER_INFORMATION . Disponibile a partire da Windows Server 2022.

Valore restituito

ZwQueryInformationFile restituisce STATUS_SUCCESS o un codice di errore NTSTATUS appropriato.

Commenti

ZwQueryInformationFile 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 ZwCreateFile, ZwQueryInformationFile restituisce il percorso completo.
Se l'handle ObjectAttributes-RootDirectory> è stato aperto per nome in una chiamata a ZwCreateFile e successivamente il file è stato aperto da ZwCreateFile rispetto a questo handle di directory radice, ZwQueryInformationFile 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 ZwCreateFile e successivamente il file è stato aperto da ZwCreateFile rispetto a questo handle di directory radice, ZwQueryInformationFile restituisce il percorso relativo.
Tuttavia, se l'utente ha SeChangeNotifyPrivilege, ZwQueryInformationFile 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 ZwQueryInformationFile 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 ZwQueryInformationFile devono essere eseguiti in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.

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 di Native System Services.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.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(storport), PowerIrpDDis(wdm)