classe <SI-Namespace>::proxy::<SI>Proxy

Utilisation et sémantique

La méthode de fabrique statique Create sert, conformément à [SWS_CM_10438], à la création sans exception d'une instance de proxy (<SI>Proxy) selon l'idiome du constructeur nommé. Elle requiert comme paramètre handle un handle de service préalablement déterminé conformément à [SWS_CM_00131]. L'appel s'effectue de manière synchrone et est déclaré comme noexcept. Le résultat est retourné dans un ara::core::Result, qui contient l'instance de proxy prête à l'emploi en cas de succès.

Gestion des erreurs

Si une erreur survient pendant l'instanciation, Create renvoie via le ara::core::Result un code d'erreur de type ara::com::ComErrc [SWS_CM_10438] :

• ComErrc::kServiceNotAvailable : Le service n'est plus disponible après une offre préalable via OfferService().
• ComErrc::kCommunicationFailure : Le binding réseau signale une erreur de communication récupérable ou l'échec d'une connexion sécurisée.

Les deux erreurs présentent une sémantique de rollback [SWS_CM_10438]. En cas d'erreurs structurelles ou liées à la sécurité, des violations spécifiées s'appliquent : si le handle transmis est nul ou corrompu, il s'agit d'une ErroneousServiceHandleViolation. Si le processus appelant ne dispose pas des autorisations nécessaires pour l'instance dans le cadre du grant enforcement, la requête est rejetée et traitée comme une InsufficientPermissionsViolation (SWS CommunicationManagement §8 « Security », [SWS_CM_10438]).

Concurrence et contraintes

Interprétation : Étant donné que Create fonctionne de manière synchrone et lie des ressources de communication, l'appel devrait être réentrant pour différents handles, mais ne devrait pas être exécuté dans des boucles hard real-time à temps critique en raison d'initialisations réseau possibles. Question Q-f7ba23670f562788 (ouverte)

La méthode statique FindService de la classe Proxy sert à la recherche synchrone d’instances de service disponibles à l’aide d’un ara::com::InstanceIdentifier ([SWS_CM_00122]). L’appel renvoie directement le résultat sous la forme d’un ara::core::Result, lequel contient un ara::com::ServiceHandleContainer en cas d’exécution réussie ([SWS_CM_00122]). Ce conteneur — généralement implémenté sous forme d’un ara::core::Vector ([SWS_CM_00304]) — peut être vide, comporter un unique descripteur d’instance ou plusieurs descripteurs selon l’état de mise à disposition effectif (ARAComAPI §6.5 « Service Discovery »).

En cas d’erreur, le ara::core::Result renvoie un code d’erreur issu de ara::com::ComErrc, à savoir ComErrc::kCommunicationFailure, lorsque le binding réseau signale une erreur de transmission récupérable ou un problème lors de la communication sécurisée ([SWS_CM_00122]). De plus, l’accès est soumis au contrôle des droits ; des autorisations insuffisantes mènent à une InsufficientPermissionsViolation ([SWS_CM_00122]).

Concernant le déroulement et la concurrence, les conditions suivantes s’appliquent :

• Contexte d’appel et synchronicité : la recherche étant exécutée immédiatement, seules sont trouvées les instances pour lesquelles OfferService() a été préalablement appelé côté serveur (ARAComAPI §6.5 « Service Discovery »).
• Sécurité vis-à-vis des exceptions et réentrance : la fonction est spécifiée comme noexcept et sûre vis-à-vis des exceptions (exception-safe) ([SWS_CM_00122]). Comme la méthode est statique et n’exige aucun état d’objet modifiable, elle devrait pouvoir être appelée de manière réentrante et sûre pour les threads. Question Q-3228cc998c4a737e (ouverte)
• Traitement ultérieur : les descripteurs trouvés servent à l’instanciation d’objets Proxy via le constructeur Proxy(const HandleType &handle) ([SWS_CM_00131]). Pour une recherche basée sur des modèles, la surcharge avec ara::core::InstanceSpecifier est alternativement disponible ([SWS_CM_00622]).

La fonction statique FindService de la classe de proxy sert, conformément à [SWS_CM_00622], à la recherche synchrone d'instances de service disponibles à l'aide d'un ara::core::InstanceSpecifier avec retour immédiat (« immediately returned request »). Le prérequis pour la recherche est que l'instance de squelette de service respective ait été préalablement mise à disposition au moyen de OfferService() (ARAComAPI p. 103 « Figure 6.5: Service Discovery »).

Valeurs de retour et interaction

Comme résultat, l'appel fournit un ara::core::Result avec un ara::com::ServiceHandleContainer selon [SWS_CM_00622], qui repose par défaut sur ara::core::Vector [SWS_CM_00304]. Ce conteneur peut être vide, contenir un handle unique ou plusieurs instances trouvées (ARAComAPI p. 103 « Figure 6.5: Service Discovery »). Les handles de service obtenus sont ensuite transmis au constructeur pour l'instanciation de l'objet proxy [SWS_CM_00131]. Pour une recherche asynchrone pilotée par événements avec notification, StartFindService est disponible en alternative [SWS_CM_00623], tandis que pour les identifiants d'instance, la surcharge de [SWS_CM_00122] est utilisée.

Gestion des erreurs et conditions limites

La fonction est déclarée comme noexcept et considérée comme sûre vis-à-vis des exceptions (« exception safe ») selon [SWS_CM_00622]. En cas d'erreur, l'objet Result contient le code d'erreur ComErrc::kCommunicationFailure, par exemple lors de perturbations de communication du binding réseau [SWS_CM_00622]. De plus, [SWS_CM_00622] définit des violations de modèle et de droits d'accès telles que InstanceSpecifierMappingIntegrityViolation, PortInterfaceMappingViolation, ProcessMappingViolation, InstanceSpecifierAlreadyInUseViolation ainsi que InsufficientPermissionsViolation.

Interprétation : en raison du retour synchrone et immédiat, la méthode devrait convenir en premier lieu pour les phases initiales d'initialisation ou un polling ciblé, pour autant qu'aucune observation continue par callback ne soit requise. Question Q-ea5b242a6fe41d20 (ouverte)

Utilisation

Le constructeur explicite <SI>Proxy instancie la classe proxy de service spécifique au type dans l'espace de noms <SI-Namespace>::proxy [SWS_CM_00131]. Dans le cadre du patron proxy-skeleton, cet objet généré sert de façade locale du côté du consommateur de service, qui relaie les appels de méthode vers l'implémentation de service effective ARAComAPI Figure 5.1 « Proxy Skeleton Pattern ».

Pour la construction, une référence à un HandleType valide est transmise comme paramètre [SWS_CM_00131]. Cet identifiant doit avoir été obtenu au préalable via des mécanismes de Service Discovery – soit de façon synchrone via FindService() [SWS_CM_00122], soit de façon asynchrone via le callback enregistré de StartFindService() [SWS_CM_00123].

Gestion des erreurs

La construction n'est pas sûre face aux exceptions (not exception safe) [SWS_CM_00131]. Si le service référencé ne peut pas être atteint, une ara::com::ComException selon ara::com::ComErrc::kServiceNotAvailable est levée [SWS_CM_00131]. En outre, les violations suivantes sont définies :

• ErroneousServiceHandleViolation : survient lorsque l'objet HandleType transmis est nul ou corrompu [SWS_CM_00131].
• InsufficientPermissionsViolation : survient lorsque la création est refusée par le contrôle des droits (Grant Enforcement) [SWS_CM_00131].

Restrictions et cycle de vie

Pour la classe proxy, le constructeur de copie est explicitement supprimé (=delete) [SWS_CM_00136]. La transmission de l'instance est exclusivement autorisée via le constructeur de déplacement (Move Constructor), qui est également spécifié comme non sûr face aux exceptions [SWS_CM_00137]. À l'exécution, après une création réussie, la gestion de la communication met à jour automatiquement en arrière-plan l'adressage de la couche de transport de l'instance proxy existante en cas de défaillance temporaire et de retour de la disponibilité du service cible ARAComAPI Figure 6.1 « Auto Updating of Proxy Instance ».

