classe <SI-Namespace>::proxy::events::<Event>

Utilisation

La fonction SetReceiveHandler sert, côté client dans le scope <SI-Namespace>::proxy::events::<Event>, à enregistrer un gestionnaire de callback pour les événements entrants [SWS_CM_00181]. Un ara::com::EventReceiveHandler est transmis en paramètre, défini comme une fonction sans paramètre et appelé par le Communication Management lors de l'arrivée d'un événement [SWS_CM_00181]. La fonction ne possède aucune valeur de retour (void) [SWS_CM_00181].

Traitement des erreurs et comportement face aux exceptions

L'opération est spécifiée comme noexcept et sûre vis-à-vis des exceptions (exception safe) [SWS_CM_00181]. Si le callable transmis n'existe pas ou vaut null, cela est considéré comme un InvalidHandlerViolation [SWS_CM_00181].

Contexte d'exécution et interaction

Au sein des interfaces de proxy, SetReceiveHandler fait partie des mécanismes fondamentaux aux côtés d'appels tels que UnsetReceiveHandler() et GetNewSamples() ARAComAPI §5.3.1 « Proxy Class API’s ». Si le gestionnaire doit être exécuté dans un contexte donné, la surcharge de modèle avec ExecutorT est disponible [SWS_CM_11356] (ARAComAPI p. 10).

La même approche de notification est également utilisée pour les déclencheurs via [SWS_CM_00250] (avec contexte : [SWS_CM_00352]) ainsi que pour les champs via [SWS_CM_11605] (avec contexte : [SWS_CM_11611]) ARAComAPI §4.2 « Means of Communication ».

La méthode SetSubscriptionStateChangeHandler dans l’espace de noms proxy::events::<Event> enregistre une fonction de rappel que le Communication Management appelle dès que l’état ara::com::SubscriptionState de l’événement change ([SWS_CM_00333]). La fonction est déclarée comme noexcept et considérée comme sûre vis-à-vis des exceptions ([SWS_CM_00333]).

Utilisation et sémantique asynchrone

Les appels de Subscribe() fonctionnent par principe de manière asynchrone ; une souscription réussie ne doit être considérée comme terminée que lorsque le gestionnaire enregistré ou GetSubscriptionState() renvoie l’état kSubscribed ([SWS_CM_12006]). Le gestionnaire est appelé avec kSubscriptionPending lorsque la souscription ne prend pas effet immédiatement (par exemple en raison de latences de protocole de bus) ou lorsque l’instance de serveur n’est pas accessible en raison de redémarrages ou d’erreurs réseau ([SWS_CM_00313]). L’annulation de l’enregistrement du gestionnaire s’effectue via UnsetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 « Proxy Class API’s »).

Gestion des erreurs et conditions limites

Si aucun objet de rappel valide n’est transmis ou si celui-ci est nul, le cas d’erreur InvalidHandlerViolation se présente ([SWS_CM_00333]). Concernant l’ordre des appels, il conviendrait d’enregistrer judicieusement le gestionnaire avant Subscribe() afin de capturer de manière fiable les premières transitions d’état. Question Q-3b9c25c6aa2d0a0f (ouverte)

Interaction et variantes

Pour l’exécution du gestionnaire dans un contexte de thread ou de travail prédéfini, la variante template surchargée avec le paramètre ExecutorT est disponible ([SWS_CM_11354]). Des interfaces parallèles existent pour les déclencheurs de Proxy ([SWS_CM_01107]), les champs de Proxy ([SWS_CM_11607]) ainsi qu’au niveau du Skeleton ([SWS_CM_12008]).

La fonction membre modèle SetSubscriptionStateChangeHandler sert, dans la portée proxy::events::<Event>, à enregistrer une fonction de rappel pour les changements d’état de la souscription (ara::com::SubscriptionState) ([SWS_CM_11354], AP EXP ARAComAPI §5.3.1 « Proxy Class API’s »). Contrairement à la fonction de base [SWS_CM_00333], le gestionnaire n’est pas exécuté dans le contexte interne de Communication Management, mais transmis via le paramètre template ExecutorT à un contexte d’exécution fourni executor ([SWS_CM_11360], AP EXP ARAComAPI §1.0 « SetSubscriptionState with ExecutorT »).

Paramètres et valeurs de retour

• handler : le callable à appeler, qui est notifié lors d’une modification du ara::com::SubscriptionState de l’événement ([SWS_CM_00333]).
• executor : le contexte d’exécution selon [SWS_CM_11360], dans lequel le gestionnaire doit être traité.
• Valeur de retour : la fonction ne possède pas de valeur de retour (void).

