Funzione NtQueryDirectoryFileEx (ntifs.h)

Articolo
02/29/2024

La routine NtQueryDirectoryFileEx restituisce vari tipi di informazioni sui file nella directory specificata da un handle di file specificato.

Sintassi

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

Parametri

[in] FileHandle

Handle restituito da NtCreateFile o NtOpenFile per l'oggetto file che rappresenta la directory per cui vengono richieste le informazioni. L'oggetto file deve essere stato aperto per l'I/O asincrono se il chiamante specifica un valore non NULL per Event o ApcRoutine.

[in, optional] Event

Handle facoltativo per un evento creato dal chiamante. Se questo parametro viene specificato, il chiamante verrà inserito in uno stato di attesa fino al completamento dell'operazione richiesta e l'evento specificato viene impostato sullo stato Segnalato. Questo parametro è facoltativo e può essere NULL. Deve essere NULL se il chiamante attenderà che FileHandle venga impostato sullo stato Segnalato.

[in, optional] ApcRoutine

Indirizzo di una routine APC fornita dal chiamante facoltativo da chiamare al termine dell'operazione richiesta. Questo parametro è facoltativo e può essere NULL. Se è presente un oggetto di completamento I/O associato all'oggetto file, questo parametro deve essere NULL.

[in, optional] ApcContext

Puntatore facoltativo a un'area di contesto determinata dal chiamante se il chiamante fornisce un APC o se un oggetto di completamento I/O è associato all'oggetto file. Al termine dell'operazione, questo contesto viene passato all'APC, se ne è stato specificato uno o viene incluso come parte del messaggio di completamento che gestione I/O invia all'oggetto di completamento I/O associato.

Questo parametro è facoltativo e può essere NULL. Deve essere NULL se ApcRoutine è NULL e non è presente alcun oggetto di completamento I/O associato all'oggetto file.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e le informazioni sull'operazione. Per le chiamate riuscite che restituiscono dati, il numero di byte scritti nel buffer FileInformation viene restituito nel membro Information della struttura.

[out] FileInformation

Puntatore a un buffer di output che riceve le informazioni desiderate sul file. La struttura delle informazioni restituite nel buffer è definita dal parametro FileInformationClass .

[in] Length

Dimensioni, in byte, del buffer a cui punta FileInformation. Il chiamante deve impostare questo parametro in base all'oggetto FileInformationClass specificato.

FileInformationClass

Tipo di informazioni da restituire sui file nella directory. Tipo di informazioni da restituire sui file nella directory. FileInformationClass può essere uno dei valori di FILE_INFORMATION_CLASS seguenti.

Valore	Significato
FileDirectoryInformation (1)	Restituisce una struttura FILE_DIRECTORY_INFORMATION per ogni file.
FileFullDirectoryInformation (2)	Restituisce una struttura FILE_FULL_DIR_INFORMATION per ogni file.
FileBothDirectoryInformation (3)	Restituisce una struttura FILE_BOTH_DIR_INFORMATION per ogni file.
FileNamesInformation (12)	Restituisce una struttura FILE_NAMES_INFORMATION per ogni file.
FileObjectIdInformation (29)	Restituisce una struttura FILE_OBJECTID_INFORMATION per ogni file con ID oggetto nel volume. Questa classe di informazioni è valida solo per la directory speciale "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" nei volumi NTFS.
FileQuotaInformation (32)	Restituisce una singola struttura FILE_QUOTA_INFORMATION per ogni utente nel volume con quote applicate. Questa classe di informazioni è valida solo per la directory speciale "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" nei volumi NTFS.
FileReparsePointInformation (33)	Restituisce una singola struttura FILE_REPARSE_POINT_INFORMATION per ogni file con un punto di correzione nel volume. Questa classe di informazioni è valida solo per la directory speciale "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" nei volumi NTFS e ReFS.
FileIdBothDirectoryInformation (37)	Restituisce una struttura FILE_ID_BOTH_DIR_INFORMATION per ogni file.
FileIdFullDirectoryInformation (38)	Restituisce una struttura FILE_ID_FULL_DIR_INFORMATION per ogni file.
FileIdGlobalTxDirectoryInformation (50)	Restituisce una struttura FILE_ID_GLOBAL_TX_DIR_INFORMATION per ogni file.
FileIdExtdDirectoryInformation (60)	Restituisce una struttura FILE_ID_EXTD_DIR_INFORMATION per ogni file.
FileIdExtdBothDirectoryInformation (63)	Restituisce una struttura FILE_ID_EXTD_BOTH_DIR_INFORMATION per ogni file.