Le destructeur ~<SI>Proxy () termine le cycle de vie d'une instance de proxy de service et libère les ressources locales associées [SWS_CM_99444]. Un proxy de service fait office, côté consommateur, de façade locale pour interagir avec une implémentation de service potentiellement distante et relaie les appels ARAComAPI §5.1 « Proxy Skeleton Pattern ». L'objet proxy est préalablement instancié via un handle de service déterminé [SWS_CM_00131], lequel a été fourni via des fonctions de découverte de services telles que FindService [SWS_CM_00122].

Pour la destruction et le comportement à l'exécution, les directives et contraintes suivantes s'appliquent :

• Cycle de vie et sémantique : la destruction s'effectue de manière synchrone lors de la sortie de la portée ou lors de la suppression explicite de l'instance. Alors que le constructeur de copie de la classe proxy est supprimé [SWS_CM_00136], l'objet peut être déplacé par sémantique de déplacement avant sa destruction [SWS_CM_00137].
• Sécurité des exceptions : le destructeur est spécifié comme not exception safe [SWS_CM_99444].
• Conditions préalables et comportement en cas d'erreur : la violation de la condition préalable [SWS_CM_00087] entraîne un DanglingSamplesViolation [SWS_CM_99444]. (Interprétation : avant l'appel du destructeur, l'ensemble des références d'échantillons ou des pointeurs de données détenus par le consommateur doivent vraisemblablement être libérés pour éviter les références invalides). Question Q-5488797b732d9be6 (ouverte)
• Interaction : si des recherches asynchrones de services sont utilisées, celles-ci doivent, au besoin, être terminées via StopFindService avant la libération du contexte d'utilisation [SWS_CM_00125]. De plus, les gestionnaires de traitement des erreurs enregistrés pour les événements, déclencheurs (triggers) et champs peuvent être préalablement réinitialisés [SWS_CM_00105] [SWS_CM_00108] [SWS_CM_00126].

La méthode statique StartFindService [SWS_CM_00123] de la classe proxy démarre la recherche asynchrone d'instances de service à l'aide d'un ara::com::InstanceIdentifier avec enregistrement d'un gestionnaire de callback (ARAComAPI §6.5 « Service Discovery »). Un ara::com::FindServiceHandler ainsi que le ara::com::InstanceIdentifier recherché sont transmis à l'appel [SWS_CM_00123].

En cas de succès, la fonction renvoie un ara::core::Result avec un ara::com::FindServiceHandle [SWS_CM_00123]. Cet identifiant représente la requête de recherche active et est impérativement requis afin d'interrompre à nouveau ultérieurement la surveillance de la disponibilité du service ainsi que les appels ultérieurs du gestionnaire au moyen de StopFindService [SWS_CM_00125].

Si un problème de communication survient lors de l'établissement de la connexion, la méthode renvoie le code d'erreur ComErrc::kCommunicationFailure dans le ara::core::Result [SWS_CM_00123]. Si l'instance de callable transmise est invalide ou nulle, cela est considéré comme un InvalidHandlerViolation ; des droits d'accès manquants entraînent un InsufficientPermissionsViolation [SWS_CM_00123].

Dès qu'une instance de service appropriée devient disponible dans le système, le gestionnaire de communication appelle le gestionnaire enregistré avec les handles de service correspondants [SWS_CM_00123]. À l'aide d'un HandleType signalé, l'application peut créer une instance de proxy concrète via la méthode constructeur nommée Create [SWS_CM_10438]. Interprétation : le gestionnaire devrait être exécuté de manière asynchrone dans un thread du gestionnaire de communication, raison pour laquelle l'accès aux ressources partagées dans le gestionnaire doit s'effectuer de manière thread-safe. Question Q-9dc570d7e65fc808 (ouverte) Pour la recherche via un identifiant basé sur un modèle, StartFindService avec InstanceSpecifier est disponible comme alternative [SWS_CM_00623].

La méthode statique StartFindService de la classe proxy démarre la recherche continue d'instances de service à l'aide d'un ara::core::InstanceSpecifier modélisé [SWS_CM_00623]. Lors de l'appel, le InstanceSpecifier ainsi qu'une fonction de callback de type ara::com::FindServiceHandler sont transmis [SWS_CM_00623]. Comme valeur de retour, la fonction renvoie un ara::core::Result<ara::com::FindServiceHandle> [SWS_CM_00623] qui, en cas d'enregistrement réussi, met à disposition un descripteur de recherche pour la gestion de la recherche.

