IOCTL_REDIR_QUERY_PATH IOCTL (ntifs.h)

Articolo
10/14/2023

Il codice di controllo IOCTL_REDIR_QUERY_PATH viene inviato da più provider UNC (MUP) ai reindirizzamenti di rete per determinare quale provider può gestire un percorso UNC specifico in un'operazione basata sul nome, in genere una richiesta di IRP_MJ_CREATE. Questa richiesta viene definita "risoluzione del prefisso".

MUP è un componente in modalità kernel responsabile del canale di tutti gli accessi al file system remoto che usano un nome UNC a un redirector di rete (provider UNC) in grado di gestire le richieste del file system remoto. MUP è coinvolto quando un percorso UNC viene usato come illustrato nell'esempio seguente che può essere eseguito da una riga di comando:

notepad \\server\public\readme.txt

MUP non è coinvolto durante un'operazione che crea una lettera di unità mappata ,ad esempio il comando "NET USE". Questa operazione viene gestita da più router provider (MPR) e da una DLL del provider WNet in modalità utente per il redirector di rete. Tuttavia, una DLL del provider di rete WNet in modalità utente potrebbe comunicare direttamente con un driver del redirector di rete in modalità kernel durante questa operazione.

In Windows Server 2003, Windows XP e Windows 2000, le operazioni remote sui file eseguite su un'unità mappata che non rappresenta un'unità DFS (Distributed File System) non passano attraverso MUP. Queste operazioni passano direttamente al provider di rete che ha gestito il mapping delle lettere di unità.

Per i reindirizzamenti di rete conformi al modello di reindirizzamento di Windows Vista, MUP è coinvolto anche quando viene usata un'unità di rete mappata. Le operazioni sui file eseguite nell'unità mappata passano attraverso MUP al redirector di rete. Si noti che in questo caso MUP passa semplicemente l'operazione al redirector di rete coinvolto.

Il codice di controllo IOCTL_REDIR_QUERY_PATH viene inviato ai reindirizzamenti di rete registrati con MUP come provider UNC (Universal Naming Convention) chiamando FsRtlRegisterUncProvider. È possibile registrare più provider UNC con MUP.

L'operazione di risoluzione del prefisso serve due scopi:

L'operazione basata sul nome che ha generato la risoluzione del prefisso viene instradata al provider che richiede il prefisso. In caso di esito positivo, MUP garantisce che le operazioni successive basate su handle (IRP_MJ_READ e IRP_MJ_WRITE, ad esempio) vadano allo stesso provider ignorando completamente MUP.
Il provider e il prefisso richiesti vengono immessi in una cache dei prefissi gestita da MUP. Per le operazioni successive basate sui nomi, MUP usa questa cache dei prefissi per determinare se un provider ha già richiesto un prefisso prima che MUP tenti di eseguire una risoluzione del prefisso. Ogni voce in questa cache dei prefissi è soggetta a un timeout (definito TTL) dopo l'aggiunta alla cache. Una voce viene generata dopo la scadenza di questo timeout, a quel punto MUP eseguirà nuovamente la risoluzione del prefisso per questo prefisso in un'operazione basata sul nome successiva.

Codice principale

IOCTL_REDIR_QUERY_PATH

Buffer di input

IrpSp->Parameters.DeviceIoControl.Type3InputBuffer è impostato su una struttura di dati QUERY_PATH_REQUEST che contiene la richiesta.

Lunghezza del buffer di input

Lunghezza del buffer di input, in byte, che deve essere almeno sizeof(QUERY_PATH_REQUEST).

Buffer di output

IRP->UserBuffer è impostato su una struttura di dati QUERY_PATH_RESPONSE che contiene la risposta.

Lunghezza del buffer di output

Lunghezza del buffer di output, in byte, che deve essere almeno sizeof(QUERY_PATH_RESPONSE).

Buffer di input/output

n/d

Lunghezza del buffer di input/output

n/d

Blocco dello stato

Il membro Status è impostato su STATUS_SUCCESS in caso di esito positivo se il nome del prefisso \\server\share viene riconosciuto o a un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice stato	Significato
STATUS_BAD_NETWORK_NAME	Impossibile trovare il nome della condivisione specificato nel server remoto. Il nome del computer (\\server, ad esempio) è valido, ma non è possibile trovare il nome di condivisione specificato nel server remoto.
STATUS_BAD_NETWORK_PATH	Impossibile trovare il percorso di rete. Il nome del computer (\\server, ad esempio) non è valido o il redirector di rete non è in grado di risolvere il nome del computer (usando i meccanismi di risoluzione dei nomi disponibili).
STATUS_INSUFFICIENT_RESOURCES	Sono disponibili risorse insufficienti per allocare memoria per i buffer.
STATUS_INVALID_DEVICE_REQUEST	Una richiesta di IOCTL_REDIR_QUERY_PATH_EX deve provenire solo da MUP e il membro RequestorMode della struttura IRP deve essere sempre KernelMode. Questo codice di errore viene restituito se la modalità richiedente del thread chiamante non era KernelMode.
STATUS_INVALID_PARAMETER	Il membro PathNameLength nella struttura QUERY_PATH_REQUEST supera la lunghezza massima consentita, UNICODE_STRING_MAX_BYTES, per una stringa Unicode.
STATUS_LOGON_FAILURE o STATUS_ACCESS_DENIED	Se l'operazione di risoluzione del prefisso non è riuscita a causa di credenziali non valide o non corrette, il provider deve restituire il codice di errore esatto restituito dal server remoto; questi codici di errore non devono essere convertiti in STATUS_BAD_NETWORK_NAME o STATUS_BAD_NETWORK_PATH. I codici di errore come STATUS_LOGON_FAILURE e STATUS_ACCESS_DENIED fungono da meccanismo di feedback per l'utente e indicano il requisito di usare le credenziali appropriate. Questi codici di errore vengono usati anche in determinati casi per richiedere automaticamente all'utente le credenziali. Senza questi codici di errore, l'utente potrebbe presupporre che il computer non sia accessibile.

Se il redirector di rete non è in grado di risolvere un prefisso, deve restituire un codice NTSTATUS che corrisponde strettamente alla semantica prevista dall'elenco precedente di codici NTSTATUS consigliati. Un redirector di rete non deve restituire l'errore rilevato effettivo (STATUS_CONNECTION_REFUSED, ad esempio) direttamente a MUP se il codice NTSTATUS non è incluso nell'elenco precedente.

Commenti

I redirector di rete devono rispettare solo i mittenti in modalità kernel di questo IOCTL, verificando che Irp-RequestorMode> sia KernelMode.

Si noti che IOCTL_REDIR_QUERY_PATH è un METHOD_NEITHER IOCTL. Ciò significa che i buffer di input e output potrebbero non trovarsi nello stesso indirizzo. Un errore comune da parte dei provider UNC consiste nel presupporre che il buffer di input e il buffer di output siano uguali e usare il puntatore al buffer di input per fornire la risposta.

Quando un provider UNC riceve una richiesta di IOCTL_REDIR_QUERY_PATH, deve determinare se può gestire il percorso UNC specificato nel membro FilePathName della struttura QUERY_PATH_REQUEST . In tal caso, deve aggiornare il membro LengthAccepted della struttura QUERY_PATH_RESPONSE con la lunghezza, in byte, del prefisso richiesto e completare l'IRP con STATUS_SUCCESS. Se il provider non è in grado di gestire il percorso UNC specificato, deve non riuscire la richiesta di IOCTL_REDIR_QUERY_PATH con un codice di errore NTSTATUS appropriato e non deve aggiornare il membro LengthAccepted della struttura QUERY_PATH_RESPONSE . I provider non devono modificare alcun membro o la stringa FilePathName in alcuna condizione.

La lunghezza del prefisso richiesto dal provider dipende da un singolo provider UNC. La maggior parte dei provider richiede in genere la parte \\servername\sharename di un percorso nel formato \\nomeserver\ percorsosharename\. Ad esempio, se un provider ha richiesto \\server\pubblico dato un percorso \\server\public\dir1\dir2, tutte le operazioni basate su nome per il prefisso \\server \ public (\\server \public\file1, ad esempio) verranno instradate a tale provider automaticamente senza alcuna risoluzione del prefisso perché il prefisso è già presente nella cache dei prefissi. Tuttavia, un percorso con il prefisso \\server\marketing\presentation passerà attraverso la risoluzione del prefisso.

Se un redirector di rete richiede un nome server (\\server, ad esempio), tutte le richieste di condivisioni in questo server verranno inviate a questo redirector di rete. Questo comportamento è accettabile solo se non è possibile accedere a un'altra condivisione nello stesso server da un redirector di rete diverso. Ad esempio, un redirector di rete che dichiara \\server di un percorso UNC impedirà l'accesso da altri reindirizzamenti di rete ad altre condivisioni in questo server (ad esempio l'accesso WebDAV alWeb \\server\).

Per altre informazioni, vedere le sezioni seguenti nella Guida alla progettazione: