classe <SI-Namespace>::proxy::fields::<Field>

Utilisation

La méthode Get sert, dans la portée du proxy <SI-Namespace>::proxy::fields::<Field>, à la récupération asynchrone de la valeur actuelle du champ ([SWS_CM_00112] ; voir aussi AUTOSAR_AP_EXP_ARAComAPI §6 « FieldGet »). La fonction est mise à disposition via l'en-tête du proxy <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h et n'existe que si Field.hasGetter == TRUE est modélisé pour le champ ([SWS_CM_00112]). Elle ne prend aucun paramètre et renvoie un ara::core::Future<FieldType> qui, après un transfert réussi, contient la valeur actuelle ([SWS_CM_00112]).

Gestion des erreurs et conditions limites

L'interface est définie comme noexcept et sûre vis-à-vis des exceptions ([SWS_CM_00112]). Si l'opération échoue, le ara::core::Future renvoyé contient un code d'erreur avec sémantique de rollback ([SWS_CM_00112]) :

• ComErrc::kCommunicationFailure : le binding réseau signale une erreur de communication récupérable ou l'échec d'une communication sécurisée ([SWS_CM_00112]).
• ComErrc::kMinimumSendIntervalViolationError : une demande d'envoi a eu lieu plus rapidement que ne l'autorise l'intervalle d'envoi minimal configuré pour l'élément (minimumSendInterval) ([SWS_CM_00112]).
• InsufficientPermissionsViolation : l'exécution est rejetée par le Grant Enforcement ([SWS_CM_00112]).

Les erreurs applicatives (Application Errors) n'existent pas pour le getter ([SWS_CM_00113]).

Interaction

Côté squelette, le traitement de la requête du getter présuppose un callback enregistré via RegisterGetHandler ([SWS_CM_00114]). Chaque appel de Get() effectue un contrôle de bout en bout (E2E) ; l'état qui en résulte peut être interrogé de manière synchrone côté proxy via GetE2EStateMachineStateGetter ([SWS_CM_00145]).

Utilisation et contexte d'appel

La fonction Set est mise à disposition dans l'espace de noms <SI-Namespace>::proxy::fields::<Field> et n'est disponible que si Field.hasSetter == TRUE est configuré pour le champ [SWS_CM_00113]. Avant son utilisation, l'instance de service doit avoir été proposée côté serveur (OfferService()) puis trouvée et connectée côté client ARAComAPI §4.2 « Means of Communication ». L'appel s'effectue de manière asynchrone : il transmet la nouvelle valeur du champ via le paramètre value et renvoie un ara::core::Future<FieldType> [SWS_CM_00113]. La méthode est spécifiée comme noexcept et est considérée comme sûre vis-à-vis des exceptions [SWS_CM_00113].

Gestion des erreurs

Si la transmission échoue, l'erreur correspondante est mise à disposition via le ara::core::Future renvoyé [SWS_CM_00113] :

• ComErrc::kCommunicationFailure : signale une erreur de communication récupérable ou une perturbation de la transmission sécurisée ; en cas de timeout, un état indéterminé sans sémantique de rollback peut exister côté serveur [SWS_CM_00113].
• ComErrc::kMinimumSendIntervalViolationError : survient lorsqu'une requête d'envoi a été émise plus rapidement que l'intervalle minimal d'envoi configuré (minimumSendInterval) (également sans sémantique de rollback) [SWS_CM_00113].
• L'absence de droits d'accès entraîne un refus par le Grant Enforcement (InsufficientPermissionsViolation) [SWS_CM_00113].
• Les erreurs applicatives ne sont pas transmises via des exceptions, mais en renvoyant, en cas de succès du future, une valeur différente du paramètre de requête [SWS_CM_00113].

Interaction et concurrence

Côté serveur, l'appel correspond à un callback sur l'instance du squelette, qui doit avoir été préalablement enregistré au moyen de RegisterSetHandler [SWS_CM_00116] ARAComAPI §4.2 « Means of Communication ». Pour surveiller la sécurité de transmission E2E côté client, l'état de la machine d'état E2E du dernier appel de Set() peut être interrogé via GetE2EStateMachineStateSetter() [SWS_CM_00146].

Utilisation et contexte d'appel

La fonction SetReceiveHandler est mise à disposition côté proxy dans l'espace de noms <SI-Namespace>::proxy::fields::<Field> via le fichier d'en-tête <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h ([SWS_CM_11605]). Elle enregistre côté client un callback pour les notifications lors de changements de valeur d'un champ ([SWS_CM_11605]). Ce mécanisme suit la procédure de notification des événements, par laquelle le Communication Management informe le client lors des mises à jour (EXP_ARAComAPI §4.2 « Means of Communication »).

