RpcServerRegisterIfEx-Funktion (rpcdce.h)

Artikel
03/01/2024

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

Syntax

RPC_STATUS RpcServerRegisterIfEx(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  RPC_IF_CALLBACK_FN *IfCallback
);

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. Die MaxCalls-Parameter gelten nur für eine Schnittstelle für automatisches Lauschen und werden auf 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.

IfCallback

Sicherheitsrückruffunktion oder NULL für keinen Rückruf. Jede registrierte Schnittstelle kann über eine andere Rückruffunktion verfügen. Weitere Informationen finden Sie unter 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 von RpcServerRegisterIfEx subsumieren die von RpcServerRegisterIf. Der Unterschied besteht in der Möglichkeit, eine Schnittstelle für automatisches Lauschen zu registrieren und eine Sicherheitsrückruffunktion anzugeben.

Der Serveranwendungscode ruft RpcServerRegisterIfEx 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 für diese Schnittstelle auf den Abschluss aller ausstehenden Aufrufe auf dieser Schnittstelle wartet. Aufrufe von RpcServerListen und RpcMgmtStopServerListening wirken sich weder auf die Schnittstelle aus, noch wird ein Aufruf von RpcServerUnregisterIf mit IfSpec == NULL ausgeführt. Dadurch kann eine DLL RPC-Schnittstellen registrieren oder aus der Registrierung entfernen, ohne den RPC-Status der Standard Anwendung zu ändern.

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

Wenn eine Serveranwendung eine Sicherheitsrückruffunktion für ihre Schnittstellen angibt, lehnt die RPC-Laufzeit automatisch nicht authentifizierte Aufrufe dieser 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.

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 aufrufen – pro Schnittstelle. Stellen Sie sicher, dass Ihre Rückruffunktion diese Möglichkeit verarbeiten kann.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	rpcdce.h (rpc.h einschließen)
Bibliothek	Rpcrt4.lib
DLL	Rpcrt4.dll