Fonction RpcServerRegisterIfEx (rpcdce.h)

Article
03/04/2024

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

Syntaxe

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

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. Les paramètres MaxCalls s’appliquent uniquement à une interface d’écoute automatique et sont ignorés sur les interfaces qui ne sont pas à l’é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.

IfCallback

Fonction de rappel de sécurité ou NULL pour aucun rappel. Chaque interface inscrite peut avoir une fonction de rappel différente. Pour plus d’informations, consultez Remarques.

Valeur retournée

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 les effets de RpcServerRegisterIfEx sous-totalisent ceux de 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 RpcServerRegisterIfEx 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 de 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 à RpcServerListen et RpcMgmtStopServerListening n’affectent pas l’interface, ni un appel à RpcServerUnregisterIf avec IfSpec == 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 par client. N’oubliez pas que, par défaut, la sécurité est facultative ; l’heure d’exécution du serveur répartit les appels non sécurisés même si le serveur a appelé RpcServerRegisterAuthInfo. Si le serveur souhaite accepter uniquement les clients authentifiés, une fonction de rappel d’interface doit appeler la fonction RpcBindingInqAuthClient ou RpcGetAuthorizationContextForClient pour récupérer le niveau de sécurité ou tenter d’emprunter l’identité du client avec RpcImpersonateClient. Il peut également spécifier l’indicateur RPC_IF_ALLOW_SECURE_ONLY dans les indicateurs d’interface.

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 non authentifiés à 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 en cours, 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.

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 et 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 XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	rpcdce.h (inclure Rpc.h)
Bibliothèque	Rpcrt4.lib
DLL	Rpcrt4.dll