Funzione NtQueryInformationFile (ntifs.h)

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

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

Vedi anche

FILE_ACCESS_INFORMATION

FILE_ALIGNMENT_INFORMATION

FILE_ALL_INFORMATION

FILE_ATTRIBUTE_TAG_INFORMATION

FILE_BASIC_INFORMATION

FILE_EA_INFORMATION

FILE_INTERNAL_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_IS_REMOTE_DEVICE_INFORMATION

FILE_MODE_INFORMATION

FILE_NAME_INFORMATION

FILE_NETWORK_OPEN_INFORMATION

FILE_POSITION_INFORMATION

FILE_STANDARD_INFORMATION

Uso di nt e zw versioni delle routine di Servizi di sistema nativo

NtCreateFile

NtQueryInformationByName

NtSetInformationFile