RpcServerListen, fonction (rpcdce.h)

Article
08/25/2023

La fonction RpcServerListen indique à la bibliothèque d’exécution RPC d’écouter les appels de procédure distante. Cette fonction n’affecte pas les interfaces d’écoute automatique ; utilisez RpcServerRegisterIfEx si vous avez besoin de cette fonctionnalité.

Syntaxe

RPC_STATUS RpcServerListen(
  unsigned int MinimumCallThreads,
  unsigned int MaxCalls,
  unsigned int DontWait
);

Paramètres

MinimumCallThreads

Indicateur de l’heure d’exécution RPC qui spécifie le nombre minimal de threads d’appel qui doivent être créés et gérés sur le serveur donné. Cette valeur n’est qu’un indicateur et est interprétée différemment dans différentes versions de Windows. Dans Windows XP, cette valeur correspond au nombre de threads créés précédemment dans chaque pool de threads créé par l’exécution rpc. Une application doit en spécifier un pour ce paramètre et différer les décisions de création de threads au moment de l’exécution RPC.

MaxCalls

Nombre maximal recommandé d’appels de procédure distante simultanés que le serveur peut exécuter. Pour permettre des performances efficaces, les bibliothèques d’exécution RPC interprètent le paramètre MaxCalls comme une limite suggérée plutôt que comme une limite supérieure absolue.

Utilisez RPC_C_LISTEN_MAX_CALLS_DEFAULT pour spécifier la valeur par défaut.

DontWait

Indicateur contrôlant le retour à partir de RpcServerListen. Une valeur différente de zéro indique que RpcServerListen doit retourner immédiatement après la fin du traitement de la fonction. La valeur zéro indique que RpcServerListen ne doit pas être retourné tant que la fonction RpcMgmtStopServerListening n’a pas été appelée et que tous les appels distants ne sont pas terminés.

Valeur retournée

Valeur	Signification
RPC_S_OK	L’appel a réussi.
RPC_S_ALREADY_LISTENING	Le serveur est déjà à l’écoute.
RPC_S_NO_PROTSEQS_REGISTERED	Aucune séquence de protocole n’est inscrite.
RPC_S_MAX_CALLS_TOO_SMALL	La valeur maximale des appels est trop petite.

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

Remarques

Un serveur appelle RpcServerListen quand le serveur est prêt à traiter les appels de procédure distante. RPC permet à un serveur de traiter simultanément plusieurs appels. Le paramètre MaxCalls recommande le nombre maximal d’appels de procédure distante simultanés que le serveur doit exécuter.

La valeur MaxCalls ne doit pas être égale à zéro et doit être supérieure à MinimumCallThreads. Les valeurs supérieures à 0x7FFFFFFF sont définies sur 0x7FFFFFFF sans préavis.

Windows XP/2000 : La définition du paramètre MaxCalls sur RPC_C_LISTEN_MAX_CALLS_DEFAULT supprime la limite des appels de procédure distante simultanés, au lieu de la définir sur la valeur définie par la constante 1234. La suppression de la limite du nombre maximal d’appels simultanés autorise autant d’appels de procédure à distance simultanés que l’ordinateur peut gérer. Ce comportement permet d’augmenter l’efficacité au moment de l’exécution rpc.

Une application serveur est responsable du contrôle d’accès concurrentiel entre les routines du gestionnaire de serveur, car chaque routine s’exécute dans un thread distinct.

Lorsque le paramètre DontWait a la valeur zéro, la bibliothèque d’exécution RPC continue d’écouter les appels de procédure distante (autrement dit, la routine ne retourne pas à l’application serveur) jusqu’à ce que l’un des événements suivants se produise :

L’une des routines de gestionnaire de l’application serveur appelle RpcMgmtStopServerListening.
Un client appelle une procédure distante fournie par le serveur qui indique au serveur d’appeler RpcMgmtStopServerListening.
Un client appelle RpcMgmtStopServerListening avec un handle de liaison au serveur.

Après avoir reçu une demande d’arrêt d’écoute, la bibliothèque d’exécution RPC cesse d’accepter de nouveaux appels de procédure distante pour toutes les interfaces inscrites. L’exécution des appels est autorisée, y compris les rappels. Une fois tous les appels terminés, RpcServerListen retourne à l’appelant.

Lorsque le paramètre DontWait a une valeur différente de zéro, RpcServerListen retourne au serveur immédiatement après avoir traité toutes les instructions associées à la fonction. Vous pouvez utiliser la fonction RpcMgmtWaitServerListen pour effectuer l’opération d’attente généralement associée à RpcServerListen.

Note L’implémentation Microsoft RPC de RpcServerListen inclut deux paramètres supplémentaires qui n’apparaissent pas dans la spécification DCE : DontWait et MinimumCallThreads.

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