Funzione FltQueryDirectoryFile (fltkernel.h)

Articolo
08/07/2023

La routine FltQueryDirectoryFile restituisce vari tipi di informazioni sui file nella directory specificata da un determinato oggetto file. Usare FltQueryDirectoryFileEx per un controllo query maggiore.

Sintassi

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

Parametri

[in] Instance

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

[in] FileObject

Puntatore all'oggetto file che rappresenta la directory da analizzare.

[out] FileInformation

Puntatore a un buffer 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.

[in] FileInformationClass

Tipo di informazioni da restituire sui file nella directory. Per l'elenco dei valori possibili, vedere il parametro FileInformationClass di NtQueryDirectoryFileEx .

[in] ReturnSingleEntry

Impostare su TRUE se deve essere restituita solo una singola voce, FALSE in caso contrario. Se questo parametro è TRUE, FltQueryDirectoryFile restituisce solo la prima voce trovata.

[in, optional] FileName

Puntatore a una stringa Unicode allocata dal chiamante che contiene il nome di un file (o più file, se vengono usati caratteri jolly) all'interno della directory specificata da FileObject. Questo parametro è facoltativo e può essere NULL.

Se FileName non è NULL, solo i file i cui nomi corrispondono alla stringa FileName vengono inclusi nell'analisi della directory. Se FileName è NULL, tutti i file sono inclusi. Se RestartScan è FALSE, il valore di FileName viene ignorato.

[in] RestartScan

Impostare su TRUE se l'analisi deve iniziare alla prima voce della directory. Impostare su FALSE se si riprende l'analisi da una chiamata precedente. Il chiamante deve impostare questo parametro su TRUE quando si chiama FltQueryDirectoryFile per la prima volta.

[out, optional] LengthReturned

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

Valore restituito

FltQueryDirectoryFile restituisce STATUS_SUCCESS o uno stato di errore appropriato. Si noti che il set di valori di stato degli errori che possono essere restituiti è specifico del file system.

Commenti

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

La prima chiamata a FltQueryDirectoryFile determina il set di voci da includere nell'analisi della directory per tutte le chiamate successive, in base ai valori di ReturnSingleEntry, FileName e RestartScan. Se è presente almeno una voce corrispondente, FltQueryDirectoryFile 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 informazioni è il più piccolo dei seguenti:

Una voce, se ReturnSingleEntry è TRUE e FileName è NULL.
Numero di voci corrispondenti alla stringa FileName , se FileName non è NULL. Si noti che 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 FltQueryDirectoryFile, se la struttura creata per la prima voce è 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. Nella prima chiamata, ma non in quelli successivi, il sistema di I/O garantisce che il buffer sia abbastanza grande per contenere la parte fissa della struttura FILE_XXX appropriata_INFORMATION. In questo caso, FltQueryDirectoryFile restituisce un valore di stato appropriato, ad esempio STATUS_BUFFER_OVERFLOW. Anche nella prima chiamata a FltQueryDirectoryFile, se nella directory FileObject non è presente alcun file corrispondente al parametro FileName, FltQueryDirectoryFile restituisce un valore di stato appropriato, ad esempio STATUS_NO_SUCH_FILE.

In ogni chiamata FltQueryDirectoryFile restituisce il numero di strutture FILE_XXX_INFORMATION (una per voce di directory) come può essere contenuta interamente nel buffer a cui punta FileInformation. Purché il buffer di output contenga almeno una struttura completa, il valore di stato restituito è STATUS_SUCCESS. Non vengono segnalate informazioni sulle voci rimanenti. Pertanto, ad eccezione dei casi elencati sopra in cui viene restituita una sola voce, FltQueryDirectoryFile 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 FltQueryDirectoryFile restituisce un buffer di output vuoto e segnala un valore di stato appropriato, ad esempio STATUS_NO_MORE_FILES.

Nota

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

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

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

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (includere Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)