[in] QueryFlags

Uno o più flag contenuti in SL_QUERY_DIRECTORY_MASK. I valori possibili sono specificati nella tabella seguente.

Valore	Significato
SL_RESTART_SCAN (0x00000001)	L'analisi inizierà alla prima voce nella directory. Se questo flag non è impostato, l'analisi riprenderà da dove è terminata l'ultima query.
SL_RETURN_SINGLE_ENTRY (0x00000002)	In genere, il buffer restituito viene compresso con tutte le voci di directory corrispondenti che rientrano. Se questo flag è impostato, il file system restituirà una sola voce di directory alla volta. In questo modo l'operazione risulta meno efficiente.
SL_INDEX_SPECIFIED (0x00000004)	L'analisi deve iniziare in corrispondenza di una posizione indicizzata specificata nella directory. Questo flag può essere impostato solo se si genera il proprio IRP_MJ_DIRECTORY_CONTROL IRP; l'indice viene specificato nell'IRP. La modalità di specifica della posizione varia dal file system al file system.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Tutti i filtri del file system che eseguono la virtualizzazione della directory o l'espansione JUST-in-time devono semplicemente passare la richiesta al file system e restituire le voci attualmente presenti su disco. Non tutti i file system supportano questo flag.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	I file system gestiscono le informazioni sul cursore della directory per FileObject. Quando più thread eseguono query usando lo stesso FileObject, l'accesso alla struttura per ogni FileObject viene a thread singolo per evitare il danneggiamento dello stato del cursore. Questo flag indica al file system di non aggiornare le informazioni sullo stato del cursore per FileObject, consentendo così a più thread di eseguire query in parallelo usando lo stesso handle. Si comporta come se SL_RESTART_SCAN sia specificato in ogni chiamata. Se alla chiamata successiva viene assegnato un criterio con caratteri jolly, l'operazione non rileverà dove è terminata l'ultima query. In questo modo è possibile supportare true query di directory asincrone. Se questo flag viene utilizzato all'interno di una transazione TxF, l'operazione non sarà riuscita. Non tutti i file system supportano questo flag.

[in, optional] FileName

Puntatore facoltativo a una stringa Unicode allocata dal chiamante contenente il nome di un file (o più file, se vengono usati caratteri jolly) all'interno della directory specificata da FileHandle. Questo parametro è facoltativo:

Se FileName non è NULL, nell'analisi della directory vengono inclusi solo i file i cui nomi corrispondono alla stringa FileName .
Se FileName è NULL:
- Se SL_RETURN_SINGLE_ENTRY non è impostato in QueryFlags, vengono inclusi tutti i file.
- Se SL_RETURN_SINGLE_ENTRY è impostato, viene incluso un solo file.

FileName viene usato come espressione di ricerca e viene acquisito nella prima chiamata a NtQueryDirectoryFileEx per un determinato handle. Le chiamate successive a NtQueryDirectoryFileEx useranno l'espressione di ricerca impostata nella prima chiamata. Il parametro FileName passato alle chiamate successive verrà ignorato.

Valore restituito

NtQueryDirectoryFileEx restituisce STATUS_SUCCESS o uno stato di errore appropriato. Il set di valori di stato degli errori che è possibile restituire è specifico del file system. NtQueryDirectoryFileEx restituisce anche il numero di byte effettivamente scritti nel buffer FileInformation specificato nel membro Information di IoStatusBlock. Alcuni possibili codici di errore e motivi potrebbero essere i seguenti:

Codice restituito	Significato
STATUS_BUFFER_OVERFLOW	Il buffer di output non è abbastanza grande per restituire il nome del file completo.
STATUS_BUFFER_TOO_SMALL	Il buffer di output non è abbastanza grande per almeno la struttura di base identificata da FileInformationClass.
STATUS_INVALID_INFO_CLASS	È stato specificato Un fileInformationClass non valido oppure la classe di informazioni è valida solo per una condizione speciale, ad esempio valida solo per una directory speciale.
STATUS_INVALID_PARAMETER	Uno dei parametri non è valido per il file system.