Un ara::com::FieldReceiveHandler, qui représente une fonction sans paramètre, est transmis comme paramètre ([SWS_CM_11605]). La fonction ne renvoie aucune valeur de retour (void) et est spécifiée comme sûre vis-à-vis des exceptions (noexcept) ([SWS_CM_11605]).

Gestion des erreurs et concurrence

Si l'objet callable transmis n'existe pas ou est nul, la fonction signale la violation InvalidHandlerViolation ([SWS_CM_11605]). Si l'exécution du gestionnaire doit avoir lieu dans un contexte d'exécution défini, la variante de modèle avec ExecutorT est disponible ([SWS_CM_11611]).

Interaction

Le comportement correspond aux enregistrements de gestionnaires pour les événements ([SWS_CM_00181]) et les déclencheurs ([SWS_CM_00250]). Une annulation de l'enregistrement devrait avoir lieu via UnsetReceiveHandler() en suivant le modèle d'interface de la classe de proxy (EXP_ARAComAPI §5.3.1 « Proxy Class API’s »). Question Q-74cd83b99aadec16 (ouverte)

Utilisation et contexte d'appel

La fonction modèle SetReceiveHandler fait partie de la classe de proxy class <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11611] ; en-tête #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h"). Elle sert à enregistrer côté client un gestionnaire de réception pour les notifications lors de changements de valeur d'un champ (AUTOSAR_AP_EXP_ARAComAPI §4.2 « Means of Communication », [SWS_CM_11605]). Un objet appelable handler de type ara::com::FieldReceiveHandler ainsi qu'un contexte d'exécution executor en tant que référence universelle ExecutorT&& sont transmis via les paramètres ([SWS_CM_11611]). La fonction ne possède aucune valeur de retour (void).

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

La méthode est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) ([SWS_CM_11611]). Si le callable handler transmis n'existe pas ou est nul, il s'agit d'une InvalidHandlerViolation ([SWS_CM_11611]). Les appelants doivent donc s'assurer qu'une fonction ou un objet fonction valide est fourni avant l'appel.

Concurrence et interaction

Contrairement à l'enregistrement standard sans exécuteur ([SWS_CM_11605]), le callback est exécuté lors de l'arrivée d'une notification de champ dans le contexte d'exécution fourni par executor ([SWS_CM_11611]). Interprétation : Cela devrait entraîner un découplage afin que le traitement des données spécifique à l'application ne s'effectue pas dans les contextes d'exécution des threads internes du middleware. Question Q-cbe1af19bea15a88 (ouverte) La méthode appartient aux API de la classe de proxy (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 « Proxy Class API’s ») et suit le même modèle que les variantes d'exécuteur pour les événements ([SWS_CM_11356] basé sur [SWS_CM_00181]) ainsi que les déclencheurs ([SWS_CM_00352] basé sur [SWS_CM_00250]).

La fonction SetSubscriptionStateChangeHandler enregistre sur un champ de proxy (portée <SI-Namespace>::proxy::fields::<Field>) un rappel défini par l'utilisateur, qui est appelé par le Communication Management dès que l'état d'abonnement (ara::com::SubscriptionState) du champ change ([SWS_CM_11607], [SWS_CM_00333]). L'appel s'effectue de façon synchrone et ne renvoie aucune valeur de retour ([SWS_CM_11607]). Elle compte parmi les interfaces proxy centrales pour la gestion des abonnements aux événements et aux champs (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 « Proxy Class API’s »).

En ce qui concerne le traitement des erreurs, la fonction d'enregistrement est spécifiée comme exception safe et déclarée avec noexcept ([SWS_CM_11607]). Si l'objet appelable handler transmis n'existe pas ou est null, il s'agit d'une violation de la spécification sous la forme d'une InvalidHandlerViolation ([SWS_CM_11607]).

En interaction avec l'établissement de la liaison, il convient de noter que Subscribe() doit par principe être considérée comme une opération asynchrone ([SWS_CM_12006]). Les applications ne doivent donc, même après un retour sans erreur de Subscribe(), présumer d'un abonnement réussi que lorsque le gestionnaire enregistré a signalé l'état kSubscribed ([SWS_CM_12006]). De plus, le Communication Management appelle le gestionnaire avec kSubscriptionPending si la liaison effective ne peut pas être finalisée immédiatement ou si l'instance de serveur est défaillante, par exemple à la suite d'un redémarrage ou d'une erreur réseau ([SWS_CM_00313]). Si le gestionnaire doit être exécuté dans un contexte d'exécution spécifique, la variante de modèle surchargée avec un ExecutorT est disponible à cet effet ([SWS_CM_11608]).

La fonction modèle SetSubscriptionStateChangeHandler dans l'espace de noms <SI-Namespace>::proxy::fields::<Field> sert à enregistrer une fonction de rappel pour surveiller les changements d'état de la souscription d'un champ ([SWS_CM_11608]). Elle enrichit le comportement de base de [SWS_CM_11607] en permettant au gestionnaire enregistré d'être exécuté dans un contexte d'exécution explicitement transmis (executor) ([SWS_CM_11608]).

La méthode prend deux paramètres ([SWS_CM_11608]) :

• handler : Le callback à appeler de type ara::com::SubscriptionStateChangeHandler ([SWS_CM_11354]), qui est déclenché dès que le ara::com::SubscriptionState change ([SWS_CM_00333]).
• executor : Une référence de transfert de type ExecutorT&& ([SWS_CM_11360]), qui fournit le contexte pour l'exécution du gestionnaire ([SWS_CM_11608]).

La fonction ne fournit aucune valeur de retour (void) et est déclarée comme noexcept ([SWS_CM_11608]). Elle est spécifiée exception safe ([SWS_CM_11608]). InvalidHandlerViolation est défini comme violation si le callable transmis n'existe pas ou est null ([SWS_CM_11608]).

Interprétation : Grâce à la transmission du executor, l'exécution du gestionnaire devrait être déplacée du contexte interne du gestionnaire de communication vers le contexte de thread ou de tâche de l'application. Question Q-647f618545799c4e (ouverte) Dans l'interaction des API de proxy, l'appel s'insère aux côtés de méthodes telles que Subscribe(), Unsubscribe() et UnsetSubscriptionStateChangeHandler() (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 « Proxy Class API’s »). Des variantes surchargées analogues avec contexte d'exécution existent pour les événements de proxy ([SWS_CM_11354]) ainsi que pour les déclencheurs de proxy ([SWS_CM_01106]).

Utilisation et contexte d'appel

La fonction membre SetTransportFaultConditionHandler sert à enregistrer un gestionnaire d’erreurs pour le notificateur d’un champ de Proxy dans l’espace de noms <SI-Namespace>::proxy::fields::<Field> [SWS_CM_00109]. Un objet appelable (callable) de type ara::com::e2e::TransportFaultConditionHandler est transmis en paramètre. La fonction ne fournit aucune valeur de retour et lie le rappel aux notificateurs d’instances de service individuelles afin de recevoir les erreurs de transmission du backend de communication AUTOSAR_AP_SWS_CommunicationManagement §7.4 « End-to-end communication protection » p. 235.

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

La méthode est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) [SWS_CM_00109]. Si le callable transmis est invalide ou nul, il s’agit d’une violation de précondition sous la forme d’une InvalidHandlerViolation [SWS_CM_00109]. Interpretation : la fonction ne devant lever aucune exception, une telle violation devrait typiquement conduire à un arrêt immédiat du programme dans AUTOSAR Adaptive. Question Q-74df6934d4ae3c93 (ouverte)

Concurrence et interaction

Alors que cette forme de base enregistre directement le gestionnaire, il existe avec [SWS_CM_00110] une variante template surchargée qui accepte en outre un exécuteur (ExecutorT&& executor) pour définir le contexte d’exécution asynchrone. La fonction s’inscrit dans le traitement des erreurs de bout en bout : tandis que les notificateurs ([SWS_CM_00109], [SWS_CM_00110]), les événements ([SWS_CM_00099]) et les déclencheurs ([SWS_CM_00106]) signalent les erreurs de transmission de manière asynchrone via de tels gestionnaires, les erreurs de transport lors de requêtes de méthodes ainsi que de getters et de setters sont au contraire renvoyées via ComErrc::kCommunicationFailure dans le ara::core::Future résultant [SWS_CM_00090].

Utilisation

La fonction membre modèle SetTransportFaultConditionHandler sert, dans le scope d'une classe Proxy Field (<SI-Namespace>::proxy::fields::<Field>), à enregistrer un gestionnaire pour le notificateur du champ respectif [SWS_CM_00110]. Elle accepte deux paramètres d'entrée :

• handler : le callable à enregistrer, de type ara::com::e2e::TransportFaultConditionHandler [SWS_CM_00110].
• executor : une référence rvalue vers un objet exécuteur (ExecutorT&&), dans le contexte d'exécution duquel les éventuels calculs déclenchés de manière asynchrone sont démarrés [SWS_CM_00110].

La fonction ne renvoie aucune valeur de retour (void) et est déclarée comme noexcept [SWS_CM_00110].

Gestion des erreurs et sécurité d'exécution

L'interface est spécifiée comme sûre vis-à-vis des exceptions (exception safe) [SWS_CM_00110]. Si un callable inexistant ou nul est passé comme handler, cela entraîne une InvalidHandlerViolation [SWS_CM_00110]. Ce gestionnaire permet de signaler des conditions d'erreur de transport spécifiques, tandis que les méthodes ainsi que les getters et setters de champ signalent d'éventuelles erreurs de transport via ComErrc::kCommunicationFailure sur leurs futures de retour respectifs [SWS_CM_00090].

Concurrence et interaction

La méthode constitue la surcharge avec contexte d'exécution de la fonction de base [SWS_CM_00109], qui comporte moins de paramètres. Grâce à l'objet exécuteur transmis, l'implémentation découple l'exécution du gestionnaire du contexte de réception interne de l'administration de communication [SWS_CM_00110]. Des surcharges similaires sont disponibles pour les événements de proxy [SWS_CM_00100], les déclencheurs de proxy [SWS_CM_00107] ainsi que pour les méthodes de skeleton [SWS_CM_00094] et les champs de skeleton [SWS_CM_00097]. Interprétation : l'appel devrait judicieusement avoir lieu avant l'arrivée de messages de notificateur ou avant l'abonnement au notificateur, afin de garantir une surveillance des erreurs sans faille. Question Q-bc5c62dd39c09029 (ouverte)

La méthode Subscribe sert à s'abonner aux notifications pour un Field d'une instance de proxy de service dans la portée proxy::fields::<Field> ([SWS_CM_11601]). Via le paramètre maxSampleCount, l'application définit le nombre maximal d'échantillons de données qu'elle souhaite conserver simultanément, configurant ainsi le cache de réception local ([SWS_CM_11601], EXP ARAComAPI §5.3 « Proxy Class API’s »). L'appel est asynchrone : le ara::core::Result<void> renvoyé signale uniquement l'acceptation de l'abonnement par le Communication Management (EXP ARAComAPI §5.3.5.2 « Monitoring Event Subscription »).

En ce qui concerne le comportement d'état et le traitement des erreurs, les règles suivantes s'appliquent :

• Idempotence : Si le Field se trouve déjà dans l'état kSubscribed ou kSubscriptionPending et que le maxSampleCount transmis correspond à la valeur de la souscription actuelle, la méthode retourne sans effet ([SWS_CM_11601]).
• Codes d'erreur : Si le cache requis ne peut pas être fourni, l'opération échoue avec l'erreur ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_11601], [SWS_CM_10432]).
• Vérification des autorisations : Si les droits requis font défaut, l'appel est rejeté par le Grant Enforcement avec une InsufficientPermissionsViolation ([SWS_CM_11601]).

La méthode est déclarée comme noexcept et spécifiée comme sûre face aux exceptions ([SWS_CM_11601]). Sémantiquement, elle suit le comportement de la souscription aux événements ([SWS_CM_00141]) ; le cache configuré constitue la base de la réception ultérieure d'échantillons via des méthodes telles que GetNewSamples ([SWS_CM_00701]).

La fonction UnsetReceiveHandler() sert, au niveau du proxy, à désenregistrer un gestionnaire de réception préalablement enregistré pour les notifications de champ ([SWS_CM_11606]). Elle fait partie des API de classes proxy de ara::com (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 « Proxy Class API’s ») et se situe dans l'espace de noms <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11606]).

Concernant le contexte d'appel et la sémantique, la méthode ne prend aucun paramètre et ne renvoie aucune valeur ([SWS_CM_11606]). Par cet appel, une application peut à tout moment passer d'un modèle de notification événementiel à un fonctionnement par scrutation (polling) basé sur des requêtes en retirant le rappel propre à l'utilisateur (AUTOSAR_AP_EXP_ARAComAPI §5.3.2 « RadarService Proxy Class Example »).

Pour le traitement des erreurs, la fonction est spécifiée comme noexcept ainsi que exception safe ([SWS_CM_11606]) ; selon la spécification, aucun code d'erreur spécifique n'existe. L'appel s'effectue de manière synchrone ; après le retrait réussi du gestionnaire, le Communication Management ne déclenche plus aucun appel de rappel lors de l'arrivée de nouvelles données (interprétation : les exécutions en cours ou déjà planifiées devraient encore être achevées ou traitées de façon sérialisée avant le retrait, car les appels de rappel par le Communication Management doivent être sérialisés ; cf. AUTOSAR_AP_EXP_ARAComAPI §5.3.2 « RadarService Proxy Class Example »). Question Q-fbc65e80b8d8be38 (ouverte)

Dans le cadre des interactions, la méthode correspond à la désactivation des déclencheurs pour les événements de service ([SWS_CM_00183] ; AUTOSAR_AP_EXP_ARAComAPI §10) et les déclencheurs ([SWS_CM_11614]). Dans le binding DDS, le comportement est reflété via le mappage de UnsetReceiveHandler() sur le DataReader respectif ([SWS_CM_11141]).

Utilisation

Dans le cadre de la plateforme AUTOSAR Adaptive, la méthode UnsetSubscriptionStateChangeHandler sert à supprimer un rappel préalablement enregistré pour les changements d'état d'abonnement (ara::com::SubscriptionState) d'un champ [SWS_CM_11609]. Elle est appelée de manière synchrone sur des instances de champs d'un proxy de service dans l'espace de noms <SI-Namespace>::proxy::fields::<Field> et nécessite l'inclusion de l'en-tête généré #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 « UnsetSubscriptionStateChangeHandler ». L'appel ne prend aucun paramètre d'entrée et ne renvoie aucune valeur de retour.

Gestion des erreurs et concurrence

L'interface est déclarée comme noexcept et satisfait selon la spécification à la propriété exception safe [SWS_CM_11609]. L'apparition d'erreurs ou d'exceptions est donc exclue. Étant donné que le désenregistrement prend effet immédiatement, il faut supposer (interprétation) qu'après la fin de la méthode, plus aucune nouvelle notification n'est transmise à l'ancien gestionnaire. Question Q-30238329b76b64f4 (ouverte)

Interaction

La fonction fait partie des API fondamentales de classes de proxy pour la gestion des abonnements dans ara::com AUTOSAR_AP_EXP_ARAComAPI §5.3.1 « Proxy Class API’s ». Des méthodes similaires pour désactiver les gestionnaires de changement d'état existent pour les événements de proxy [SWS_CM_00334] et les déclencheurs [SWS_CM_01108], ainsi que, symétriquement côté squelette, pour les événements [SWS_CM_12010] et les déclencheurs [SWS_CM_01112].

Utilisation

La fonction UnsetTransportFaultConditionHandler sert à désinscrire un ara::com::e2e::TransportFaultConditionHandler précédemment enregistré pour le notificateur d'un champ de proxy donné [SWS_CM_00126]. Elle est définie au sein du scope <SI-Namespace>::proxy::fields::<Field> et est incluse via le fichier d'en-tête <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.1.4 « UnsetTransportFaultConditionHandler ». L'appel s'effectue sans paramètre et ne renvoie aucune valeur de retour (void).

Gestion des erreurs

La méthode est déclarée comme noexcept et possède la garantie d'exception exception safe [SWS_CM_00126]. Aucun code d'erreur n'est renvoyé et aucune exception n'est levée. Si aucun gestionnaire n'avait été enregistré auparavant, un appel répété resterait vraisemblablement sans effet. Question Q-85da9a7b00678748 (ouverte)

Concurrence et restrictions

La spécification ne définit aucune exigence particulière en matière de concurrence ou de sécurité des threads. L'interface fonctionnant de manière synchrone et n'utilisant pas de types asynchrones, le retrait du gestionnaire d'erreurs devrait prendre effet de manière synchrone et immédiate. Question Q-ed4cc712bb55aee5 (ouverte) Les appelants devraient coordonner l'appel dans le cycle de vie de l'application de telle sorte que les messages de notificateur des différentes instances de service ne soient pas traités sans gestionnaire de manière incontrôlée AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 « End-to-end communication protection for SOMEIP ».

Interaction

La désinscription suit un modèle de nommage et de fonctionnement cohérent dans AUTOSAR Adaptive :

• Au niveau du proxy, des fonctions équivalentes sont disponibles pour les événements ([SWS_CM_00105]) ainsi que pour les déclencheurs ([SWS_CM_00108]).
• Au niveau du skeleton, des homologues correspondants existent pour les getters et setters de champ ([SWS_CM_00098]) ainsi que de manière globale pour toutes les méthodes de l'interface skeleton ([SWS_CM_00095]).