Le traitement des erreurs s'effectue via le ara::core::Result renvoyé. Si une erreur de communication récupérable ou une erreur de communication sécurisée survient lors de la liaison réseau, le résultat contient le code d'erreur ComErrc::kCommunicationFailure [SWS_CM_00623]. En outre, des violations spécifiques sont spécifiées : InvalidHandlerViolation si le gestionnaire transmis est invalide ou nul, InsufficientPermissionsViolation en cas d'autorisations manquantes par suite du Grant Enforcement, ainsi que des violations de modélisation telles que InstanceSpecifierMappingIntegrityViolation ou PortInterfaceMappingViolation [SWS_CM_00623].

Concernant la concurrence et les conditions aux limites, la fonction est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions [SWS_CM_00623]. L'exécution du gestionnaire enregistré devrait vraisemblablement s'effectuer de manière asynchrone par l'administration de communication dès que des instances de service correspondantes sont détectées dans le système. Question Q-79fb3ff78d517714 (ouverte)

Dans l'interaction avec les interfaces associées, les points suivants s'appliquent :

• Le ara::com::FindServiceHandle renvoyé doit être conservé afin de mettre fin à la recherche en cours via StopFindService [SWS_CM_00125] et d'interrompre la réception de notifications supplémentaires.
• Les descripteurs mis à disposition via le callback (HandleType) servent typiquement à instancier l'objet proxy au moyen de la méthode de fabrique Create [SWS_CM_10438].
• En alternative à la recherche via un InstanceSpecifier, une recherche peut également être initiée avec un ara::com::InstanceIdentifier [SWS_CM_00123].

Sur une instance de proxy, la méthode SetServiceStateChangeHandler sert à enregistrer une fonction de rappel destinée à surveiller les changements de disponibilité du service concerné ([SWS_CM_01074], SWS CommunicationManagement §8.3.8.2.4.6 « SetServiceStateChangeHandler(ara::com::ServiceStateHandler) »). La gestion de la communication appelle ce gestionnaire dès que l'état de disponibilité du service (ServiceState) change ([SWS_CM_01074]).

Un objet fonction de type ara::com::ServiceStateHandler, spécifié comme std::function<void(ServiceState)> ([SWS_CM_01072]), est transmis en paramètre. La fonction ne possède aucune valeur de retour. Un gestionnaire déjà enregistré peut être écrasé pendant l'exécution par un nouvel appel ([SWS_CM_01074]).

Concernant le traitement des erreurs, la fonction est déclarée comme sûre face aux exceptions (noexcept) ([SWS_CM_01074]). Si l'élément appelable transmis n'existe pas ou est nul, la violation InvalidHandlerViolation est caractérisée ([SWS_CM_01074]).

Concernant l'environnement d'exécution, [SWS_CM_01074] constitue l'interface de base. Comme aucun exécuteur ne peut être transmis ici, le rappel devrait vraisemblablement être exécuté dans le contexte de thread interne de la gestion de la communication. Question Q-7833435e7aa1da9f (ouverte) Si une exécution dans un contexte d'application spécifique est requise, la variante template surchargée avec un executor selon [SWS_CM_01076] est disponible en alternative (SWS CommunicationManagement §8.3.8.2.4.5 « SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&) »).

Utilisation et contexte d'appel

La méthode modèle SetServiceStateChangeHandler sert, sur la classe proxy générée <SI-Namespace>::proxy::<SI>Proxy, à enregistrer un rappel pour surveiller la disponibilité du service [SWS_CM_01076]. La fonction prend deux paramètres AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.5 « SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&) » :

• handler : un foncteur de type ara::com::ServiceStateHandler (défini comme std::function<void(ServiceState)>), appelé à chaque changement de l'état de disponibilité [SWS_CM_01072], [SWS_CM_01074].
• executor : un contexte d'exécution du type modèle ExecutorT selon [SWS_CM_11360], dans lequel le gestionnaire enregistré est exécuté [SWS_CM_01076].

