IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

Artikel
12/21/2024

Ab Windows Vista sendet der mehrere UNC-Anbieter (MUP) einen IOCTL_REDIR_QUERY_PATH_EX Steuercode an Netzwerkumleitungen, um zu ermitteln, 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 für das Kanalieren aller Remotedateisystemzugriffe mit einem UNC-Namen zu einem UNC-Anbieter (dem UNC-Anbieter) verantwortlich ist, der die Remotedateisystemanforderungen verarbeiten kann. MUP ist beteiligt, wenn ein UNC-Pfad verwendet wird, wie im folgenden Beispiel dargestellt, das über eine Befehlszeile ausgeführt werden kann:

notepad \\server\public\readme.txt

MUP ist während eines Vorgangs nicht beteiligt, der einen zugeordneten Laufwerkbuchstaben erstellt (z. B. den Befehl "NET USE"). Dieser Vorgang wird vom 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 jedoch während dieses Vorgangs direkt mit einem Kernelmodus-Netzwerkumleitungstreiber 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, durchlaufen MUP zum Netzwerkumleitungsmodul. Beachten Sie, dass MUP in diesem Fall einfach den Vorgang an den Netzwerkumleitungsmodul übergibt, der beteiligt ist.

Der IOCTL_REDIR_QUERY_PATH_EX-Steuerelementcode wird an Netzwerkumleitungen gesendet, die sich bei MUP als UNC-Anbieter (Universal Naming Convention) registriert haben, indem FsRtlRegisterUncProviderExaufgerufen wird. Bei MUP können mehrere UNC-Anbieter registriert sein.

Der Präfixauflösungsvorgang dient zwei Zwecken:

Der namebasierte Vorgang, der zu der Präfixauflösung führte, 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 für 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 vollständig für nachfolgende Handle-basierte Vorgänge umgangen.
Der Anbieter und das Präfix, das er behauptet hat, werden in einen Präfixcache eingegeben, der von MUP verwaltet wird. Bei nachfolgenden namensbasierten Vorgängen 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 entfernt, an dem MUP die Präfixauflösung für dieses Präfix für einen nachfolgenden namensbasierten Vorgang erneut ausführt.

Hauptcode

IOCTL_REDIR_QUERY_PATH_EX

Eingabepuffer

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

Eingabepufferlänge

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

Ausgabepuffer

IRP->UserBuffer- wird 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 in Bytes verweist.

Eingabe-/Ausgabepuffer

n/a

Länge des Eingabe-/Ausgabepuffers

n/a

Statusblock

Der Status- Members wird bei Erfolg auf STATUS_SUCCESS festgelegt, wenn der Präfixname \\server\freigabe erkannt wird, oder auf einen geeigneten NTSTATUS-Wert, z. B. einen der folgenden Werte:

Statuscode	Bedeutung
STATUS_BAD_NETWORK_NAME	Der angegebene Freigabename kann auf dem Remoteserver nicht gefunden werden. Der Computername (z. B. \\Server) ist gültig, der angegebene Freigabename kann jedoch 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 Netzwerkumleitungsmodul kann den Computernamen nicht auflösen (mit den verfügbaren Namensauflösungsmechanismen).
STATUS_INSUFFICIENT_RESOURCES	Es waren unzureichende Ressourcen verfügbar, um Speicher für Puffer zuzuweisen.
STATUS_INVALID_DEVICE_REQUEST	Eine IOCTL_REDIR_QUERY_PATH_EX Anforderung sollte nur von MUP stammen, und das RequestorMode Mitglied der IRP-Struktur sollte immer KernelMode-sein. Dieser Fehlercode wird zurückgegeben, wenn der Anforderermodus des aufrufenden Threads nicht KernelMode-wurde.
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, geeignete 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 kein Präfix 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. Ein Netzwerkumleitungsmodul 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.

Bemerkungen

Netzwerkumleitungen sollten nur Kernelmodus-Absender dieses IOCTL berücksichtigen, indem überprüft wird, ob Irp->RequestorMode-KernelMode-ist.

Beachten Sie, dass IOCTL_REDIR_QUERY_PATH_EX ein 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 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 das LengthAccepted Member der QUERY_PATH_RESPONSE-Struktur mit der Länge (in Bytes) des Präfixes aktualisieren, das er beansprucht hat, und das IRP mit STATUS_SUCCESS abschließen. Wenn der Anbieter den angegebenen UNC-Pfad nicht verarbeiten kann, muss die IOCTL_REDIR_QUERY_PATH_EX Anforderung mit einem entsprechenden NTSTATUS-Fehlercode fehlschlagen und darf das LengthAccepted Member der QUERY_PATH_RESPONSE-Struktur nicht aktualisieren. Anbieter dürfen keine anderen Mitglieder oder das PathName Mitglied unter irgendeiner Bedingung ä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 Servernamen \\\ShareName Teil eines Pfads des Formulars \\Servername\\Pfad. Beispiel: wenn ein Anbieter \\Server\öffentlichen einem Pfad \\Server\öffentlichen\dir1\dir2, alle namenbasierten Vorgänge für das Präfix \\Server\öffentlichen (\\Server\öffentliche\Datei1) wird automatisch ohne Präfixauflösung an diesen Anbieter weitergeleitet, da sich das Präfix bereits im Präfixcache. Ein Pfad mit dem Präfix \\Server\Marketing\Präsentation durchläuft jedoch die Präfixauflösung.

Wenn ein Netzwerkumleitung einen Servernamen (\\Serverbeispielsweise) anfordert, gehen alle Anforderungen für Freigaben auf diesem Server an diesen Netzwerkumleitungsor. Dieses Verhalten ist nur akzeptabel, wenn es keine Möglichkeit gibt, dass auf demselben Server von einem anderen Netzwerkumleitungsmodul auf eine andere Freigabe zugegriffen wird. Ein Netzwerkumleitungsmodul, der \\Server eines UNC-Pfads angibt, verhindert z. B. den Zugriff anderer Netzwerkumleitungen auf andere Freigaben auf diesem Server (WebDAV-Zugriff auf \\Server\Web-).

Weitere Informationen finden Sie in den folgenden Abschnitten im Entwurfshandbuch: