RpcServerSubscribeForNotification, fonction (rpcasync.h)
La fonction RpcServerSubscribeForNotification abonne le serveur aux notifications RPC.
Syntaxe
RPC_STATUS RpcServerSubscribeForNotification(
[in] RPC_BINDING_HANDLE Binding,
[in] RPC_NOTIFICATIONS Notification,
[in] RPC_NOTIFICATION_TYPES NotificationType,
[in] RPC_ASYNC_NOTIFICATION_INFO *NotificationInfo
);
Paramètres
[in] Binding
RPC_BINDING_HANDLE structure qui contient le handle de liaison pour l’appel actuel. Si cette fonction est appelée sur le même thread sur lequel RPC a distribué un appel, ce paramètre peut être défini sur NULL ; sinon, un handle de liaison explicite doit être passé dans ce paramètre.
[in] Notification
Combinaison au niveau du bit des valeurs d’énumération RPC_NOTIFICATIONS qui spécifie le type de notification demandé à RPC par le serveur.
Windows Vista : Actuellement, seuls RpcNotificationClientDisconnect et RpcNotificationCallCancel sont pris en charge. Si une autre valeur est spécifiée pour ce paramètre, le code d’erreur RPC_S_CANNOT_SUPPORT est retourné.
[in] NotificationType
RPC_NOTIFICATION_TYPES valeur d’énumération qui spécifie la méthode par laquelle RPC informera le serveur.
Windows Vista : RpcNotificationTypeNone n’est pas pris en charge. Si cette valeur est spécifiée, le code d’erreur RPC_S_INVALID_ARG est retourné.
[in] NotificationInfo
Pointeur vers une union RPC_ASYNC_NOTIFICATION_INFO qui contient les informations spécifiques nécessaires pour que RPC contacte le serveur pour la notification. Les données contenues dans cette union sont spécifiques à la méthode passée au paramètre NotificationType .
Si la méthode RpcNotificationTypeCallback est spécifiée dans NotificationTypes, le membre NotificationRoutine de la branche correspondante de l’union est défini sur le handle de liaison pour les appels synchrones et le handle asynchrone pour les appels asynchrones.
RPC effectue une copie de ce paramètre lors d’un appel réussi à cette fonction. L’appelant peut libérer ou mettre à jour ce paramètre lorsque l’API est retournée.
Valeur retournée
Cette fonction retourne RPC_S_OK en cas de réussite ; sinon, un code d’erreur RPC_S_* est retourné.
Remarques
Si l’appelant spécifie un type de notification autre que RpcNotificationTypeEvent, il peut s’abonner aux notifications RpcNotificationClientDisconnect et RpcNotificationCallCancel avec un seul appel. Pour les événements, deux appels distincts à cette API sont requis.
L’application serveur doit se désabonner pour recevoir une notification avant la fin de l’appel RPC. Si l’appel RPC est synchrone, il est terminé lorsque le serveur envoie une valeur de retour à RPC. Si l’appel RPC est asynchrone, il est terminé lorsque le serveur appelle RpcAsyncCompleteCall ou RpcAsyncAbortCall, ou lève une exception à partir de la routine du gestionnaire. Si le serveur ne parvient pas à se désabonner des notifications d’appel status de modification, les résultats ne sont pas définis et le serveur peut se bloquer ultérieurement. Notez que l’abonnement s’applique à un seul appel RPC. Si l’application serveur doit surveiller plusieurs appels, elle doit s’abonner à chaque appel spécifiquement.
L’application serveur peut s’attendre à ce qu’elle ne soit pas signalée pour les notifications auxquelles elle n’est pas abonnée. S’il s’est abonné à plusieurs notifications, chaque notification est communiquée à la méthode d’achèvement si la méthode d’achèvement sélectionnée le permet. Si elle n’autorise pas la communication des notifications, l’application serveur peut appeler les API du serveur RPC pour tester si le client a annulé ou déconnecté. Le tableau ci-dessous indique comment le type de notification (annulation d’appel ou déconnexion du client) est communiqué à chaque méthode de notification :
| Méthode de notification | Type d’événement/notification |
|---|---|
| RpcNotificationTypeNone | Non autorisé pour l’abonnement. |
| RpcNotificationTypeEvent | Le type de notification n’est pas disponible. |
| RpcNotificationTypeApc | Le type de notification se trouve dans le paramètre Event de la fonction APC. |
| RpcNotificationTypeIoc | Le type de notification n’est pas disponible. |
| RpcNotificationTypeCallback | Le type de notification se trouve dans le paramètre Event de la fonction de rappel. |
Notez que la table n’implique pas si un appelant peut s’abonner ou non aux notifications à l’aide de la méthode de notification donnée ; au lieu de cela, il indique simplement les informations que l’appelant peut obtenir lors de la réception de la notification, telles que le type de notification.
L’appelant doit se synchroniser entre RpcServerSubscribeForNotification et RpcServerUnsubscribeForNotification sur le même handle de liaison. Si elles sont appelées simultanément, les résultats ne sont pas définis et peuvent entraîner des notifications perdues, des notifications supplémentaires, un nombre de notifications incorrect, des incidents de traitement, une altération des données et des fuites de mémoire. Le même problème s’applique aux threads appelant RpcServerSubscribeForNotification sur le même handle de liaison.
L’appel de RpcServerSubscribeForNotification et RpcServerUnsubscribeForNotification sur le même handle de liaison est thread-safe. Pour les notifications actuelles, RPC n’avertit le serveur qu’une seule fois par appel.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista, Windows XP avec SP2 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008, Windows Server 2003 avec SP1 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | rpcasync.h (inclure Rpc.h) |
| Bibliothèque | Rpcrt4.lib |
| DLL | Rpcrt4.dll |