Funzione FltQueryDirectoryFileEx (fltkernel.h)

Articolo
08/07/2023

FltQueryDirectoryFileEx restituisce vari tipi di informazioni sui file nella directory specificata da un determinato oggetto file.

Sintassi

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

Parametri

Instance

Puntatore opaco all'istanza del driver minifilter che avvia l'I/O.

FileObject

Puntatore all'oggetto file che rappresenta la directory su cui viene eseguito la query.

FileInformation

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

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. Vedere il parametro FileInformationClass di NtQueryDirectoryFileEx per l'elenco dei valori possibili.

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)	Se questo flag è impostato, l'analisi inizierà alla prima voce della 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 )	Se questo flag è impostato, 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)	Se questo flag è impostato, 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.

FileName

Puntatore a una struttura UNICODE_STRING allocata dal chiamante con la stringa Unicode che contiene il nome di un file (o più file, se vengono utilizzati caratteri jolly) all'interno della directory specificata da FileObject. Questo parametro è facoltativo e può essere NULL. Se fileName è NULL, vengono inclusi tutti i file.

Se FileName non è NULL, nell'analisi della directory vengono inclusi solo i file i cui nomi corrispondono alla stringa FileName . Se il flag ResetScan di QueryFlags è impostato, il valore di FileName viene ignorato.

LengthReturned

Riceve il numero di byte effettivamente scritti nel buffer FileInformation specificato.

Valore restituito

FltQueryDirectoryFileEx restituisce STATUS_SUCCESS o un codice di errore appropriato. Il set di valori di stato degli errori che è possibile restituire è specifico del file system.

Commenti

FltQueryDirectoryFileEx restituisce informazioni sui file contenuti nella directory rappresentata da FileObject.

La prima chiamata a FltQueryDirectoryFileEx determina il set di voci da includere nell'analisi della directory per tutte le chiamate successive, in base ai valori di QueryFlags e FileName. Se è presente almeno una voce corrispondente, FltQueryDirectoryFileEx crea una struttura FILE_XXX_INFORMATION (vedere la tabella precedente) per ogni voce e archivia la struttura nel buffer.

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

Una voce, se il flag SL_RETURN_SINGLE_ENTRY è impostato in QueryFlags e FileName è NULL.
Numero di voci che corrispondono alla stringa FileName , se FileName non è NULL. Si noti che se la stringa non contiene caratteri jolly, può essere presente al massimo una voce corrispondente.
Numero di voci le cui informazioni si inserisce nel buffer a cui punta FileInformation.
Numero di voci contenute nella directory.

Nella prima chiamata a FltQueryDirectoryFileEx, se la struttura creata per la prima voce trovata è troppo grande per adattarsi al buffer di output, viene restituita solo la parte fissa della struttura. La parte fissa è costituita da tutti i campi della struttura ad eccezione della stringa FileName finale. Il sottosistema di I/O garantisce che il buffer sia sufficientemente grande da contenere la parte fissa della struttura FILE_XXX_INFORMATION appropriata (solo nella prima chiamata e non nelle chiamate successive). In questo caso, FltQueryDirectoryFileEx restituisce un valore di stato di STATUS_BUFFER_OVERFLOW. Anche nella prima chiamata a FltQueryDirectoryFileEx, se nella directory FileObject non è presente alcun file corrispondente al parametro FileName , FltQueryDirectoryFileEx restituisce STATUS_NO_SUCH_FILE.

In ogni chiamata FltQueryDirectoryFileEx restituisce tutte le strutture FILE_XXX_INFORMATION (una per ogni voce di directory) come possono essere contenute interamente nel buffer a cui punta FileInformation. Finché il buffer di output contiene almeno una struttura completa, il valore di stato restituito viene STATUS_SUCCESS. Non vengono segnalate informazioni sulle voci rimanenti. Pertanto, tranne nei casi elencati in precedenza in cui viene restituita una sola voce, FltQueryDirectoryFileEx deve essere chiamato almeno due volte per enumerare il contenuto di un'intera directory, ad esempio quando il parametro FileName contiene uno o più caratteri jolly o è NULL.

La chiamata finale a FltQueryDirectoryFileEx restituisce un buffer di output vuoto e segnala un valore di stato non di errore di STATUS_NO_MORE_FILES.

Nota: Quando FltQueryDirectoryFileEx viene chiamato più volte nella stessa directory, è possibile che il numero di voci per cui vengono restituite le informazioni sarà minore del previsto. Ciò è dovuto al fatto che il set di voci da includere nell'analisi della directory viene corretto alla prima chiamata a FltQueryDirectoryFileEx. Nelle chiamate successive FltQueryDirectoryFileEx riprende l'analisi della directory ovunque sia stata interrotta in questa stessa enumerazione. Tuttavia, tra le chiamate a FltQueryDirectoryFileEx, le voci effettive della directory possono cambiare in modo che non siano più sincronizzate con l'enumerazione originale.

FltQueryDirectoryFileEx restituisce zero in qualsiasi membro di un FILE_XXX_INFORMATION struttura non supportata dal file system.

I chiamanti di FltQueryDirectoryFileEx devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con le SCHEDE APN abilitate. Per altre informazioni, vedere Disabilitazione delle SCHEDE APN.