PMRX_CREATE_SRVCALL Rückruffunktion (mrx.h)

Artikel
10/13/2023

Die MRxCreateSrvCall-Routine wird von RDBSS aufgerufen, um anzufordern, dass der Netzwerkminiumleitungsor eine SRV_CALL-Struktur erstellt und eine Verbindung mit einem Server herstellt.

Syntax

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

NTSTATUS PmrxCreateSrvcall(
  IN OUT PMRX_SRV_CALL SrvCall,
  IN OUT PMRX_SRVCALL_CALLBACK_CONTEXT SrvCallCallBackContext
)
{...}

Parameter

SrvCall

[ein, aus] Ein Zeiger auf die zu erstellende SRV_CALL-Struktur.

SrvCallCallBackContext

[ein, aus] Ein Zeiger auf den Rückrufkontext, der vom Netzwerkminiumleitungsor verwendet wird, um RDBSS zu benachrichtigen, wenn die MRxCreateSrvCall-Anforderung endgültig abgeschlossen ist. Der SrvCallCallBackContext-Parameter verweist auf eine MRX_SRVCALLDOWN_STRUCTURE-Struktur, die die RX_CONTEXT Struktur für diese Anforderung enthält, sowie auf die Rückrufroutine , die der Mini-Redirector aufruft, wenn die MRxCreateSrvCall-Anforderung endgültig abgeschlossen ist.

Rückgabewert

RDBSS erwartet , dass MRxCreateSrvCall 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 MRxCreateSrvCall zuordnen.

Die endgültige Vervollständigung status wird im SrvCallCallBackContext-Status-Member> zurückgegeben, sobald der Aufruf abgeschlossen ist und die Routine im Rückrufelement in der MRX_SRVCALLDOWN_STRUCTURE-Struktur vom Netzwerk-Mini-Redirector aufgerufen wird. Dieses Element enthält zunächst STATUS_BAD_NETWORK_PATH, bis der Netzwerkminiumleitungsor diesen Wert nach Abschluss ändert.

Das SrvCallCallBackContext-Status-Element> enthält STATUS_SUCCESS nach Abschluss des Aufrufs oder einen der folgenden gängigen Fehlercodes bei Fehler (obwohl andere Fehlercodes möglich sind):

Rückgabecode	Beschreibung
STATUS_BAD_NETWORK_PATH	Der angegebene Netzwerkpfad ist fehlerhaft.
STATUS_NETWORK_UNREACHABLE	Das Netzwerk war nicht erreichbar.

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-Struktur. Eine SRV_CALL Struktur entspricht dem Kontext, der einem Server zugeordnet ist, sobald eine Verbindung hergestellt wird. Eine NET_ROOT-Struktur entspricht einer Freigabe auf einem Server (dies kann auch als Teil des Namespace angezeigt werden, der von einem Netzwerkminiumleitungsor beansprucht wurde).

Die Erstellung einer SRV_CALL-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 SRV_CALL-Struktur als zweiphasige Aktivität modelliert. Jeder Aufruf einer Netzwerkminiumleitung zum Erstellen einer SRV_CALL-Struktur wird von einem Aufruf vom Netzwerkminiumleitungsor an RDBSS begleitet, der den Abschluss status der Anforderung angibt. RDBSS geht davon aus, dass MRxCreateSrvCall asynchron abgeschlossen wird. Daher erwartet RDBSS, dass MRxCreateSrvCall STATUS_PENDING zurückgibt. RDBSS wird mithilfe der Rückrufroutine benachrichtigt, wenn der Anruf schließlich abgeschlossen ist.

Es wird erwartet, dass eine Netzwerkminiumleitungsimplementierung von MRxCreateSrvCall STATUS_PENDING zum ersten Aufruf zurückgibt. Nach Abschluss der Verarbeitung ruft der Netzwerkminiumleitungsor die Rückrufroutine auf, die als Teil des SrvCallCallBackContext-Parameters übergeben wird, um RDBSS darüber zu informieren, dass der Aufruf abgeschlossen wurde, und um den Abschluss status zurückzugeben. Die Rückrufroutine, die der Netzwerkminiumleitungsor aufruft, wird als Rückrufelement im MRX_SRVCALLDOWN_STRUCTURE des SrvCallCallBackContext-Parameters angegeben. Der endgültige Abschluss status des Aufrufs muss im Statuselement des SrvCallCallBackContext-Parameters gespeichert werden.

Bei Erfolg muss der Netzwerkminiumleitungsor auch einen Wert im RecommunicateContext-Member des SrvCallCallBackContext-Elements speichern. Der im RecommunicateContext-Member gespeicherte Wert ist der Wert, den RDBSS im RecommunicateContext-Parameter an MRxSrvCallWinnerNotify übergibt, wenn MRxCreateSrvCall erfolgreich war. Der Netzwerkminiumleitungsor muss auch die entsprechenden Daten im SrvCall-Parameter für die SRV_CALL-Struktur ausfüllen, die erstellt wurde. Beachten Sie, dass der an MRxCreateSrvCall übergebene SrvCall-Parameter mit dem SrvCall-Member im MRX_SRVCALLDOWN_STRUCTURE des SrvCallCallBackContext-Parameters identisch ist. Derselbe SrvCall-Parameter wird auch im SrvCall-Parameter an MRxSrvCallWinnerNotify übergeben.

Die Implementierung von MRxCreateSrvCall 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 SRV_CALL-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 kurzlebig sein könnte, nicht sinnvoll. Daher muss eine SRV_CALL 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 verwendet wird, um die potenziellen Probleme mit Transporthandles zu umgehen, ist die Zuordnung der Transporthandles durch den RDBSS-Systemprozess. Dies wirkt sich auf die Ausführung der MRxCreateSrvCall-Routine aus. Wenn die Anforderung an MRxCreateSrvCall 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 MRxCreateSrvCall 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 MRxCreateSrvCall auszuführen. Dadurch wird sichergestellt, dass alle Transporthandles im Besitz eines Systemprozesses sind.

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

Der Entwickler des Netzwerkminiumleitungs kann entscheiden, wie MRxCreateSrvCall implementiert wird. Wenn der Prozess zum Erstellen einer SRV_CALL viel Zeit in Anspruch nehmen kann, sollte MRxCreateSrvCall asynchron abgeschlossen werden. Wenn Transporthandles erforderlich sind, muss der Netzwerkminiumleitung einen Systemprozess finden, der langlebig ist, um diese Handles einzurichten.

Wenn dieser Aufruf abgeschlossen ist, sollte der SrvCall-Parameter geändert werden, wobei die SRV_CALL Strukturinformationen aus dem Netzwerkmini-Redirector aktualisiert werden.

Ein Netzwerkminiumleitungsor, der die Unterstützung als UNC-Anbieter angibt, erhält einen Präfixanspruch vom MUP (Multiple UNC Provider) als Aufruf von MRxCreateSrvCall. Weitere Informationen zu UNC-Benennung und MUP finden Sie unter Unterstützung für UNC-Benennung und MUP.