IOCTL_REDIR_QUERY_PATH IOCTL (ntifs.h)

Artikel
06/28/2024

Der IOCTL_REDIR_QUERY_PATH Steuercode wird vom mehrfachen UNC-Anbieter (MUP) an Netzwerkumleitungen gesendet, 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 verantwortlich ist, die einen UNC-Namen zu einem Netzwerkumleitungsanbieter (UNC-Anbieter) verwenden, 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.

Unter Windows Server 2003, Windows XP und Windows 2000 durchlaufen Remotedateivorgänge, die auf einem zugeordneten Laufwerk ausgeführt werden, das kein DFS-Laufwerk (Distributed File System) darstellt, nicht über MUP. Diese Vorgänge gehen direkt an den Netzwerkanbieter, der die Laufwerkbuchstabenzuordnung verarbeitet hat.

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 Steuercode wird an Netzwerkumleitungen gesendet, die sich bei MUP als UNC-Anbieter (Universal Naming Convention) registriert haben, indem FsRtlRegisterUncProvideraufgerufen 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) zum gleichen Anbieter gehen, der MUP vollständig umgeht.
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, zu welchem Zeitpunkt MUP die Präfixauflösung für dieses Präfix für einen nachfolgenden namensbasierten Vorgang erneut ausführt.

Hauptcode

IOCTL_REDIR_QUERY_PATH

Eingabepuffer

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

Eingabepufferlänge

Länge des Eingabepuffers in Bytes, die mindestens sizeof(QUERY_PATH_REQUEST)sein müssen.

Ausgabepuffer

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

Länge des Ausgabepuffers

Länge des Ausgabepuffers in Bytes, die mindestens sizeof(QUERY_PATH_RESPONSE)sein müssen.

Eingabe-/Ausgabepuffer

n/a

Länge des Eingabe-/Ausgabepuffers

n/a

Statusblock

Das Status- Mitglied wird auf erfolgswirksam STATUS_SUCCESS festgelegt, wenn der Präfixname \\server\freigabe erkannt wird oder auf einen entsprechenden NTSTATUS-Wert, wie z. B. einer 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 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 der Eingabepufferzeiger verwendet wird, um die Antwort bereitzustellen.

Wenn ein UNC-Anbieter eine IOCTL_REDIR_QUERY_PATH Anforderung empfängt, muss er bestimmen, ob er den UNC-Pfad verarbeiten kann, der im FilePathName Member der QUERY_PATH_REQUEST-Struktur angegeben ist. Wenn ja, muss das LengthAccepted Member der QUERY_PATH_RESPONSE-Struktur mit der Länge (in Byte) des Präfixes aktualisiert und das IRP mit STATUS_SUCCESS abgeschlossen werden. Wenn der Anbieter den angegebenen UNC-Pfad nicht verarbeiten kann, muss die IOCTL_REDIR_QUERY_PATH Anforderung mit einem entsprechenden NTSTATUS-Fehlercode fehlschlagen und darf den LengthAccepted Member der QUERY_PATH_RESPONSE-Struktur nicht aktualisieren. Anbieter dürfen keines der anderen Member oder die FilePathName- Zeichenfolge 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 Artikeln: