IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

Artikel
10/10/2023

Ab Windows Vista sendet der mehrfache UNC-Anbieter (MUP) einen IOCTL_REDIR_QUERY_PATH_EX Steuercode an Netzwerkumleitungen, um zu bestimmen, welcher Anbieter einen bestimmten UNC-Pfad in einem namenbasierten Vorgang verarbeiten kann, in der Regel eine IRP_MJ_CREATE-Anforderung. Diese Anforderung wird als "Präfixauflösung" bezeichnet.

MUP ist eine Kernelmoduskomponente, die dafür verantwortlich ist, alle Remotedateisystemzugriffe mithilfe eines UNC-Namens an einen Netzwerkumleitungsanbieter (den UNC-Anbieter) zu kanalieren, der die Remotedateisystemanforderungen verarbeiten kann. MUP ist beteiligt, wenn ein UNC-Pfad verwendet wird, wie im folgenden Beispiel veranschaulicht, das über eine Befehlszeile ausgeführt werden könnte:

notepad \\server\public\readme.txt

MUP ist nicht bei einem Vorgang beteiligt, der einen zugeordneten Laufwerkbuchstaben erstellt (z. B. der Befehl "NET USE"). Dieser Vorgang wird vom Mehrfachanbieterrouter (Multiple Provider Router, MPR) und einer WNet-Anbieter-DLL für den Benutzermodus für den Netzwerkumleitungsanbieter verarbeitet. Eine WNet-Anbieter-DLL im Benutzermodus kann während dieses Vorgangs jedoch direkt mit einem Netzwerkumleitungstreiber im Kernelmodus kommunizieren.

Bei Netzwerkumleitungen, die dem Windows Vista-Umleitungsmodell entsprechen, ist MUP auch dann beteiligt, wenn ein zugeordnetes Netzlaufwerk verwendet wird. Dateivorgänge, die auf dem zugeordneten Laufwerk ausgeführt werden, gehen über MUP an den Netzwerkumleitungsor. Beachten Sie, dass MUP in diesem Fall den Vorgang einfach an den beteiligten Netzwerkumleitungsor übergibt.

Der IOCTL_REDIR_QUERY_PATH_EX-Steuerungscode wird durch Aufrufen von FsRtlRegisterUncProviderEx an Netzwerkumleitungen gesendet, die sich bei MUP als UNC-Anbieter (Universal Naming Convention) registriert haben. Es können mehrere UNC-Anbieter bei MUP registriert sein.

Der Präfixauflösungsvorgang dient zwei Zwecken:

Der namenbasierte Vorgang, der zur Präfixauflösung geführt hat, wird an den Anbieter weitergeleitet, der das Präfix angibt. Bei erfolgreicher Ausführung stellt MUP sicher, dass nachfolgende handlebasierte Vorgänge (z. B. IRP_MJ_READ und IRP_MJ_WRITE) MUP an denselben Anbieter durchlaufen. Beachten Sie, dass sich dieses Verhalten bei Netzwerkumleitungen unterscheidet, die nicht mit dem Windows Vista-Umleitungsmodell übereinstimmen, das IOCTL_REDIR_QUERY_PATH zur Präfixauflösung gesendet wird. Für Netzwerkumleitungen, die nicht dem Windows Vista-Umleitungsmodell entsprechen, wird MUP für nachfolgende handle-basierte Vorgänge vollständig umgangen.
Der Anbieter und das beanspruchte Präfix werden in einen Präfixcache eingegeben, der von MUP verwaltet wird. Für nachfolgende namensbasierte Vorgänge verwendet MUP diesen Präfixcache, um zu bestimmen, ob ein Anbieter bereits ein Präfix beansprucht hat, bevor MUP versucht, eine Präfixauflösung auszuführen. Jeder Eintrag in diesem Präfixcache unterliegt einem Timeout (als TTL bezeichnet), sobald er dem Cache hinzugefügt wird. Nach Ablauf dieses Timeouts wird ein Eintrag weggeworfen. An diesem Punkt führt MUP die Präfixauflösung für dieses Präfix bei einem nachfolgenden namensbasierten Vorgang erneut aus.

Hauptcode

IOCTL_REDIR_QUERY_PATH_EX

Eingabepuffer

IrpSp->Parameters.DeviceIoControl.Type3InputBuffer ist auf eine QUERY_PATH_REQUEST_EX Datenstruktur festgelegt, die die Anforderung enthält.

Länge des Eingabepuffers

Größe der QUERY_PATH_REQUEST_EX Struktur, auf die der Eingabepuffer verweist, in Byte.

Ausgabepuffer

IRP->UserBuffer ist auf eine QUERY_PATH_RESPONSE Datenstruktur festgelegt, die die Antwort enthält.

Länge des Ausgabepuffers

Größe der QUERY_PATH_RESPONSE Struktur, auf die der Ausgabepuffer zeigt, in Byte.

Eingabe-/Ausgabepuffer

–

Länge des Eingabe-/Ausgabepuffers

–

Statusblock

Das Status-Element wird auf STATUS_SUCCESS bei Erfolg festgelegt, wenn der Name des \\server\share-Präfixes erkannt wird, oder auf einen geeigneten NTSTATUS-Wert, z. B. einen der folgenden:

Statuscode	Bedeutung
STATUS_BAD_NETWORK_NAME	Der angegebene Freigabename kann auf dem Remoteserver nicht gefunden werden. Der Computername (z. B. \\server) ist gültig, aber der angegebene Freigabename kann nicht auf dem Remoteserver gefunden werden.
STATUS_BAD_NETWORK_PATH	Der Netzwerkpfad kann nicht gefunden werden. Der Computername (z. B. \\server) ist ungültig, oder der Netzwerkumleitungsor kann den Computernamen nicht auflösen (mit allen verfügbaren Mechanismen zur Namensauflösung).
STATUS_INSUFFICIENT_RESOURCES	Es waren nicht genügend Ressourcen verfügbar, um Arbeitsspeicher für Puffer zuzuweisen.
STATUS_INVALID_DEVICE_REQUEST	Eine IOCTL_REDIR_QUERY_PATH_EX Anforderung sollte nur von MUP stammen, und das RequestorMode-Element der IRP-Struktur sollte immer KernelMode sein. Dieser Fehlercode wird zurückgegeben, wenn der Anforderermodus des aufrufenden Threads nicht KernelMode war.
STATUS_INVALID_PARAMETER	Der PathNameLength-Member in der QUERY_PATH_REQUEST-Struktur überschreitet die maximal zulässige Länge (UNICODE_STRING_MAX_BYTES) für eine Unicode-Zeichenfolge.
STATUS_LOGON_FAILURE oder STATUS_ACCESS_DENIED	Wenn der Präfixauflösungsvorgang aufgrund ungültiger oder falscher Anmeldeinformationen fehlgeschlagen ist, sollte der Anbieter den genauen Fehlercode zurückgeben, der vom Remoteserver zurückgegeben wird. Diese Fehlercodes dürfen nicht in STATUS_BAD_NETWORK_NAME oder STATUS_BAD_NETWORK_PATH übersetzt werden. Fehlercodes wie STATUS_LOGON_FAILURE und STATUS_ACCESS_DENIED dienen als Feedbackmechanismus für den Benutzer und geben die Anforderung an, die entsprechenden Anmeldeinformationen zu verwenden. Diese Fehlercodes werden auch in bestimmten Fällen verwendet, um den Benutzer automatisch zur Eingabe von Anmeldeinformationen aufzufordern. Ohne diese Fehlercodes kann der Benutzer davon ausgehen, dass auf den Computer nicht zugegriffen werden kann.

Wenn der Netzwerkumleitung ein Präfix nicht auflösen kann, muss er einen NTSTATUS-Code zurückgeben, der eng mit der beabsichtigten Semantik aus der obigen Liste der empfohlenen NTSTATUS-Codes übereinstimmt. Eine Netzwerkumleitung darf den tatsächlich aufgetretenen Fehler (z. B. STATUS_CONNECTION_REFUSED) nicht direkt an MUP zurückgeben, wenn der NTSTATUS-Code nicht aus der obigen Liste stammt.

Hinweise

Netzwerkumleitungen sollten nur Kernelmodus-Absender dieser IOCTL berücksichtigen, indem sie überprüfen, ob Irp-RequestorMode>KernelMode ist.

Beachten Sie, dass IOCTL_REDIR_QUERY_PATH_EX eine METHOD_NEITHER IOCTL ist. Dies bedeutet, dass sich die Eingabe- und Ausgabepuffer möglicherweise nicht an derselben Adresse befinden. Ein häufiger Fehler von UNC-Anbietern besteht darin, davon auszugehen, dass der Eingabepuffer und der Ausgabepuffer identisch sind, und den Eingabepufferzeiger zu verwenden, um die Antwort bereitzustellen.

Wenn ein UNC-Anbieter eine IOCTL_REDIR_QUERY_PATH_EX-Anforderung empfängt, muss er bestimmen, ob er den UNC-Pfad verarbeiten kann, der im PathName-Member der QUERY_PATH_REQUEST_EX-Struktur angegeben ist. Wenn ja, muss der UNC-Anbieter den LengthAccepted-Member der QUERY_PATH_RESPONSE-Struktur mit der Länge (in Byte) des beanspruchten Präfixes aktualisieren und das IRP mit STATUS_SUCCESS. Wenn der Anbieter den angegebenen UNC-Pfad nicht verarbeiten kann, muss er die IOCTL_REDIR_QUERY_PATH_EX-Anforderung mit einem entsprechenden NTSTATUS-Fehlercode fehlschlagen und darf den LengthAccepted-Member der QUERY_PATH_RESPONSE-Struktur nicht aktualisieren. Anbieter dürfen unter keiner Bedingung andere Member oder das PathName-Element ändern.

Die Länge des vom Anbieter beanspruchten Präfixes hängt von einem einzelnen UNC-Anbieter ab. Die meisten Anbieter beanspruchen in der Regel den\\servername-Freigabename-Teil\ eines Pfads im Format \\servername\sharename\path. Wenn beispielsweise ein Anbieter \\server\public unter dem Pfad \\server\public\dir1\dir2 beansprucht hat, werden alle namenbasierten Vorgänge für das Präfix \\server\public (z. B. \\server\public\file1) automatisch ohne Präfixauflösung an diesen Anbieter weitergeleitet, da sich das Präfix bereits im Präfixcache befindet. Ein Pfad mit dem Präfix \\server\marketing\presentation durchläuft jedoch die Präfixauflösung.

Wenn eine Netzwerkumleitung einen Servernamen (z. B. \\server) anfordert, werden alle Anforderungen für Freigaben auf diesem Server an diesen Netzwerkumleitungsor gesendet. Dieses Verhalten ist nur akzeptabel, wenn es nicht möglich ist, dass auf eine andere Freigabe auf demselben Server von einem anderen Netzwerkumleitungsor zugegriffen wird. Beispielsweise verhindert ein Netzwerkumleitungsor, der \\server eines UNC-Pfads angibt, den Zugriff anderer Netzwerkumleitungen auf andere Freigaben auf diesem Server (z. B. WebDAV-Zugriff auf \\server-Web\).

Weitere Informationen finden Sie in den folgenden Abschnitten im Entwurfshandbuch: