RpcServerListen-Funktion (rpcdce.h)

Artikel
08/25/2023

Die RpcServerListen-Funktion signalisiert der RPC-Laufzeitbibliothek, auf Remoteprozeduraufrufe zu lauschen. Diese Funktion wirkt sich nicht auf Schnittstellen zum automatischen Lauschen aus. Verwenden Sie RpcServerRegisterIfEx , wenn Sie diese Funktionalität benötigen.

Syntax

RPC_STATUS RpcServerListen(
  unsigned int MinimumCallThreads,
  unsigned int MaxCalls,
  unsigned int DontWait
);

Parameter

MinimumCallThreads

Hinweis auf die RPC-Laufzeit, die die Mindestanzahl von Aufrufthreads angibt, die auf dem angegebenen Server erstellt und verwaltet werden sollen. Dieser Wert ist nur ein Hinweis und wird in verschiedenen Versionen von Windows unterschiedlich interpretiert. In Windows XP ist dieser Wert die Anzahl der zuvor erstellten Threads in jedem Threadpool, die die RPC-Laufzeit erstellt. Eine Anwendung sollte einen für diesen Parameter angeben und Entscheidungen zur Threaderstellung auf die RPC-Laufzeit zurückstellen.

MaxCalls

Empfohlene maximale Anzahl gleichzeitiger Remoteprozeduraufrufe, die der Server ausführen kann. Um eine effiziente Leistung zu ermöglichen, interpretieren die RPC-Laufzeitbibliotheken den MaxCalls-Parameter als vorgeschlagene Grenze und nicht als absolute Obergrenze.

Verwenden Sie RPC_C_LISTEN_MAX_CALLS_DEFAULT, um den Standardwert anzugeben.

DontWait

Flag, das die Rückgabe von RpcServerListen steuert. Der Wert nonzero gibt an, dass RpcServerListen sofort nach Abschluss der Funktionsverarbeitung zurückgegeben werden soll. Der Wert null gibt an, dass RpcServerListen erst zurückgegeben werden soll, wenn die RpcMgmtStopServerListening-Funktion aufgerufen wurde und alle Remoteaufrufe abgeschlossen wurden.

Rückgabewert

Wert	Bedeutung
RPC_S_OK	Der Aufruf war erfolgreich.
RPC_S_ALREADY_LISTENING	Der Server lauscht bereits.
RPC_S_NO_PROTSEQS_REGISTERED	Es sind keine Protokollsequenzen registriert.
RPC_S_MAX_CALLS_TOO_SMALL	Der maximale Aufrufwert ist zu klein.

Hinweis Eine Liste der gültigen Fehlercodes finden Sie unter RPC-Rückgabewerte.

Hinweise

Ein Server ruft RpcServerListen auf, wenn der Server bereit ist, Remoteprozeduraufrufe zu verarbeiten. RPC ermöglicht es einem Server, mehrere Aufrufe gleichzeitig zu verarbeiten. Der MaxCalls-Parameter empfiehlt die maximale Anzahl gleichzeitiger Remoteprozeduraufrufe, die der Server ausführen soll.

Der MaxCalls-Wert sollte nicht 0 sein und größer als MinimumCallThreads sein. Werte, die größer als 0x7FFFFFFF sind, werden ohne Hinweis auf 0x7FFFFFFF festgelegt.

Windows XP/2000: Wenn Sie den MaxCalls-Parameter auf RPC_C_LISTEN_MAX_CALLS_DEFAULT festlegen, wird der Grenzwert für gleichzeitige Remoteprozeduraufrufe aufgehoben, anstatt ihn auf den konstanten definierten Wert 1234 festzulegen. Das Entfernen des Grenzwerts für maximale gleichzeitige Aufrufe ermöglicht so viele gleichzeitige Remoteprozeduraufrufe, wie der Computer verarbeiten kann. Dieses Verhalten ermöglicht eine höhere Effizienz in der RPC-Laufzeit.

Eine Serveranwendung ist für die Parallelitätssteuerung zwischen den Server-Manager-Routinen verantwortlich, da jede Routine in einem separaten Thread ausgeführt wird.

Wenn der DontWait-Parameter den Wert 0 aufweist, lauscht die RPC-Laufzeitbibliothek weiterhin auf Remoteprozeduraufrufe (d. a. die Routine kehrt nicht an die Serveranwendung zurück), bis eines der folgenden Ereignisse auftritt:

Eine der Managerroutinen der Serveranwendung ruft RpcMgmtStopServerListening auf.
Ein Client ruft eine vom Server bereitgestellte Remoteprozedur auf, die den Server anfordert , RpcMgmtStopServerListening aufzurufen.
Ein Client ruft RpcMgmtStopServerListening mit einem Bindungshandle an den Server auf.

Nachdem sie eine Anforderung zum Beenden des Lauschens empfangen hat, akzeptiert die RPC-Laufzeitbibliothek nicht mehr neue Remoteprozeduraufrufe für alle registrierten Schnittstellen. Die Ausführung von Anrufen kann ausgeführt werden, einschließlich Rückrufen. Nachdem alle Aufrufe abgeschlossen sind, kehrt RpcServerListen an den Aufrufer zurück.

Wenn der DontWait-Parameter über einen nonzero-Wert verfügt, kehrt RpcServerListen sofort nach der Verarbeitung aller der Funktion zugeordneten Anweisungen zum Server zurück. Sie können die RpcMgmtWaitServerListen-Funktion verwenden, um den Wartevorgang auszuführen, der normalerweise RpcServerListen zugeordnet ist.

Hinweis Die Microsoft RPC-Implementierung von RpcServerListen enthält zwei zusätzliche Parameter, die nicht in der DCE-Spezifikation enthalten sind: DontWait und MinimumCallThreads.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	rpcdce.h (include Rpc.h)
Bibliothek	Rpcrt4.lib
DLL	Rpcrt4.dll