La fonction ne possède pas de valeur de retour (void) [SWS_CM_01076].

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

La fonction est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) [SWS_CM_01076]. Si le gestionnaire appelable transmis n'existe pas ou est null, une InvalidHandlerViolation est déclenchée [SWS_CM_01076].

Concurrence et restrictions

Un gestionnaire enregistré peut être remplacé au moment de l'exécution [SWS_CM_01074]. L'exécution s'effectuant via l'objet executor transmis [SWS_CM_01076], la notification est vraisemblablement traitée de manière asynchrone dans le contexte de thread ou de répartition fourni par l'utilisateur. Question Q-349c5224c3b9cc20 (ouverte)

Interaction

La méthode enrichit la variante élémentaire [SWS_CM_01074] de la spécification explicite du contexte d'exécution [SWS_CM_01076]. L'en-tête <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h est requis pour l'intégration, tandis que le type de gestionnaire provient de ara/com/types.h [SWS_CM_01072].

La méthode statique de modèle StartFindService démarre la surveillance asynchrone en arrière-plan pour la découverte d'instances d'un service à l'aide d'un ara::com::InstanceIdentifier ([SWS_CM_11352], EXP_ARAComAPI §5.3.3 « Proxy Class API’s »). Outre l'instance cible (instance selon [SWS_CM_00122]), une fonction de rappel (handler selon [SWS_CM_00123]) ainsi qu'un contexte d'exécution (executor du type de modèle ExecutorT selon [SWS_CM_11360]) sont enregistrés ([SWS_CM_11352]). Les notifications de rappel devraient ainsi être traitées dans le contexte de thread ou de tâche du executor transmis ([SWS_CM_11352]). Question Q-1db520123c1e49a4 (ouverte)

En tant que valeur de retour, l'appel fournit un ara::com::FindServiceHandle ([SWS_CM_11352]). Ce handle identifie l'activité de recherche en cours et est requis pour terminer explicitement ultérieurement l'activité en arrière-plan via [SWS_CM_00125] (StopFindService) (EXP_ARAComAPI §5.3.3 « Proxy Class API’s »). Les handles de service (HandleType) obtenus via le rappel enregistré servent ensuite à la construction des instances proxy associées ([SWS_CM_00131]).

La fonction est déclarée comme noexcept et spécifiée sûre face aux exceptions (exception safe) ([SWS_CM_11352]). Les violations à l'exécution (Violations) suivantes sont définies :

• InvalidHandlerViolation : survient lorsque la fonction de gestionnaire transmise est invalide ou correspond à null ([SWS_CM_11352]).
• InsufficientPermissionsViolation : survient lorsque l'accès est refusé par le système d'autorisations (Grant Enforcement) ([SWS_CM_11352]).

Si un service doit plutôt être recherché via un ara::core::InstanceSpecifier basé sur un modèle, la variante de fonction [SWS_CM_11365] est disponible à titre d'alternative.

La fonction statique de modèle StartFindService démarre la recherche continue et asynchrone d'instances de service à l'aide d'un ara::core::InstanceSpecifier avec enregistrement d'un gestionnaire de notification dans un contexte d'exécution transmis [SWS_CM_11365]. Contrairement aux recherches ponctuelles synchrones, elle déclenche une activité en arrière-plan pour surveiller la disponibilité du service et renvoie un ara::com::FindServiceHandle EXP_ARAComAPI §5.3 « Proxy Class APIs ».

Paramètres et exécution

La fonction accepte trois paramètres [SWS_CM_11365] :

• handler : fonction de rappel de type ara::com::FindServiceHandler selon [SWS_CM_00123], appelée lors de modifications de la disponibilité de l'instance.
• instance : le ara::core::InstanceSpecifier à rechercher selon [SWS_CM_00123].
• executor : un contexte d'exécution du type de modèle ExecutorT selon [SWS_CM_11360]. Interprétation : l'argument de modèle ExecutorT devrait déterminer dans quel contexte de thread ou de tâche le rappel enregistré est exécuté. Question Q-6d46f67d536a391e (ouverte)

Gestion des erreurs et conditions limites

