RpcServerRegisterIf2-Funktion (rpcdce.h)

Artikel
03/06/2024

Die RpcServerRegisterIf2-Funktion registriert eine Schnittstelle bei der RPC-Laufzeitbibliothek.

Syntax

RPC_STATUS RpcServerRegisterIf2(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  unsigned int       MaxRpcSize,
  RPC_IF_CALLBACK_FN *IfCallbackFn
);

Parameter

IfSpec

VON MIDL generierte Struktur, die die zu registrierende Schnittstelle angibt.

MgrTypeUuid

Zeiger auf eine Typ-UUID , die dem MgrEpv-Parameter zugeordnet werden soll. Wenn Sie einen NULL-Parameterwert (oder eine Null-UUID) angeben, wird IfSpec mit einer UUID vom Typ nil registriert.

MgrEpv

Einstiegspunktvektor (EPV) von Managerroutinen. Um das von MIDL generierte Standard-EPV zu verwenden, geben Sie einen NULL-Wert an. Weitere Informationen finden Sie unter RPC_MGR_EPV.

Flags

Flaggen. Eine Liste der Flagwerte finden Sie unter Schnittstellenregistrierungsflags.

MaxCalls

Maximale Anzahl gleichzeitiger Remoteprozeduraufrufanforderungen, die der Server auf einer Schnittstelle für automatisches Lauschen akzeptieren kann. Der MaxCalls-Parameter gilt nur für eine Schnittstelle für automatisches Lauschen und wird für Schnittstellen ignoriert, die nicht automatisch lauschen. Die RPC-Laufzeitbibliothek bemüht sich nach besten Kräften, sicherzustellen, dass der Server nicht mehr gleichzeitige Anrufanforderungen zulässt als die in MaxCalls angegebene Anzahl von Anrufen. Die tatsächliche Zahl kann größer sein und je nach Protokollsequenz variieren.

Aufrufe auf anderen Schnittstellen werden durch den Wert des prozessweiten MaxCalls-Parameters gesteuert, der im RpcServerListen-Funktionsaufruf angegeben ist.

Wenn die Anzahl gleichzeitiger Aufrufe kein Problem ist, können Sie eine etwas bessere serverseitige Leistung erzielen, indem Sie den Standardwert mithilfe von RPC_C_LISTEN_MAX_CALLS_DEFAULT angeben. Dadurch wird die RPC-Laufzeitumgebung davon befreit, eine unnötige Einschränkung zu erzwingen.

MaxRpcSize

Maximale Größe der eingehenden Datenblöcke in Bytes. Dieser Parameter kann verwendet werden, um böswillige Denial-of-Service-Angriffe zu verhindern. Wenn der Datenblock eines Remoteprozeduraufrufs größer als MaxRpcSize ist, lehnt die RPC-Laufzeitbibliothek den Aufruf ab und sendet einen RPC_S_ACCESS_DENIED Fehler an den Client. Durch Angabe des Werts (unsigned int) –1 für diesen Parameter wird der Grenzwert für die Größe eingehender Datenblöcke entfernt. Dieser Parameter hat keine Auswirkungen auf Aufrufe, die über das ncalrpc-Protokoll ausgeführt werden.

IfCallbackFn

Sicherheitsrückruffunktion oder NULL für keinen Rückruf. Jede registrierte Schnittstelle kann über eine andere Rückruffunktion verfügen. Siehe Hinweise.

Rückgabewert

Gibt bei Erfolg RPC_S_OK zurück.

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

Hinweise

Die Parameter und Auswirkungen der RpcServerRegisterIf2-Funktion erweitern die der RpcServerRegisterIf-Funktion . Der Unterschied besteht in der Möglichkeit, eine Schnittstelle für automatisches Lauschen zu registrieren und eine Sicherheitsrückruffunktion anzugeben.

Der Serveranwendungscode ruft RpcServerRegisterIf2 auf, um eine Schnittstelle zu registrieren. Um eine Schnittstelle zu registrieren, stellt der Server die folgenden Informationen bereit:

Schnittstellenspezifikation
Die Schnittstellenspezifikation ist eine Datenstruktur, die vom MIDL-Compiler generiert wird.
Managertyp UUID und Manager EPV
Der Managertyp UUID und die Manager-EPV bestimmen, welche Managerroutine ausgeführt wird, wenn ein Server eine Remoteprozeduraufrufanforderung von einem Client empfängt. Für jede Implementierung einer Schnittstelle, die von einem Server angeboten wird, muss ein separater Manager-EPV registriert werden.

Beachten Sie, dass der Server beim Angeben einer UUID vom Managertyp "non-nil" auch RpcObjectSetType aufrufen muss, um Objekte dieses Nicht-Null-Typs zu registrieren.

Wenn Sie die RPC_IF_AUTOLISTEN-Flags angeben, wird die Schnittstelle als Schnittstelle für automatisches Lauschen markiert. Die Laufzeit beginnt mit dem Lauschen auf Aufrufe, sobald die Schnittstelle registriert ist, und beendet die Überwachung, wenn die Registrierung der Schnittstelle aufgehoben wird. Ein Aufruf von RpcServerUnregisterWenn diese Schnittstelle auf den Abschluss aller ausstehenden Aufrufe auf dieser Schnittstelle wartet. Aufrufe der Funktionen RpcServerListen und RpcMgmtStopServerListening wirken sich weder auf die Schnittstelle aus, noch ein Aufruf der RpcServerUnregisterIf-Funktion , bei der IfSpec auf den Wert NULL festgelegt ist. Dadurch kann eine DLL RPC-Schnittstellen registrieren oder aus der Registrierung entfernen, ohne den RPC-Status der Standard Anwendung zu ändern.

Die Angabe einer Sicherheitsrückruffunktion ermöglicht es der Serveranwendung, den Zugriff auf ihre Schnittstellen auf einzelner Clientbasis einzuschränken. Das heißt, die Sicherheit ist standardmäßig optional. Die Serverlaufzeit sendet ungesicherte Aufrufe, auch wenn der Server die RpcServerRegisterAuthInfo-Funktion aufgerufen hat. Wenn der Server nur authentifizierte Clients akzeptieren möchte, muss eine Schnittstellenrückruffunktion die Funktionen RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient oder RpcServerInqCallAttributes aufrufen, um die Sicherheitsstufe abzurufen, oder versuchen, die Identität des Clients mit der RpcImpersonateClient-Funktion anzunehmen. Es kann auch das RPC_IF_ALLOW_SECURE_ONLY-Flag in den Schnittstellenflags angeben, um nicht authentifizierte Aufrufe abzulehnen.

Wenn eine Serveranwendung eine Sicherheitsrückruffunktion für ihre Schnittstellen angibt, lehnt die RPC-Laufzeit Aufrufe automatisch ohne Authentifizierungsinformationen für diese Schnittstelle ab. Darüber hinaus zeichnet die Laufzeit die Schnittstellen auf, die jeder Client verwendet hat. Wenn ein Client einen RPC zu einer Schnittstelle macht, die er während der aktuellen Kommunikationssitzung nicht verwendet hat, ruft die RPC-Laufzeitbibliothek die Sicherheitsrückruffunktion der Schnittstelle auf. Die Angabe RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH Flags verhindert die automatische Ablehnung nicht authentifizierter Clients. Beachten Sie, dass Aufrufe der sogenannten NULL-Sicherheitssitzung Authentifizierungsinformationen enthalten können, obwohl sie von anonymen Clients stammen. Daher reicht das Vorhandensein eines Rückrufs allein nicht aus, um anonyme Clients daran zu hindern, eine Verbindung herzustellen. Dies muss entweder von der Sicherheitsrückruffunktion überprüft werden, oder es muss das flag RPC_IF_ALLOW_SECURE_ONLY verwendet werden. RPC_IF_ALLOW_SECURE_ONLY lehnt NULL-Sitzungsaufrufe nur unter Windows XP und höheren Versionen von Windows ab.

Die Signatur für die Rückruffunktion finden Sie unter RPC_IF_CALLBACK_FN.

Die Rückruffunktion sollte RPC_S_OK zurückgeben, wenn der Client Methoden in dieser Schnittstelle aufrufen darf. Jeder andere Rückgabecode bewirkt, dass der Client die Ausnahme RPC_S_ACCESS_DENIED empfängt.

In einigen Fällen kann die RPC-Laufzeit die Sicherheitsrückruffunktion mehrmals pro Client und schnittstelle aufrufen. Stellen Sie sicher, dass Ihre Rückruffunktion diese Möglichkeit verarbeiten kann.

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 (rpc.h einschließen)
Bibliothek	Rpcrt4.lib
DLL	Rpcrt4.dll