Commenti

NtQueryDirectoryFileEx restituisce informazioni sui file contenuti nella directory rappresentata da FileHandle.

Se specificato, FileName determina le voci incluse nell'analisi della directory per tutte le chiamate successive a NtQueryDirectoryFileEx per un determinato FileHandle.

Se è presente almeno una voce corrispondente, NtQueryDirectoryFileEx crea una struttura FILE_XXX_INFORMATION per ogni voce e le archivia nel buffer.

Supponendo che venga trovata almeno una voce di directory corrispondente, il numero di voci per cui vengono restituite informazioni è il più piccolo dei seguenti:

Una voce, se SL_RETURN_SINGLE_ENTRY è impostata in QueryFlags e FileName è NULL.
Numero di voci corrispondenti alla stringa FileName , se FileName non è NULL. Se la stringa non contiene caratteri jolly, è possibile che sia presente una voce corrispondente.
Numero di voci le cui informazioni si adattano al buffer specificato.
Numero di voci contenute nella directory.

Nella prima chiamata a NtQueryDirectoryFileEx, se la struttura creata per la prima voce trovata è troppo grande per adattarsi al buffer di output, questa routine esegue le operazioni seguenti:

Scrive la parte fissa della struttura nel buffer di output di FileInformation. La parte fissa è costituita da tutti i campi, ad eccezione della stringa FileName finale. Nella prima chiamata, ma non nelle chiamate successive, il sistema di I/O garantisce che il buffer sia abbastanza grande per contenere la parte fissa della struttura FILE_XXX appropriata_INFORMATION.
Scrive nel buffer di output la maggior parte della stringa FileName adatta.
Restituisce un valore di stato appropriato, ad esempio STATUS_BUFFER_OVERFLOW.

In ogni chiamata NtQueryDirectoryFileEx restituisce il numero massimo di strutture FILE_XXX_INFORMATION (una per voce di directory) che può essere contenuta interamente nel buffer a cui fa riferimento FileInformation:

Nella prima chiamata NtQueryDirectoryFileEx restituisce STATUS_SUCCESS solo se il buffer di output contiene almeno una struttura completa.
Nelle chiamate successive, se il buffer di output non contiene strutture, NtQueryDirectoryFileEx restituisce STATUS_SUCCESS ma imposta IoStatusBlock-Information> = 0 per notificare al chiamante di questa condizione. In questo caso, il chiamante deve allocare un buffer più grande e chiamare di nuovo NtQueryDirectoryFileEx . Non vengono segnalate informazioni sulle voci rimanenti. Pertanto, tranne nei casi elencati sopra in cui viene restituita una sola voce, NtQueryDirectoryFileEx deve essere chiamato almeno due volte per enumerare il contenuto di un'intera directory.

Quando si chiama NtQueryDirectoryFileEx, è possibile che vengano visualizzate modifiche apportate alla directory che si verificano in parallelo con chiamate NtQueryDirectoryFileEx . Questo comportamento dipende dall'implementazione del file system sottostante.

La chiamata finale a NtQueryDirectoryFileEx restituisce un buffer di output vuoto e segnala un valore di stato appropriato, ad esempio STATUS_NO_MORE_FILES.

Se NtQueryDirectoryFileEx viene chiamato più volte nella stessa directory e alcune altre operazioni modificano il contenuto di tale directory, eventuali modifiche potrebbero o meno essere visualizzate, a seconda della tempistica delle operazioni.

NtQueryDirectoryFileEx restituisce zero in qualsiasi membro di una struttura FILE_XXX_INFORMATION non supportata dal file system.

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

Per informazioni sulle altre routine di query sulle informazioni sui file, vedere Oggetti file.

Nota

Se la chiamata alla funzione NtQueryDirectoryFileEx si verifica in modalità kernel, è necessario usare il nome "ZwQueryDirectoryFileEx" anziché "NtQueryDirectoryFileEx".

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 10, versione 1709
Intestazione	ntifs.h
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)