PMRX_CREATE_V_NET_ROOT Rückruffunktion (mrx.h)

Artikel
02/07/2025

Die MRxCreateVNetRoot Routine wird von RDBSS- aufgerufen, um anzufordern, dass der Netzwerkminiumleitungsmodul 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

[in, out] Ein Zeiger auf den Rückrufkontext, der vom Netzwerk-Miniumleitungsmodul verwendet wird, um RDBSS zu benachrichtigen, wenn der Anruf schließlich abgeschlossen ist. Dazu gehört die RX_CONTEXT Struktur der Anforderung bei Context->RxContext-. Der parameter Context enthält die V_NET_ROOT Struktur, die bei Context->pVNetRoot-erstellt werden soll. Diese V_NET_ROOT Struktur enthält einen Zeiger auf die NET_ROOT Struktur bei pVNetRoot->pNetRoot-. Die NET_ROOT-Struktur enthält auch einen Zeiger auf die SRV_CALL Struktur bei pNetRoot->pSrvCall.

Rückgabewert

RDBSS erwartet, dass MRxCreateVNetRoot- STATUS_PENDING bei Erfolg oder Fehler zurückgibt. Dieses Verhalten führt dazu, dass RDBSS erwartet, dass dieser Aufruf asynchron abgeschlossen wird. Ein Netzwerkminiumleitung sollte STATUS_SUCCESS STATUS_PENDING als Rückgabewert für MRxCreateVNetRoot-zuordnen.

Der endgültige Abschlussstatus wird in Context->VirtualNetRootStatus- und Context->NetRootStatus-Member zurückgegeben, sobald der Aufruf abgeschlossen ist und die Routine im Callback Member der Context-Struktur vom Netzwerkminiumleitungsmodul aufgerufen wird. Diese Member enthalten zunächst STATUS_SUCCESS, bis der Netzwerk-Miniumleitungsmodul diesen Wert nach Abschluss ändert. Wenn der Anruf erfolgreich abgeschlossen wurde, enthalten beide Member STATUS_SUCCESS.

Beim Fehler beim Erstellen einer V_NET_ROOT- oder NET_ROOT-Struktur wird eine der folgenden allgemeinen Fehlercodes für dieVirtualNetRootStatus- oder NetRootStatus Member 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	Unerwarteter Netzwerkfehler ist in der Regel durch ein ungültiges Handle verursacht.

Bemerkungen

Die beiden wichtigen Abstraktionen, die in der Schnittstelle zwischen RDBSS und einem Netzwerk-Miniumleitung 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 Namespaces unter einer NET_ROOT Struktur betrachtet werden, die von einem Netzwerk-Miniumleitungsmodul beansprucht wird.

Die Erstellung einer NET_ROOT/V_NET_ROOT-Struktur umfasst in der Regel mindestens einen Netzwerk-Roundtrip. Dieser Vorgang kann erhebliche 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 zweistufige Aktivität modelliert. Jeder Aufruf eines Netzwerk-Miniumleitungsmoduls zum Erstellen einer NET_ROOT/V_NET_ROOT-Struktur folgt einem Rückruf vom Netzwerk-Miniumleitungsmodul an RDBSS, der rdBSS den Abschlussstatus der Anforderung an den Netzwerkminiumleitungsmodul angibt. Da RDBSS erwartet, dass MRxCreateVNetRoot- asynchron abgeschlossen ist, erwartet RDBSS, MRxCreateVNetRoot- STATUS_PENDING zurückzugeben. RDBSS wird über die Rückrufroutine benachrichtigt, wenn der Anruf schließlich abgeschlossen ist.

MRxCreateVNetRoot müssen zwei Interessenfälle behandeln:

Eine neue V_NET_ROOT Struktur und die zugeordnete 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 MRxCreateVNetRoot- eine Netzwerk-Miniumleitungsimplementierung STATUS_PENDING zum ersten Aufruf zurückgibt. Nach Abschluss der Verarbeitung ruft der Netzwerkminiumleitungs-Umleitungsmodul die im Rahmen des Context Parameter übergebene Rückrufroutine auf, um RDBSS darüber zu informieren, dass der Aufruf abgeschlossen wurde und den Abschlussstatus zurückgibt. Die Rückrufroutine, zu der der Netzwerkminiumleitung aufgerufen werden soll, wird als Callback Member in der MRX_CREATENETROOT_CONTEXT-Struktur angegeben, die als Context-Parameter übergeben wird. Der endgültige Abschlussstatus des MRxCreateVNetRoot--Aufrufs muss im VirtualNetRootStatus- und NetRootStatus- Member des Context--Parameters gespeichert werden. Beachten Sie, dass separater Status für die NET_ROOT- und V_NET_ROOT-Strukturen zurückgegeben wird.

Die Implementierung von MRxCreateVNetRoot- in einem Netzwerk-Miniumleitungsmodul ist auch durch die Notwendigkeit von Transporthandles kompliziert. Für bestimmte transportbezogene Schnittstellen muss ein Handle erstellt und für jede Kommunikation verwendet werden. Das Erstellen einer NET_ROOT- oder V_NET_ROOT-Struktur erfordert möglicherweise die Einrichtung transportbezogener Handles für die Netzwerkkommunikation. Da der Prozess der Einrichtung einer Netzwerkverbindung zeitaufwändig sein kann, ist es sinnvoll, die Verbindung so lange wie möglich 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 sein kann, nicht sinnvoll. Daher muss eine NET_ROOT- oder V_NET_ROOT-Struktur normalerweise im Kontext eines bekannten Prozesses initialisiert werden, der nicht verschwindet, während diese Transporthandles für die Kommunikation verwendet werden.

Eine Methode, die zum Verwalten dieses Vorgangs in Netzwerk-Miniumleitungen verwendet wird, besteht darin, dass der RDBSS-Systemprozess diese Transporthandles zuweist. Dies wirkt sich darauf aus, wie die MRxCreateVNetRoot Routine ausgeführt wird. Wenn die Anforderung an MRxCreateVNetRoot im Kontext des RDBSS-Systemprozesses ausgegeben wurde, kann dieser Aufruf sofort ausgeführt werden und muss nicht in eine Arbeitswarteschlange gestellt werden. Um Jedoch Probleme zu vermeiden, wenn die Anforderung an MRxCreateVNetRoot von einem anderen Prozess stammt, wird die Anforderung mithilfe von RxDispatchToWorkerThread für spätere Ausführung in eine Systemarbeitswarteschlange gepostet. RDBSS verwendet später einen seiner Systemthreads, um die Arbeitswarteschlangenanforderung zu verarbeiten und MRxCreateVNetRootauszuführen. Dadurch wird sichergestellt, dass alle Transporthandles einem Systemprozess gehören.

Ein Netzwerk-Miniumleitungsmodul kann ermitteln, ob ein Aufruf von MRxCreateVNetRoot- direkt von RDBSS empfangen wurde, indem RxGetRDBSSProcessaufgerufen wurde. RxGetRDBSSProcess gibt den RDBBS-Prozess zurück, und dieser Wert kann mit dem aktuellen Prozess verglichen werden, der durch Aufrufen IoGetCurrentProcesszurückgegeben wird. Wenn der Aufruf von MRxCreateVNetRoot- nicht im Kontext des RDBSS-Systemprozesses initiiert wurde, können MRxCreateVNetRoot- STATUS_PENDING zurückgeben und den Aufruf an eine Arbeitswarteschlange mithilfe von RxDispatchToWorkerThread für spätere Ausführung durch RDBSS senden. Normalerweise werden diese Anrufe an die DelayedWorkQueuegepostet.

Es liegt bei der Miniumleitung des Netzwerks, um zu entscheiden, wie MRxCreateVNetRoot- implementiert wird. Wenn dieser Vorgang sehr viel Zeit in Anspruch nehmen kann, sollte dieser Aufruf asynchron abgeschlossen werden. Wenn Transporthandles erforderlich sind, kann der Netzwerk-Miniumleitungsmodul einen Systemprozess verwenden, der langlebig ist, um diese Handles einzurichten.

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

Wenn MRxCreateVNetRoot abgeschlossen ist, sollte der parameter Context mit den entsprechenden NET_ROOT und V_NET_ROOT Strukturinformationen geändert werden, die vom Miniumleitungsmodul des Netzwerks aktualisiert werden.