Traitement des erreurs et exécution

La fonction est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe). Si le callable handler transmis n’existe pas ou vaut null, un InvalidHandlerViolation est déclenché ([SWS_CM_11354]).

Interaction

Le modèle de surveillance d’état liée à un contexte avec ExecutorT existe de manière analogue pour les déclencheurs de Proxy ([SWS_CM_01106]) ainsi que les champs de Proxy ([SWS_CM_11608]). Si aucune externalisation vers un contexte spécifique n’est requise, la variante [SWS_CM_00333] est disponible.

La fonction membre SetTransportFaultConditionHandler sert, sur un événement de Proxy ([SWS_CM_00099]), à enregistrer une fonction de rappel de type ara::com::e2e::TransportFaultConditionHandler. Les erreurs de transmission détectées au niveau de la couche de transport du binding de communication sont signalées via ce gestionnaire ([SWS_CM_00211]).

Utilisation et sémantique :

• Appel et paramètres : la fonction reçoit l’objet gestionnaire appelable handler et ne renvoie aucune valeur de retour ([SWS_CM_00099]). La signature de la méthode est déclarée comme noexcept ([SWS_CM_00099]).
• États d’erreur transmis : le gestionnaire enregistré signale, en cas d’erreur, des valeurs de l’enum ara::com::e2e::TransportFaultCondition, telles que kSampleRejected en cas d’échantillons rejetés sur le canal de transport sous-jacent ([SWS_CM_00211]).
• Contexte d’exécution : pour les exécutions asynchrones, une surcharge de modèle avec un objet exécuteur ExecutorT&& executor supplémentaire est disponible ([SWS_CM_00100]).

Traitement des erreurs et conditions aux limites :

• Sécurité vis-à-vis des exceptions : la fonction est considérée comme sûre vis-à-vis des exceptions (exception safe) ([SWS_CM_00099]).
• Violations : si le callable transmis n’existe pas ou vaut null, il y a violation sous la forme d’une InvalidHandlerViolation ([SWS_CM_00099]).
• Interaction : des interfaces équivalentes pour l’enregistrement d’un TransportFaultConditionHandler existent également pour les déclencheurs ([SWS_CM_00106]), les notificateurs de champs ([SWS_CM_00109]) et les méthodes de Skeleton ([SWS_CM_00093]).

La fonction template SetTransportFaultConditionHandler enregistre sur un événement de Proxy un gestionnaire spécifique à l’application de type ara::com::e2e::TransportFaultConditionHandler conjointement avec un exécuteur personnalisé ([SWS_CM_00100]). Elle constitue la surcharge avec contexte d’exécution de la fonction de base comportant moins de paramètres ([SWS_CM_00099]).

Utilisation et paramètres : la méthode est appelée sur des instances de <SI-Namespace>::proxy::events::<Event> et ne renvoie aucune valeur (void) ([SWS_CM_00100]). Elle prend en charge le gestionnaire à appeler (handler) et reçoit un objet exécuteur (executor en tant que référence universelle ExecutorT&&), dans le contexte duquel toute exécution asynchrone du gestionnaire est initiée ([SWS_CM_00100]). La signature de fonction est déclarée avec noexcept ([SWS_CM_00100]).

Traitement des erreurs : l’opération est spécifiée comme exception safe ([SWS_CM_00100]). Si un callable invalide ou inexistant est transmis (null), il se produit une violation sous la forme de InvalidHandlerViolation ([SWS_CM_00100]). Les erreurs de transport détectées sont signalées via le gestionnaire enregistré, comme par exemple TransportFaultCondition::kSampleRejected lors du rejet d’échantillons de données entrants par l’entité de transport sous-jacente ([SWS_CM_00211]).

Interaction : tandis que [SWS_CM_00099] effectue l’enregistrement sans exécuteur explicite, cette surcharge permet l’exécution dans le contexte de thread ou de tâche souhaité ([SWS_CM_00100]). Des surcharges analogues avec exécuteur sont disponibles pour les méthodes de Skeleton ([SWS_CM_00094]) et les champs de Skeleton ([SWS_CM_00097]) ainsi que, du côté Proxy, pour les déclencheurs ([SWS_CM_00107]) et les notificateurs de champ ([SWS_CM_00110]).

Utilisation

La méthode Subscribe enregistre l'élément proxy pour la réception d'événements de service conformément à [SWS_CM_00141]. L'appel est de nature asynchrone : le retour de la fonction confirme seulement que le Communication Management a accepté la demande d'enregistrement (AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 « Monitoring Event Subscription »). Avec le paramètre obligatoire maxSampleCount, l'application indique de manière ferme le nombre maximal d'échantillons d'événement qu'elle conservera simultanément, initialisant ainsi le tampon de réception local (AUTOSAR_AP_EXP_ARAComAPI p. 40).

