Funzione NtQueryDirectoryFile (ntifs.h)
La routine NtQueryDirectoryFile restituisce vari tipi di informazioni sui file nella directory specificata da un handle di file specificato.
Sintassi
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
[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,
[in] FILE_INFORMATION_CLASS FileInformationClass,
[in] BOOLEAN ReturnSingleEntry,
[in, optional] PUNICODE_STRING FileName,
[in] BOOLEAN RestartScan
);
Parametri
[in] FileHandle
Handle restituito da NtCreateFile o NtOpenFile per l'oggetto file che rappresenta la directory per cui vengono richieste informazioni. L'oggetto file deve essere stato aperto per l'I/O asincrona 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 fornito, 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 il FileHandle sia 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 all'oggetto file è associato un oggetto di completamento I/O, 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 esiste 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 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 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. 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, NtQueryDirectoryFile restituisce solo la prima voce trovata.
[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 e può essere NULL.
Se fileName non è NULL, nell'analisi della directory vengono inclusi solo i file i cui nomi corrispondono alla stringa NomeFile. Se FileName è NULL, vengono inclusi tutti i file.
Il FileName viene usato come espressione di ricerca e viene acquisito nella prima chiamata a NtQueryDirectoryFile per un handle specificato. Le chiamate successive a NtQueryDirectoryFile useranno l'espressione di ricerca impostata nella prima chiamata. Il parametro FileName passato alle chiamate successive verrà 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.
Quando viene chiamata la routine NtQueryDirectoryFile per un handle specifico, il parametro RestartScan viene considerato come se fosse impostato su TRUE, indipendentemente dal relativo valore. Nelle chiamate successive NtQueryDirectoryFile, viene rispettato il valore del parametro RestartScan.
Valore restituito
La routine NtQueryDirectoryFilerestituisce STATUS_SUCCESS o uno stato di errore appropriato. Il set di valori di stato degli errori che è possibile restituire è specifico del file system. NtQueryDirectoryFilerestituisce anche il numero di byte effettivamente scritti nel buffer FileInformation specificato nel Information membro di IoStatusblock. Vedere NtQueryDirectoryFileEx per un elenco di alcuni possibili codici di errore.
Osservazioni
La routine NtQueryDirectoryFile restituisce informazioni sui file contenuti nella directory rappresentata da FileHandle.
Se specificato, il valore del parametro FileName determina le voci incluse nell'analisi della directory per tutte le chiamate successive a NtQueryDirectoryFile per un determinato FileHandle.
Se è presente almeno una voce corrispondente, NtQueryDirectoryFile 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 le informazioni è il *più piccolo dei seguenti elementi:
- 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 NtQueryDirectoryFile, se la struttura creata per la prima voce trovata è troppo grande per adattarsi al buffer di output, la routine scrive la parte fissa della struttura nel buffer di output. La routine scrive quindi nel buffer di output la maggior parte della stringa FileName adatta. La parte fissa della struttura è costituita da tutti i campi ad eccezione del fileName finale stringa. Nella prima chiamata, ma non nelle chiamate successive, il sistema di I/O garantisce che il buffer sia sufficientemente grande da contenere la parte fissa della struttura FILE_XXX_INFORMATION appropriata). In questo caso, NtQueryDirectoryFile restituisce un valore di stato appropriato, ad esempio STATUS_BUFFER_OVERFLOW.
In ogni chiamata, NtQueryDirectoryFile restituisce il numero di strutture_INFORMATION XXX FILE_XXX (una per voce di directory) che può essere contenuta interamente nel buffer a cui punta FileInformation. Nella prima chiamata NtQueryDirectoryFile 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, NtQueryDirectoryFile 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 NtQueryDirectoryFile. Non vengono segnalate informazioni sulle voci rimanenti. Pertanto, tranne nei casi elencati in precedenza in cui viene restituita una sola voce, ntQueryDirectoryFile deve essere chiamato almeno due volte per enumerare il contenuto di un'intera directory.
Quando si chiama NtQueryDirectoryFile, è possibile che vengano visualizzate modifiche apportate alla directory che si verificano in parallelo con NtQueryDirectoryFile chiamate. Questo comportamento dipende dall'implementazione del file system sottostante.
La chiamata finale a NtQueryDirectoryFile restituisce un buffer di output vuoto e segnala un valore di stato appropriato, ad esempio STATUS_NO_MORE_FILES.
Se NtQueryDirectoryFile viene chiamato più volte nella stessa directory e altre operazioni modificano il contenuto della directory, eventuali modifiche potrebbero essere visualizzate o meno, a seconda della tempistica delle operazioni.
NtQueryDirectoryFilerestituisce zero in qualsiasi membro di una struttura_INFORMATION XXX FILE_XXX non supportata dal file system.
I chiamanti di NtQueryDirectoryFile devono essere eseguiti in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.
Per informazioni su altre routine di query sulle informazioni sui file, vedere Oggetti file.
Nota
Se la chiamata alla funzione ntQueryDirectoryFile viene eseguita in modalità utente, è necessario usare il nome "NtQueryDirectoryFile" anziché "ZwQueryDirectoryFile".
Per le chiamate da driver in modalità kernel, il NtXXX e ZwXXX versioni di una routine di Servizi di sistema nativi di Windows può comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra NtXXX e ZwXXX versioni di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP |
| piattaforma di destinazione | Universale |
| intestazione | ntifs.h (include Ntifs.h) |
| libreria | NtosKrnl.lib |
| dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (vedere la sezione Osservazioni) |
| regole di conformità DDI | HwStorPortProhibitedDDIs, PowerIrpDDis |