PMRX_CREATE_V_NET_ROOT Rückruffunktion (mrx.h)

Artikel
02/26/2024

Die MRxCreateVNetRoot-Routine wird von RDBSS aufgerufen, um anzufordern, dass der Netzwerkminiumleitungsor eine V_NET_ROOT-Struktur und in einigen Fällen eine NET_ROOT-Struktur erstellt.

Syntax

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

NTSTATUS PmrxCreateVNetRoot(
  IN OUT PMRX_CREATENETROOT_CONTEXT Context
)
{...}

Parameter

Context

[ein, aus] Ein Zeiger auf den Rückrufkontext, der vom Netzwerk-Miniumleitungsor verwendet wird, um RDBSS zu benachrichtigen, wenn der Aufruf abgeschlossen ist. Dies schließt die RX_CONTEXT Struktur der Anforderung unter Context-RxContext> ein. Der Context-Parameter enthält die V_NET_ROOT Struktur, die in Context-pVNetRoot> erstellt werden soll. Diese V_NET_ROOT-Struktur enthält einen Zeiger auf die NET_ROOT-Struktur in pVNetRoot-pNetRoot>. Die NET_ROOT-Struktur enthält auch einen Zeiger auf die SRV_CALL-Struktur in pNetRoot-pSrvCall>.

Rückgabewert

RDBSS erwartet, dass MRxCreateVNetRoot bei Erfolg oder Fehler STATUS_PENDING zurückgibt. Dieses Verhalten ergibt sich, da RDBSS erwartet, dass dieser Aufruf asynchron abgeschlossen wird. Ein Netzwerkminiumleitungsor sollte STATUS_SUCCESS STATUS_PENDING als Rückgabewert für MRxCreateVNetRoot zuordnen.

Die endgültige Vervollständigung status wird in den Membern Context-VirtualNetRootStatus> und Context-NetRootStatus> zurückgegeben, sobald der Aufruf abgeschlossen ist und die Routine im Rückrufelement der Kontextstruktur vom Netzwerk-Mini-Redirector aufgerufen wird. Diese Member enthalten zunächst STATUS_SUCCESS, bis der Netzwerkminiumleitungsor diesen Wert nach Abschluss ändert. Wenn der Aufruf erfolgreich abgeschlossen wurde, enthalten beide Member STATUS_SUCCESS.

Wenn eine V_NET_ROOT- oder NET_ROOT-Struktur nicht erstellt wurde, wird einer der folgenden häufigen Fehlercodes für dasElement VirtualNetRootStatus oder NetRootStatus zurückgegeben (obwohl andere Fehlercodes möglich sind):

Rückgabecode	Beschreibung
STATUS_CONNECTION_RESET	Die Verbindung mit der Remoteressource wurde zurückgesetzt.
STATUS_IO_TIMEOUT	Bei einer E/A-Anforderung ist ein Timeout aufgetreten.
STATUS_RETRY	Ein Remotestartserver war nicht bereit, die Anforderung zu erfüllen.
STATUS_UNEXPECTED_NETWORK_ERROR	Ein unerwarteter Netzwerkfehler ist normalerweise durch ein ungültiges Handle verursacht.

Hinweise

Die beiden wichtigen Abstraktionen, die in der Schnittstelle zwischen RDBSS und einem Netzwerk-Mini-Redirector verwendet werden, sind die SRV_CALL-Struktur und die NET_ROOT/V_NET_ROOT-Struktur. Eine SRV_CALL-Struktur entspricht dem Kontext, der einem Server zugeordnet ist, mit dem eine Verbindung hergestellt wurde. Eine NET_ROOT Struktur entspricht einer Freigabe auf einem Server. Eine V_NET_ROOT-Struktur könnte als Teil des Namespace unterhalb einer NET_ROOT Struktur angezeigt werden, die von einem Netzwerkminiumleitungsor beansprucht wird.

Die Erstellung einer NET_ROOT/V_NET_ROOT-Struktur umfasst in der Regel mindestens eine Netzwerk-Rundreise. Dieser Vorgang kann viel Zeit in Anspruch nehmen, da möglicherweise eine Netzwerkverbindung mit einer Remoteressource hergestellt werden muss. Um sicherzustellen, dass die asynchronen Vorgänge fortgesetzt werden, wird die Erstellung einer NET_ROOT/V_NET_ROOT-Struktur als zweiphasige Aktivität modelliert. Jedem Aufruf einer Netzwerkminiumleitung zum Erstellen einer NET_ROOT/V_NET_ROOT-Struktur folgt ein Rückruf vom Netzwerkminiumleitungsor an RDBSS, der RDBSS den Abschluss status der Anforderung an den Netzwerkminiumleitungsor angibt. Da RDBSS erwartet, dass MRxCreateVNetRoot asynchron abgeschlossen wird, erwartet RDBSS, dass MRxCreateVNetRoot STATUS_PENDING zurückgibt. RDBSS wird mithilfe der Rückrufroutine benachrichtigt, wenn der Anruf schließlich abgeschlossen ist.

MRxCreateVNetRoot muss zwei interessante Fälle behandeln:

Eine neue V_NET_ROOT-Struktur und die zugehörige neue NET_ROOT-Struktur werden erstellt.
Es wird eine neue V_NET_ROOT-Struktur erstellt, die einer vorhandenen NET_ROOT-Struktur zugeordnet ist.

Diese beiden Fälle können unterschieden werden, indem überprüft wird, ob der Kontext, der einer NET_ROOT-Struktur zugeordnet ist, NULL ist.

Es wird erwartet, dass eine Netzwerkminiumleitungsimplementierung von MRxCreateVNetRoot STATUS_PENDING zum ersten Aufruf zurückgibt. Wenn die Verarbeitung abgeschlossen ist, ruft der Netzwerkminiumleitungsgeber die Rückrufroutine auf, die als Teil des Context-Parameters übergeben wurde, um RDBSS über den Abschluss des Aufrufs zu informieren und den Abschluss status zurückzugeben. Die Rückrufroutine, für die der Netzwerkminiumleitungsor aufrufen soll, wird als Rückrufelement in der MRX_CREATENETROOT_CONTEXT Struktur angegeben, die als Context-Parameter übergeben wird. Der endgültige Abschluss status des MRxCreateVNetRoot-Aufrufs muss in den Membern VirtualNetRootStatus und NetRootStatus des Context-Parameters gespeichert werden. Beachten Sie, dass separate status für die NET_ROOT- und V_NET_ROOT-Strukturen zurückgegeben werden.

Die Implementierung von MRxCreateVNetRoot in einem Netzwerk-Mini-Redirector ist auch durch die Notwendigkeit von Transporthandles kompliziert. Für bestimmte transportbezogene Schnittstellen muss ein Handle erstellt und für die gesamte Kommunikation verwendet werden. Das Erstellen einer NET_ROOT- oder V_NET_ROOT-Struktur erfordert möglicherweise das Einrichten transportbezogener Handles für die Netzwerkkommunikation. Da der Prozess des Herstellens einer Netzwerkverbindung zeitaufwändig sein kann, ist es sinnvoll, die Verbindung nach dem Herstellen einer Verbindung so lange wie möglich für die Kommunikation zu verwenden. Sobald ein Transporthandle zu einer Remotenetzwerkressource eingerichtet wurde, kann es von einer beliebigen Anzahl anderer Anwendungsanforderungen wiederverwendet werden. Wenn eine Benutzeranwendung beendet wird, werden die dem Prozess zugeordneten Handles gelöscht. Aus diesem Grund ist das Einrichten von Transporthandles im Kontext eines vorübergehenden Benutzermodusprozesses, der möglicherweise kurzlebig ist, nicht sinnvoll. Daher muss eine NET_ROOT oder V_NET_ROOT Struktur normalerweise im Kontext eines bekannten Prozesses initialisiert werden, der nicht verschwindet, wenn diese Transporthandles für die Kommunikation verwendet werden.

Eine Methode, die verwendet wird, um dies in Netzwerkminiumleitungen zu verwalten, besteht darin, dass der RDBSS-Systemprozess diese Transporthandles ordnet. Dies wirkt sich auf die Ausführung der MRxCreateVNetRoot-Routine aus. Wenn die Anforderung an MRxCreateVNetRoot im Kontext des RDBSS-Systemprozesses ausgestellt wurde, kann dieser Aufruf sofort ausgeführt werden und muss nicht an eine Arbeitswarteschlange gesendet werden. Wenn die Anforderung an MRxCreateVNetRoot von einem anderen Prozess stammt, wird die Anforderung jedoch mithilfe von RxDispatchToWorkerThread zur späteren Ausführung an eine Systemarbeitswarteschlange gesendet, um Probleme zu vermeiden. RDBSS verwendet später einen seiner Systemthreads, um die Arbeitswarteschlangenanforderung zu verarbeiten und MRxCreateVNetRoot auszuführen. Dadurch wird sichergestellt, dass alle Transporthandles im Besitz eines Systemprozesses sind.

Ein Netzwerkminiumleitungsor kann ermitteln, ob ein Aufruf von MRxCreateVNetRoot direkt von RDBSS empfangen wurde, indem RxGetRDBSSProcess aufgerufen wird. RxGetRDBSSProcess gibt den RDBBS-Prozess zurück, und dieser Wert kann mit dem aktuellen zurückgegebenen Prozess verglichen werden, indem IoGetCurrentProcess aufgerufen wird. Wenn der Aufruf von MRxCreateVNetRoot nicht im Kontext des RDBSS-Systemprozesses initiiert wurde, kann MRxCreateVNetRoot STATUS_PENDING zurückgeben und den Aufruf an eine Arbeitswarteschlange mit RxDispatchToWorkerThread zur späteren Ausführung durch RDBSS senden. Normalerweise werden diese Anrufe an die DelayedWorkQueue gesendet.

Die Implementierung von MRxCreateVNetRoot muss vom Mini-Redirector des Netzwerks bestimmt werden. Wenn dieser Prozess viel Zeit in Anspruch nehmen kann, sollte dieser Aufruf asynchron abgeschlossen werden. Wenn Transporthandles erforderlich sind, möchte der Netzwerkminiumleitungsor möglicherweise einen Systemprozess, der langlebig ist, um diese Handles einzurichten.

Falls die Verbindung nicht hergestellt werden kann, kann der Netzwerkminiumleitungsor versuchen, die NET_ROOT und V_NET_ROOT Strukturen in einen getrennten Modus zu überführen (sofern dies unterstützt wird) und die Verbindung offline herzustellen.

Wenn MRxCreateVNetRoot abgeschlossen ist, sollte der Context-Parameter mit den entsprechenden NET_ROOT und V_NET_ROOT Strukturinformationen geändert werden, die vom Netzwerk-Mini-Redirector aktualisiert werden.