Gestion des erreurs et conditions limites

Si l'événement se trouve déjà dans l'état kSubscribed ou kSubscriptionPending lors de l'appel et que la valeur transmise maxSampleCount concorde avec la souscription active, la méthode retourne avec succès sans exécuter d'action ([SWS_CM_00141]). En revanche, si la taille du cache diverge lors d'une nouvelle souscription, l'appel échoue et renvoie dans ara::core::Result le code d'erreur ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_00141]). En cas d'autorisations d'accès manquantes, l'appel est refusé (InsufficientPermissionsViolation selon [SWS_CM_00141]). La signature est déclarée comme noexcept et est considérée comme sûre vis-à-vis des exceptions.

Interaction

La capacité de cache réservée limite la réception ultérieure de données via GetNewSamples ([SWS_CM_00701]) ; si l'application conserve davantage de pointeurs intelligents que spécifié, l'erreur ComErrc::kMaxSamplesExceeded est déclenchée ([SWS_CM_10432]). Alors que les événements de champ sont abonnés de manière identique via maxSampleCount ([SWS_CM_11601]), les événements de déclencheur purs ne requièrent aucune indication de taille de tampon ([SWS_CM_00723]).

Utilisation

La fonction UnsetReceiveHandler fait partie du wrapper d'événement dans la portée <SI-Namespace>::proxy::events::<Event> et est incluse via le fichier d'en-tête #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00183]). Elle ne prend aucun paramètre d'entrée et ne possède aucune valeur de retour (void). L'appel supprime un gestionnaire de réception spécifique à l'application préalablement enregistré avec SetReceiveHandler pour un événement de service (EXP ARAComAPI §5.3.2 « RadarService Proxy Class Example »). Ainsi, l'application réceptrice peut à tout moment basculer entre une réception pilotée par les événements (« event-driven ») et un mode d'interrogation actif (« polling style ») au moyen de GetNewSamples() (EXP ARAComAPI §5.3.2 « RadarService Proxy Class Example »).

Gestion des erreurs

La méthode est déclarée avec noexcept et possède la propriété exception safe ([SWS_CM_00183]). Elle ne lève aucune exception au moment de l'exécution et ne renvoie aucun code d'erreur spécifique.

Concurrence et liaison

Tandis que pour le gestionnaire de callback enregistré, il est stipulé qu'il n'a pas besoin d'être réentrant car le Communication Management sérialise les appels (EXP ARAComAPI §5.3.2 « RadarService Proxy Class Example »), UnsetReceiveHandler désactive le déclencheur d'événement pour la réception de notifications ultérieures ([SWS_CM_00183]). Dans le contexte du binding DDS, la méthode UnsetReceiveHandler() selon [SWS_CM_11141] est mappée sur le DataReader associé conformément à la spécification [SWS_CM_11026].

Interaction

La fonction constitue le pendant direct de l'enregistrement via SetReceiveHandler ([SWS_CM_11140], EXP ARAComAPI §5.3.1 « Proxy Class API’s »). Des fonctions apparentées se trouvent dans d'autres interfaces de proxy :

• Pour les champs, il existe une fonction de même nom UnsetReceiveHandler dans la portée <SI-Namespace>::proxy::fields::<Field>, qui est également définie comme noexcept et exception safe ([SWS_CM_11606]).
• Pour les triggers, UnsetReceiveHandler est disponible dans la portée <SI-Namespace>::proxy::triggers::<Trigger>, mais est déclaré différemment en tant que not exception safe ([SWS_CM_11614]).

Utilisation

La fonction membre UnsetSubscriptionStateChangeHandler sert à réinitialiser et à désenregistrer un gestionnaire de callback précédemment défini pour les changements de l'état d'abonnement (ara::com::SubscriptionState) côté proxy ([SWS_CM_00334], EXP ARAComAPI §1.0). La fonction fait partie intégrante de l'interface d'événement et se trouve dans l'espace de noms spécifique à l'application sous proxy::events ([SWS_CM_00334], SWS CommunicationManagement §8.3.2.2.4.5 « UnsetSubscriptionStateChangeHandler »). Pour son utilisation, le fichier d'en-tête de proxy généré <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h est inclus ([SWS_CM_00334]). L'appel s'effectue de manière synchrone, ne prend aucun paramètre et ne fournit aucune valeur de retour ([SWS_CM_00334]).

Gestion des erreurs

Conformément à la spécification, la fonction est déclarée avec l'identifiant noexcept et classée comme sûre vis-à-vis des exceptions (« exception safe ») ([SWS_CM_00334]). Elle ne déclenche aucune exception C++ en cas d'erreur et ne renvoie aucun code d'erreur ([SWS_CM_00334]).

Concurrence et interaction

La fonction est associée à d'autres API de proxy pour la recherche de services et la gestion des événements telles que Subscribe(), Unsubscribe(), GetSubscriptionState() et SetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 « Proxy Class API’s »). Comme interprétation, aucune autre notification ne devrait être déclenchée via le gestionnaire désenregistré après l'appel. Question Q-6173c01e6ca93876 (ouverte) Des équivalents symétriques pour réinitialiser les gestionnaires de changements d'état sont définis dans la spécification pour les fields de proxy ([SWS_CM_11609], SWS CommunicationManagement §8.3.3.2.4.5 « UnsetSubscriptionStateChangeHandler ») et les déclencheurs ([SWS_CM_01108]), ainsi que côté fournisseur de service (squelette) pour les événements ([SWS_CM_12010]) et les déclencheurs ([SWS_CM_01112]).

Utilisation

La fonction UnsetTransportFaultConditionHandler dans l'espace de noms <SI-Namespace>::proxy::events::<Event> sert à désenregistrer un ara::com::e2e::TransportFaultConditionHandler précédemment enregistré pour un événement de proxy concret [SWS_CM_00105]. La déclaration de la fonction est fournie par le fichier d'en-tête <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.1.3 « UnsetTransportFaultConditionHandler ». L'appel ne prend aucun paramètre et ne renvoie aucune valeur de retour (void).

Gestion des erreurs et sécurité vis-à-vis des exceptions

La fonction est déclarée avec l'identifiant noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) [SWS_CM_00105]. Ni codes d'erreur spécifiques ni notifications aux sous-systèmes d'erreur ou de diagnostic ne sont définis dans la norme.

Déroulement et conditions aux limites

L'appel devrait être exécuté de manière synchrone afin de désactiver immédiatement la gestion des erreurs E2E au niveau de l'événement, par exemple lorsque l'événement ne doit plus être surveillé ou avant que l'objet proxy associé ne soit libéré (interprétation). Question Q-ff00695fff5407fe (ouverte) Après exécution, la couche de communication ne traite plus aucune erreur de transport E2E via le callback précédemment enregistré pour cet événement.

Interaction

Le désenregistrement de gestionnaires pour les erreurs de transport suit un modèle uniforme à travers divers éléments de communication :

• Pour les notificateurs de champs au niveau du proxy, la fonction [SWS_CM_00126] est utilisée.
• Pour les déclencheurs de proxy, le gestionnaire est désinscrit via [SWS_CM_00108].
• Côté skeleton, des interfaces analogues sont disponibles pour l'ensemble des méthodes d'une interface de service ([SWS_CM_00095]) ainsi que pour les getters/setters de champs ([SWS_CM_00098]).

Utilisation

La méthode Unsubscribe() met fin à l'abonnement actif d'un événement de service côté proxy ([SWS_CM_00151], EXP_ARAComAPI §5.5). Elle est définie dans la portée <SI-Namespace>::proxy::events::<Event> et est incluse via le fichier d'en-tête #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00151]). La fonction ne prend aucun paramètre d'entrée et ne fournit aucune valeur de retour (void). Si l'événement n'était pas abonné au moment de l'appel, la méthode retourne sans exécuter d'action ([SWS_CM_00151]).

Gestion des erreurs et sécurité vis-à-vis des exceptions

L'opération est déclarée avec l'identifiant noexcept et est spécifiée comme sûre vis-à-vis des exceptions ([SWS_CM_00151]). Une DanglingSamplesViolation est prévue comme violation si la précondition selon [SWS_CM_00085] a été enfreinte avant l'appel de la méthode ([SWS_CM_00151]).

Interaction et interfaces apparentées

Au niveau du réseau, l'arrêt de l'abonnement déclenche l'envoi de messages SOME/IP de type StopSubscribeEventgroup ([SWS_CM_10378], SWS_CommunicationManagement §7.2.1.2.6). Au sein des interfaces de proxy, Unsubscribe() appartient au groupe des méthodes de gestion des souscriptions (EXP_ARAComAPI §5.3.1). Une sémantique de désinscription identique est également disponible pour les déclencheurs de service ([SWS_CM_00810], EXP_ARAComAPI §4) ainsi que pour les notifications de champ ([SWS_CM_11602]).