Funzione FltQueryDirectoryFile (fltkernel.h)

Articolo
12/21/2024

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 al FileInformationClass specificato.

[in] FileInformationClass

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

[in] ReturnSingleEntry

Impostare su true se deve essere restituita una sola 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 file vengono inclusi nell'analisi della directory. Se fileName è null, vengono inclusi tutti i file. 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.

Osservazioni

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, FileNamee RestartScan. Se è presente almeno una voce corrispondente, FltQueryDirectoryFile crea una struttura FILE_XXX_INFORMATION (vedere la tabella precedente) per ogni voce a sua volta 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 ReturnSingleEntry è TRUE e FileName è NULL.
Numero di voci che corrispondono alla stringa NomeFile , se NomeFile 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 rientrano nel buffer specificato.
Numero di voci contenute nella directory.

Nella prima chiamata a FltQueryDirectoryFile, se la struttura creata per la prima voce trovata troppo grande per rientrare nel buffer di output viene restituita solo la parte fissa della struttura. La parte fissa è costituita da tutti i campi della struttura, ad eccezione del fileName finale stringa. Nella prima chiamata, ma non su quelli successivi, il sistema di I/O garantisce che il buffer sia sufficientemente grande da contenere la parte fissa della struttura di FILE_XXX_INFORMATION appropriata. In questo caso, FltQueryDirectoryFile restituisce un valore di stato appropriato, ad esempio STATUS_BUFFER_OVERFLOW. Anche nella prima chiamata a FltQueryDirectoryFile, se non è presente alcun file nella directory FileObject che corrisponde al parametro NomeFile , 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 ogni voce di directory) contenute interamente nel buffer a cui punta FileInformation. Se 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, FltQueryDirectoryFile deve essere chiamato almeno due volte per enumerare il contenuto di un'intera directory, ad esempio quando il parametro NomeFile 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 le informazioni sarà inferiore al previsto. Ciò è dovuto al fatto che il set di voci da includere nell'analisi della directory viene corretto alla 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 di directory effettive 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 su 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 La disabilitazione delle API.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista
piattaforma di destinazione	Universale
intestazione	fltkernel.h (include Fltkernel.h)
libreria	FltMgr.lib
dll	Fltmgr.sys
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)