La signature est déclarée comme noexcept et spécifiée comme sûre face aux exceptions [SWS_CM_11365]. Du point de vue de la spécification, des violations fonctionnelles (Violations) sont définies : InstanceSpecifierMappingIntegrityViolation (résolution échouée dans le contexte Executable ou aucun PortPrototype), PortInterfaceMappingViolation et ProcessMappingViolation (mappages PortInterface non concordants), InstanceSpecifierAlreadyInUseViolation, InvalidHandlerViolation (gestionnaire invalide ou inexistant) ainsi que InsufficientPermissionsViolation en cas d'autorisation d'accès manquante [SWS_CM_11365].

Interaction

Le FindServiceHandle obtenu sert à terminer de manière contrôlée la surveillance continue en arrière-plan par transmission à StopFindService [SWS_CM_00125]. Les handles signalés au gestionnaire sont utilisés pour instancier des proxys de service concrets au moyen de Proxy(handle) [SWS_CM_00131]. Pour les recherches au moyen de ara::com::InstanceIdentifier, une surcharge alternative [SWS_CM_11352] existe.

La fonction statique StopFindService de la classe proxy met fin à une recherche de service asynchrone démarrée précédemment avec StartFindService et arrête la réception de notifications supplémentaires pour le handle transmis [SWS_CM_00125]. L'activité d'arrière-plan en cours destinée à surveiller la disponibilité du service est ainsi arrêtée par le binding technique AP EXP ARAComAPI §5.3 « Proxy Class API’s ».

Utilisation et sémantique

• Paramètres : comme paramètre d'entrée, la fonction attend un ara::com::FindServiceHandle obtenu précédemment par l'une des méthodes StartFindService ([SWS_CM_00123], [SWS_CM_00623], [SWS_CM_11352], [SWS_CM_11365], [SWS_CM_00125]).
• Valeur de retour et sécurité vis-à-vis des erreurs : la fonction ne fournit aucune valeur de retour (void), est déclarée avec noexcept et spécifiée comme sûre vis-à-vis des exceptions [SWS_CM_00125].
• Concurrence et contexte d'appel : un appel de StopFindService est expressément autorisé également directement à l'intérieur de la fonction de callback définie par l'utilisateur FindServiceHandler [SWS_CM_00383] AP EXP ARAComAPI §5.3 « Proxy Class API’s ». À cette fin, le FindServiceHandle respectif est transmis en tant que paramètre au gestionnaire [SWS_CM_00383]. Comme le callback lui-même n'a pas besoin d'être réentrant, la sérialisation des appels consécutifs doit être garantie par l'implémenteur du binding AP EXP ARAComAPI §5.3 « Proxy Class API’s ».

La fonction membre UnsetServiceStateChangeHandler fait partie de la classe de proxy générée dans l'espace de noms <SI-Namespace>::proxy::<SI>Proxy conformément à [SWS_CM_01075] (AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.12 « UnsetServiceStateChangeHandler »). Elle est incluse via l'en-tête #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h".

Concernant l'utilisation, le comportement et la concurrence, les dispositions suivantes s'appliquent :

• Utilisation : la méthode possède la signature void UnsetServiceStateChangeHandler() noexcept;. Elle ne prend aucun paramètre et ne renvoie aucune valeur de retour. Interprétation : d'après l'identifiant ainsi que la référence à [SWS_CM_01074], l'appel sert à réinitialiser ou à désinscrire un gestionnaire de rappel préalablement enregistré pour les changements d'état du service sur l'instance de proxy. Question Q-6eb71298a6f37ad9 (ouverte)
• Traitement des erreurs et sécurité des exceptions : l'opération est déclarée comme noexcept et spécifiée comme sans danger vis-à-vis des exceptions (exception safe) ([SWS_CM_01075]). Elle ne lève aucune exception et ne renvoie aucun code d'erreur à l'appelant.
• Interaction et contraintes : la sémantique fonctionnelle renvoie à la définition figurant dans [SWS_CM_01074]. Interprétation : la désinscription devrait prendre effet de manière synchrone, de sorte qu'aucun changement d'état ultérieur ne soit délivré via le rappel antérieur après le retour de l'appel de fonction. Question Q-31348a50d9be537d (ouverte)