PMRX_CREATE_SRVCALL Rückruffunktion (mrx.h)

Artikel
02/07/2025

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

[in, out] Ein Zeiger auf die zu erstellende SRV_CALL Struktur.

SrvCallCallBackContext

[in, out] Ein Zeiger auf den Rückrufkontext, der vom Netzwerk-Miniumleitungsmodul verwendet wird, um RDBSS zu benachrichtigen, wenn die MRxCreateSrvCall- Anforderung schließlich abgeschlossen ist. Der SrvCallBackContext Parameter verweist auf eine MRX_SRVCALLDOWN_STRUCTURE Struktur, die die RX_CONTEXT Struktur für diese Anforderung enthält, sowie die Callback Routine, die der Miniumleitung aufruft, wenn die MRxCreateSrvCall Anforderung schließlich abgeschlossen ist.

Rückgabewert

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

Der endgültige Abschlussstatus wird im SrvCallCallBackContext->Status Mitglied zurückgegeben, sobald der Anruf abgeschlossen ist und die Routine im Callback-Element in der MRX_SRVCALLDOWN_STRUCTURE-Struktur vom Netzwerk-Miniumleitung aufgerufen wird. Dieses Element enthält zunächst STATUS_BAD_NETWORK_PATH, bis der Netzwerkminiumleitungs-Umleitungsmodul diesen Wert nach Abschluss ändert.

Der SrvCallCallBackContext->Status Member enthält STATUS_SUCCESS bei Erfolg, sobald der Aufruf abgeschlossen ist, oder eine der folgenden allgemeinen Fehlercodes für Fehlercodes (obwohl andere Fehlercodes möglich sind):

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

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

Die Erstellung einer SRV_CALL 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 SRV_CALL-Struktur als zweistufige Aktivität modelliert. Jeder Aufruf eines Netzwerk-Miniumleitungsmoduls zum Erstellen einer SRV_CALL-Struktur wird von einem Aufruf vom Netzwerk-Miniumleitungsmodul zu RDBSS begleitet, der den Abschlussstatus der Anforderung angibt. RDBSS geht davon aus, dass MRxCreateSrvCall asynchron abgeschlossen wird. Daher erwartet RDBSS, dass MRxCreateSrvCall- STATUS_PENDING zurückgibt. RDBSS wird über die Rückrufroutine benachrichtigt, wenn der Anruf schließlich abgeschlossen ist.

Es wird erwartet, dass eine Netzwerk-Miniumleitungsimplementierung von MRxCreateSrvCall- STATUS_PENDING an den ersten Aufruf zurückgibt. Nach Abschluss der Verarbeitung ruft der Netzwerk-Miniumleitungsmodul die Rückrufroutine auf, die als Teil der SrvCallCallBackContext Parameter übergeben wird, um RDBSS zu benachrichtigen, dass der Aufruf abgeschlossen wurde und um den Abschlussstatus zurückzugeben. Die Rückrufroutine, die die Netzwerk-Miniumleitung aufruft, wird als Callback Member in der MRX_SRVCALLDOWN_STRUCTURE des SrvCallCallBackContext Parameter angegeben. Der endgültige Abschlussstatus des Aufrufs muss im Status- Mitglied des SrvCallCallBackContext Parameter gespeichert werden.

Bei Erfolg muss der Netzwerk-Miniumleitung auch einen Wert im RecommunicateContext Mitglied des SrvCallCallBackContext-speichern. Der im RecommunicateContext Member gespeicherte Wert ist der Wert, den RDBSS an MRxSrvCallWinnerNotify im RecommunicateContext Parameter übergeben wird, wenn MRxCreateSrvCall erfolgreich war. Der Netzwerkminiumleitungsmodul muss auch die entsprechenden Daten im SrvCall Parameter für die erstellte SRV_CALL Struktur ausfüllen. Beachten Sie, dass der SrvCall Parameter, der an MRxCreateSrvCall übergeben wird, mit dem SrvCall Member im MRX_SRVCALLDOWN_STRUCTURE des SrvCallCallBackContext--Parameters identisch ist. Dieser SrvCall-Parameter wird auch an MRxSrvCallWinnerNotify im parameter SrvCall übergeben.

Die Implementierung von MRxCreateSrvCall- 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 SRV_CALL-Struktur erfordert möglicherweise das Einrichten 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 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, besteht darin, dass der RDBSS-Systemprozess die Transporthandles zuordnet. Dies wirkt sich darauf aus, wie die MRxCreateSrvCall Routine ausgeführt wird. Wenn die Anforderung an MRxCreateSrvCall 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 MRxCreateSrvCall von einem anderen Prozess stammt, wird die Anforderung mit RxDispatchToWorkerThread für spätere Ausführung in eine Systemarbeitswarteschlange gepostet. RDBSS verwendet später einen seiner Systemthreads, um die Arbeitswarteschlangenanforderung zu verarbeiten und MRxCreateSrvCallauszuführen. Dadurch wird sichergestellt, dass alle Transporthandles einem Systemprozess gehören.

Ein Netzwerk-Miniumleitungsmodul kann ermitteln, ob ein Aufruf von MRxCreateSrvCall- 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 mit IoGetCurrentProcesszurü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 mithilfe von RxDispatchToWorkerThreadfür spätere Ausführung durch RDBSS bereitstellen. Normalerweise werden diese Anrufe an die DelayedWorkQueuegepostet.

Der Entwickler des Netzwerk-Miniumleitungsmoduls muss entscheiden, wie MRxCreateSrvCall implementiert wird. Wenn der Prozess zum Erstellen einer SRV_CALL eine beträchtliche Zeit in Anspruch nehmen kann, sollte MRxCreateSrvCall asynchron abgeschlossen werden. Wenn Transporthandles erforderlich sind, muss der Netzwerk-Miniumleitungsmodul einen Systemprozess finden, der langlebig ist, um diese Handles einzurichten.

Nach Abschluss dieses Aufrufs sollte der SrvCall Parameter mit den SRV_CALL Strukturinformationen geändert werden, die vom Netzwerk-Miniumleitungsmodul aktualisiert werden.

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