RPC_INTERFACE_TEMPLATEW-Struktur (rpcdce.h)

Artikel
08/25/2023

Die RPC_INTERFACE_TEMPLATE-Struktur definiert eine RPC-Schnittstellengruppenserverschnittstelle.

Syntax

typedef struct {
  unsigned long      Version;
  RPC_IF_HANDLE      IfSpec;
  UUID               *MgrTypeUuid;
  RPC_MGR_EPV        *MgrEpv;
  unsigned int       Flags;
  unsigned int       MaxCalls;
  unsigned int       MaxRpcSize;
  RPC_IF_CALLBACK_FN *IfCallback;
  UUID_VECTOR        *UuidVector;
  RPC_WSTR           Annotation;
  void               *SecurityDescriptor;
} RPC_INTERFACE_TEMPLATEW, *PRPC_INTERFACE_TEMPLATEW;

Member

Version

Dieses Feld ist reserviert und muss auf 0 festgelegt werden.

IfSpec

MIDL-generierte Struktur, die die zu registrierende Schnittstelle definiert.

MgrTypeUuid

Zeiger auf eine UUID , die MgrEpv zugeordnet werden soll. Null oder eine Null-UUID registriert IfSpec mit einer null-UUID.

MgrEpv

Zeiger auf eine RPC_MGR_EPV-Struktur , die den Einstiegspunktvektor (EPV) der Managerroutinen enthält. Wenn NULL, wird die von MIDL generierte Standard-EPV verwendet.

Flags

Flaggen. Eine Liste der Flagwerte finden Sie unter Schnittstellenregistrierungsflags. Schnittstellengruppenschnittstellen werden immer als automatisches Lauschen behandelt.

MaxCalls

Maximale Anzahl gleichzeitiger Remoteprozeduraufrufanforderungen, die der Server auf dieser Schnittstelle akzeptieren kann. 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 jedoch größer als MaxCalls sein und kann für jede Protokollsequenz variieren.

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

Wenn die Anzahl gleichzeitiger Aufrufe kein Problem ist, kann eine etwas bessere serverseitige Leistung erzielt werden, indem der Standardwert mithilfe von RPC_C_LISTEN_MAX_CALLS_DEFAULT angegeben wird. Dadurch wird die RPC-Laufzeitumgebung davon befreit, eine unnötige Einschränkung zu erzwingen.

MaxRpcSize

Maximale Größe eingehender Datenblöcke in Byte. MaxRpcSize 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. Die Angabe des Werts (unsigned int) –1 in MaxRpcSize entfernt den Grenzwert für die Größe der eingehenden Datenblöcke. Dieser Parameter hat keine Auswirkungen auf Aufrufe, die über das ncalrpc-Protokoll ausgeführt werden.

IfCallback

Ein Zeiger auf eine RPC_INTERFACE_GROUP_IDLE_CALLBACK_FN Sicherheitsrückruffunktion oder NULL für keinen Rückruf. Jede registrierte Schnittstelle kann über eine andere Rückruffunktion verfügen.

UuidVector

Zeiger auf einen Vektor von Objekt-UUIDs , die vom Server angeboten werden, um bei der RPC-Endpunktzuordnung registriert zu werden. Die Serveranwendung erstellt diesen Vektor. NULL gibt an, dass keine Objekt-UUIDs registriert werden müssen.

Annotation

Zeiger auf den Zeichenfolgenkommentar, der auf jedes produktübergreifende Element angewendet wird, das der lokalen Endpunktzuordnungsdatenbank hinzugefügt wird. Die Zeichenfolge kann bis zu 64 Zeichen lang sein, einschließlich des NULL-Endzeichens. Geben Sie einen NULL-Wert oder eine null-endende Zeichenfolge ("\0") an, wenn keine Anmerkungszeichenfolge vorhanden ist.

Die Anmerkungszeichenfolge wird von Anwendungen nur für Informationen verwendet. RPC verwendet diese Zeichenfolge nicht, um zu bestimmen, mit welchem Server instance ein Client kommuniziert, oder um Elemente in der Endpunktzuordnungsdatenbank aufzulisten.

SecurityDescriptor

Optionaler Sicherheitsdeskriptor, der beschreibt, welche Clients auf die Schnittstelle zugreifen können.

Hinweise

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.

Alle Schnittstellengruppenschnittstellen werden als automatisches Lauschen behandelt. Die Runtime beginnt mit dem Lauschen auf Aufrufe, sobald die Schnittstellengruppe aktiviert ist. Aufrufe von RpcServerListen und RpcMgmtStopServerListening wirken sich weder auf die Schnittstelle aus, noch ein Aufruf von RpcServerUnregisterIf mit IfSpec , der auf NULL festgelegt ist.

Wenn Sie eine Sicherheitsrückruffunktion in IfCallback angeben, kann die Serveranwendung den Zugriff auf ihre Schnittstellen auf einzelner Clientbasis einschränken. Das heißt, die Sicherheit ist standardmäßig optional. 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 RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient oder RpcServerInqCallAttributes 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 Flags angeben, um nicht authentifizierte Aufrufe abzulehnen.

Wenn eine Serveranwendung eine Sicherheitsrückruffunktion für ihre Schnittstellen in IfCallback angibt, lehnt die RPC-Laufzeit Aufrufe für diese Schnittstelle ohne Authentifizierungsinformationen automatisch 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. Wenn Sie RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH in Flags angeben, wird die automatische Ablehnung nicht authentifizierter Clients verhindert. Beachten Sie, dass Aufrufe der NULL-Sicherheitssitzung Authentifizierungsinformationen enthalten können, auch wenn sie von anonymen Clients stammen. Daher reicht das Vorhandensein eines Rückrufs allein nicht aus, um zu verhindern, dass anonyme Clients eine Verbindung herstellen; Entweder muss die Sicherheitsrückruffunktion dies überprüfen, oder das flag RPC_IF_ALLOW_SECURE_ONLY muss 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 in IfCallback 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. Die Rückruffunktion muss diese Möglichkeit verarbeiten können.

Hinweis

Der rpcdce.h-Header definiert RPC_INTERFACE_TEMPLATE als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Kopfzeile	rpcdce.h (rpc.h einschließen)