Fonction RpcServerRegisterIf2 (rpcdce.h)

Article
03/15/2023

La fonction RpcServerRegisterIf2 inscrit une interface avec la bibliothèque d’exécution RPC.

Syntaxe

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
);

Paramètres

IfSpec

Structure générée par MIDL indiquant l’interface à inscrire.

MgrTypeUuid

Pointeur vers un UUID de type à associer au paramètre MgrEpv . La spécification d’une valeur de paramètre null (ou d’un UUID nil) inscrit IfSpec avec un UUID de type nil.

MgrEpv

Vecteur de point d’entrée (EPV) des routines du gestionnaire. Pour utiliser l’EPV par défaut généré par MIDL, spécifiez une valeur null . Pour plus d’informations, consultez RPC_MGR_EPV.

Flags

Drapeaux. Pour obtenir la liste des valeurs d’indicateur, consultez Indicateurs d’inscription d’interface.

MaxCalls

Nombre maximal de demandes d’appel de procédure distante simultanées que le serveur peut accepter sur une interface d’écoute automatique . Le paramètre MaxCalls s’applique uniquement sur une interface d’écoute automatique et est ignoré sur les interfaces qui ne sont pas en écoute automatique. La bibliothèque d’exécution RPC fait tout son possible pour s’assurer que le serveur n’autorise pas plus de demandes d’appels simultanés que le nombre d’appels spécifié dans MaxCalls. Le nombre réel peut être supérieur et peut varier pour chaque séquence de protocole.

Les appels sur d’autres interfaces sont régis par la valeur du paramètre MaxCalls à l’échelle du processus spécifié dans l’appel de fonction RpcServerListen .

Si le nombre d’appels simultanés n’est pas un problème, vous pouvez obtenir des performances côté serveur légèrement meilleures en spécifiant la valeur par défaut à l’aide de RPC_C_LISTEN_MAX_CALLS_DEFAULT. Cela évite à l’environnement d’exécution RPC d’appliquer une restriction inutile.

MaxRpcSize

Taille maximale des blocs de données entrants, en octets. Ce paramètre peut être utilisé pour empêcher les attaques malveillantes par déni de service. Si le bloc de données d’un appel de procédure distante est supérieur à MaxRpcSize, la bibliothèque d’exécution RPC rejette l’appel et envoie une erreur RPC_S_ACCESS_DENIED au client. La spécification d’une valeur (int non signé) -1 pour ce paramètre supprime la limite de taille des blocs de données entrants. Ce paramètre n’a aucun effet sur les appels effectués sur le protocole ncalrpc .

IfCallbackFn

Fonction de rappel de sécurité ou NULL pour aucun rappel. Chaque interface inscrite peut avoir une fonction de rappel différente. Consultez la section Notes.

Valeur de retour

Retourne RPC_S_OK en cas de réussite.

Note Pour obtenir la liste des codes d’erreur valides, consultez Valeurs de retour RPC.

Remarques

Les paramètres et effets de la fonction RpcServerRegisterIf2 étendent ceux de la fonction RpcServerRegisterIf . La différence est la possibilité d’inscrire une interface d’écoute automatique et de spécifier une fonction de rappel de sécurité.

Le code de l’application serveur appelle RpcServerRegisterIf2 pour inscrire une interface. Pour inscrire une interface, le serveur fournit les informations suivantes :

Spécification d’interface
La spécification d’interface est une structure de données générée par le compilateur MIDL.
Type de gestionnaire UUID et EPV du gestionnaire
Le type de gestionnaire UUID et le gestionnaire EPV déterminent quelle routine de gestionnaire s’exécute lorsqu’un serveur reçoit une demande d’appel de procédure distante d’un client. Pour chaque implémentation d’une interface proposée par un serveur, elle doit inscrire un EPV de gestionnaire distinct.

Notez que lors de la spécification d’un UUID de type gestionnaire non nil, le serveur doit également appeler RpcObjectSetType pour inscrire des objets de ce type non nul.

La spécification des indicateurs RPC_IF_AUTOLISTEN marque l’interface en tant qu’interface d’écoute automatique . L’heure d’exécution commence à écouter les appels dès que l’interface est inscrite et cesse d’écouter lorsque l’interface n’est pas inscrite. Un appel à RpcServerUnregisterIf pour cette interface attend la fin de tous les appels en attente sur cette interface. Les appels aux fonctions RpcServerListen et RpcMgmtStopServerListening n’affectent pas l’interface, pas plus qu’un appel à la fonction RpcServerUnregisterIf avec IfSpec défini sur la valeur NULL. Cela permet à une DLL d’inscrire des interfaces RPC ou de les supprimer du Registre sans modifier l’état RPC de l’application main.

La spécification d’une fonction de rappel de sécurité permet à l’application serveur de restreindre l’accès à ses interfaces sur une base de client individuel. Autrement dit, par défaut, la sécurité est facultative ; l’exécution du serveur distribue les appels non sécurisés même si le serveur a appelé la fonction RpcServerRegisterAuthInfo . Si le serveur souhaite accepter uniquement les clients authentifiés, une fonction de rappel d’interface doit appeler la fonction RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient ou RpcServerInqCallAttributes pour récupérer le niveau de sécurité ou tenter d’emprunter l’identité du client avec la fonction RpcImpersonateClient . Il peut également spécifier l’indicateur RPC_IF_ALLOW_SECURE_ONLY dans les indicateurs d’interface pour rejeter les appels non authentifiés.

Lorsqu’une application serveur spécifie une fonction de rappel de sécurité pour ses interfaces, le temps d’exécution RPC rejette automatiquement les appels sans informations d’authentification pour cette interface. En outre, l’exécution enregistre les interfaces utilisées par chaque client. Lorsqu’un client effectue un RPC vers une interface qu’il n’a pas utilisée pendant la session de communication actuelle, la bibliothèque d’exécution RPC appelle la fonction de rappel de sécurité de l’interface. La spécification de RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH indicateur empêche le rejet automatique des clients non authentifiés. Notez que les appels sur la session de sécurité NULL peuvent avoir des informations d’authentification, même s’ils proviennent de clients anonymes. Par conséquent, l’existence d’un rappel ne suffit pas à elle seule pour empêcher les clients anonymes de se connecter. La fonction de rappel de sécurité doit case activée pour cela, ou l’indicateur RPC_IF_ALLOW_SECURE_ONLY doit être utilisé. RPC_IF_ALLOW_SECURE_ONLY rejette les appels de session null uniquement sur Windows XP et les versions ultérieures de Windows.

Pour obtenir la signature de la fonction de rappel, consultez RPC_IF_CALLBACK_FN.

La fonction de rappel doit retourner RPC_S_OK, si le client est autorisé à appeler des méthodes dans cette interface. Tout autre code de retour entraîne la réception par le client de l’exception RPC_S_ACCESS_DENIED.

Dans certains cas, le temps d’exécution RPC peut appeler la fonction de rappel de sécurité plusieurs fois par client, par interface. Assurez-vous que votre fonction de rappel peut gérer cette possibilité.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	rpcdce.h (inclure Rpc.h)
Bibliothèque	Rpcrt4.lib
DLL	Rpcrt4.dll