classe ara::diag::DiagnosticSovdRecordContentElementDataView

Utilisation

La fonction synchrone [SWS_DM_02288] insère une valeur entière signée (std::int64_t) sous la clé key indiquée (ara::core::StringView) dans une structure de données SOVD. Elle est déclarée en tant que méthode de la classe ara::diag::DiagnosticSovdRecordContentElementDataView et intégrée via l'en-tête ara/diag/diagnostic_sovd_content_element_data.h.

Prérequis et gestion des erreurs

Conformément à [SWS_DM_02288], l'objet DiagnosticSovdContentElementData sous-jacent doit être de type RecordContentElementData ou ContentData, tandis que l'élément à ajouter ne doit lui-même pas être un ContentData. La fonction est définie comme noexcept et renvoie un ara::core::Result<void>. Si l'opération échoue – par exemple parce que le conteneur cible possède un type incompatible ou que l'élément ne peut pas être ajouté –, le résultat contient un code d'erreur ; interprétation : cela devrait typiquement aussi être le cas lors de collisions de clés. Question Q-524c832a794559b7 (ouverte)

Concurrence et interaction

L'exécution est spécifiée comme sûre pour les threads et sans danger au niveau des exceptions [SWS_DM_02288]. Au sein de l'interface, il existe des surcharges de même type pour les entiers non signés ([SWS_DM_02289]), les nombres à virgule flottante ([SWS_DM_02290]), les valeurs booléennes ([SWS_DM_02291]), les chaînes de caractères ([SWS_DM_02292]) ainsi que les éléments de données imbriqués ([SWS_DM_02293]). La même méthode est par ailleurs fournie sur la classe porteuse DiagnosticSovdContentElementData ([SWS_DM_02368]).

La fonction membre synchrone Add de la classe ara::diag::DiagnosticSovdRecordContentElementDataView sert à ajouter une valeur entière 64 bits non signée sous une clé donnée ([SWS_DM_02289]). Elle est employée dans le cadre de la fonctionnalité SOVD du Diagnostic Management, qui fournit la communication de diagnostic selon ASAM SOVD (AUTOSAR_AP_SWS_Diagnostics §1.0 « Introduction and functional overview », [SWS_DM_01369]).

Utilisation et appel

La méthode est incluse via l'en-tête ara/diag/diagnostic_sovd_content_element_data.h. Comme paramètres, elle attend l'identifiant key en tant que ara::core::StringView ainsi que la valeur à ajouter content_element en tant que std::uint64_t ([SWS_DM_02289]). L'appel est synchrone, est spécifié comme noexcept et renvoie le résultat sous forme de ara::core::Result<void>.

Gestion des erreurs et conditions limites

• Conditions de type : Le DiagnosticSovdContentElementData instancié doit être soit de type RecordContentElementData, soit de type ContentData. De plus, l'élément à ajouter lui-même ne doit pas être de type ContentData ([SWS_DM_02289]).
• Comportement en cas d'erreur : Si l'une de ces exigences de type est enfreinte ou si l'élément ne peut pas être ajouté, la fonction renvoie un ara::core::Result en erreur ([SWS_DM_02289]). La spécification n'indique pas de codes d'erreur spécifiques à cet endroit ; l'objet Result fournit probablement un code d'erreur correspondant du domaine de diagnostic. Question Q-ffca131eece93b35 (ouverte)
• Concurrence : La fonction est explicitement spécifiée comme thread-safe et exception safe ([SWS_DM_02289]).

Interaction

La méthode appartient à une famille de surcharges typées pour la saisie d'éléments de données primitifs et complexes, parmi lesquelles des variantes pour les entiers signés ([SWS_DM_02288]) et les sous-éléments structurés ([SWS_DM_02293]). Une interface équivalente est proposée en parallèle sur la classe DiagnosticSovdContentElementData ([SWS_DM_02369]).

La fonction membre synchrone Add de la classe ara::diag::DiagnosticSovdRecordContentElementDataView ajoute à un enregistrement de données une valeur primitive à virgule flottante de type double sous la clé spécifiée key [SWS_DM_02290]. La fonction sert à construire des données de diagnostic structurées pour la fonctionnalité de serveur SOVD du Diagnostic Management [SWS_DM_01369].

Les préconditions suivantes relatives aux types s'appliquent à l'exécution [SWS_DM_02290] :

• L'objet cible doit être de type RecordContentElementData ou ContentData.
• L'élément à ajouter ne doit pas être lui-même de type ContentData.

La méthode est déclarée comme noexcept (exception safe) et spécifiée comme sûre pour les threads (thread-safe) pour les accès concurrents [SWS_DM_02290]. Si l'ajout échoue – par exemple parce que le type d'objet est incompatible ou que l'élément ne peut pas être inséré –, une erreur est signalée via le ara::core::Result<void> renvoyé [SWS_DM_02290]. Interprétation : la cause exacte de l'erreur devrait alors être représentée dans le ara::core::ErrorCode de l'objet Result. Question Q-c987f75d785d3e90 (ouverte)

Conjointement avec les surcharges apparentées de Add, la méthode permet le remplissage structuré d'enregistrements de données SOVD avec des valeurs entières ([SWS_DM_02288], [SWS_DM_02289]), des valeurs booléennes [SWS_DM_02291], des chaînes de caractères [SWS_DM_02292] ou des données d'éléments plus complexes [SWS_DM_02293].

La fonction Add de la classe ara::diag::DiagnosticSovdRecordContentElementDataView sert à ajouter une valeur primitive booléenne sous une clé spécifiée à un élément de données SOVD [SWS_DM_02291]. L'appel s'effectue via le fichier d'en-tête ara/diag/diagnostic_sovd_content_element_data.h avec le nom de paramètre key de type ara::core::StringView ainsi que la valeur de données utiles content_element de type bool [SWS_DM_02291]. Étant donné que la méthode renvoie immédiatement un ara::core::Result<void> et qu'aucune asynchronie n'est spécifiée, l'opération devrait se dérouler de manière synchrone. Question Q-a16b08bf68f8590b (ouverte)

Le traitement des erreurs s'effectue via le ara::core::Result<void> renvoyé. Une erreur est signalée si le DiagnosticSovdContentElementData sous-jacent n'est ni de type RecordContentElementData ni de type ContentData, ou si l'élément ne peut pas être ajouté [SWS_DM_02291]. Des codes d'erreur spécifiques ne sont pas détaillés dans l'extrait de spécification.

En matière de concurrence et de sécurité d'exécution, la méthode est classée comme thread-safe et offre une sécurité vis-à-vis des exceptions (noexcept) [SWS_DM_02291]. Comme contrainte structurelle, la spécification exige que l'élément à ajouter ne soit pas lui-même de type ContentData [SWS_DM_02291].

Dans le système global, cette méthode complète des surcharges apparentées pour les entiers signés [SWS_DM_02288], les entiers non signés [SWS_DM_02289], les nombres à virgule flottante [SWS_DM_02290], les chaînes de caractères [SWS_DM_02292] ainsi que les éléments de contenu subordonnés [SWS_DM_02293]. De plus, l'interface analogue existe sur la classe DiagnosticSovdContentElementData [SWS_DM_02371] dans le contexte de la fonctionnalité de serveur SOVD du Diagnostic Management [SWS_DM_01369].

Utilisation

La méthode synchrone Add de la classe ara::diag::DiagnosticSovdRecordContentElementDataView sert à ajouter une entrée comportant une clé et une valeur primitive de chaîne de caractères à un élément de données SOVD [SWS_DM_02292]. L'appel s'effectue via les deux paramètres key et content_element, qui sont chacun transmis en tant que ara::core::StringView [SWS_DM_02292]. Comme valeur de retour, la fonction fournit un ara::core::Result<void> pour signaler le résultat de l'opération [SWS_DM_02292].

Gestion des erreurs

Si l'ajout échoue, la méthode renvoie une erreur dans le ara::core::Result [SWS_DM_02292]. Cela se produit lorsque l'objet sous-jacent n'est pas de type RecordContentElementData ou ContentData, ou si l'élément ne peut pas être ajouté [SWS_DM_02292]. Interprétation : les codes d'erreur concrets devraient être déterminés par le domaine d'erreur associé de l'implémentation, car la spécification ne les énumère pas explicitement dans la définition de la fonction. Question Q-ba196615f0cd8fc8 (ouverte)

Concurrence et contraintes

L'opération est déclarée comme thread-safe (thread-safe) ainsi que sûre vis-à-vis des exceptions (exception safe) et est annotée avec noexcept [SWS_DM_02292]. Comme précondition essentielle, l'élément transmis comme paramètre ne doit pas être lui-même de type ContentData [SWS_DM_02292].

Interaction

La fonction fait partie du Diagnostic Management (DM) d'AUTOSAR pour la réalisation de SOVD pour l'Adaptive Platform AUTOSAR_AP_SWS_Diagnostics §1 « Introduction and functional overview », le DM agissant en tant que serveur SOVD [SWS_DM_01369]. Pour la même portée, il existe des surcharges analogues de Add pour les entiers signés [SWS_DM_02288], les entiers non signés [SWS_DM_02289], les nombres à virgule flottante [SWS_DM_02290], les valeurs booléennes [SWS_DM_02291] ainsi que les éléments de données complexes [SWS_DM_02293]. De plus, ara::diag::DiagnosticSovdContentElementData met à disposition une surcharge correspondante pour les chaînes de caractères [SWS_DM_02372].

La fonction synchrone Add de la classe ara::diag::DiagnosticSovdRecordContentElementDataView ajoute un élément imbriqué de type DiagnosticSovdContentElementData sous la clé key indiquée à un élément de données [SWS_DM_02293]. Cela sert à la mise à disposition structurée de données de diagnostic dans le cadre de SOVD (Service-Oriented Vehicle Diagnostics), qui est pris en charge par le Diagnostic Management (DM) sur l'Adaptive Platform ([SWS_DM_01369], AUTOSAR_AP_SWS_Diagnostics §1 « Introduction and functional overview »).

Lors de l'utilisation, des prescriptions de type impératives doivent être respectées :

• L'objet de données appelant doit être de type RecordContentElementData ou ContentData [SWS_DM_02293].
• L'élément à ajouter content_element ne doit explicitement pas être de type ContentData [SWS_DM_02293].
• En complément des structures de données complexes, des surcharges distinctes sont disponibles pour les valeurs élémentaires, par exemple pour les valeurs entières ([SWS_DM_02288], [SWS_DM_02289]), les nombres à virgule flottante [SWS_DM_02290], les valeurs booléennes [SWS_DM_02291] ou les chaînes de caractères [SWS_DM_02292], telles qu'elles sont également définies sur DiagnosticSovdContentElementData [SWS_DM_02373].

Pour la gestion des erreurs, la fonction renvoie un ara::core::Result<void>. Si l'opération échoue – par exemple parce que les prérequis de type sont violés ou que l'élément ne peut pas être inséré –, le résultat contient une erreur [SWS_DM_02293]. Le codage exact de l'erreur devrait vraisemblablement reposer sur des erreurs spécifiques au domaine de la gestion du diagnostic. Question Q-56c929209d0c7358 (ouverte) En ce qui concerne la concurrence et la sécurité, la méthode est déclarée comme noexcept, est considérée comme sans danger au niveau des exceptions (exception safe) et est spécifiée comme sûre pour les threads (thread-safe) pour l'accès concurrent [SWS_DM_02293].

Utilisation et sémantique

La méthode Clear de la classe ara::diag::DiagnosticSovdRecordContentElementDataView sert à la suppression synchrone de tous les éléments de contenu d'un RecordContentElementData [SWS_DM_02276]. L'appel s'effectue sans paramètre via l'en-tête #include "ara/diag/diagnostic_sovd_content_element_data.h" et ne possède pas de valeur de retour (void) [SWS_DM_02276].

Comme précondition pour l'exécution, il est défini que l'instance de données sous-jacente doit être de type RecordContentElementData ou ContentData [SWS_DM_02276]. Interprétation : la fonction étant déclarée comme noexcept et ne signalant aucun état d'erreur, le respect de ce type de données devrait déjà être garanti en amont lors de la création de l'objet vue. Question Q-93e43eee235a8f12 (ouverte)

Gestion des erreurs et concurrence

En ce qui concerne la sûreté d'exécution, la méthode est spécifiée comme exception safe et ne lève aucune exception grâce à la déclaration noexcept [SWS_DM_02276]. L'appel est en outre explicitement classé comme thread-safe, de sorte que les accès concurrents sont autorisés [SWS_DM_02276].

Interaction et délimitation

Dans l'environnement SOVD, cette fonction se distingue de la méthode Clear sur DiagnosticSovdContentElementData [SWS_DM_02338], qui est définie pour les éléments de tableau et fournit un ara::core::Result<void>. De même, il existe une distinction fonctionnelle par rapport à la méthode de vue pour les tableaux [SWS_DM_02233] ainsi que par rapport à la suppression asynchrone de DTC via ara::diag::DTCInformation::Clear, qui renvoie un ara::core::Future<void> et n'est pas thread-safe [SWS_DM_00671].

La fonction membre Erase de la classe ara::diag::DiagnosticSovdRecordContentElementDataView sert à supprimer un élément de contenu subordonné d'un record de données de diagnostic ([SWS_DM_02294], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.14 « Erase »). La déclaration est mise à disposition via l'en-tête #include "ara/diag/diagnostic_sovd_content_element_data.h" ([SWS_DM_02294]).

Utilisation et sémantique : en tant que paramètre d'entrée, la fonction prend l'itérateur iterator de type DiagnosticSovdRecordContentElementDataIterator qui référence l'élément concret à supprimer ([SWS_DM_02294]). Interprétation : la fonction étant déclarée avec noexcept et renvoyant directement ara::core::Result<void> au lieu d'un objet future, le processus de suppression devrait être exécuté de manière synchrone dans le thread de l'appelant. Question Q-148ae95c28910b16 (ouverte) En cas d'exécution réussie, la méthode renvoie un ara::core::Result<void> vide ([SWS_DM_02294]).

Gestion des erreurs : l'opération échoue si l'élément de données concerné n'est ni du type RecordContentElementData ni du type ContentData ou si l'élément n'a pas pu être retiré du conteneur ([SWS_DM_02294]). Dans ces cas d'erreur, la fonction renvoie une erreur avec le code d'erreur DiagErrc::kInvalidArgument ([SWS_DM_02294]).

Concurrence et interaction : pour l'appel, l'interface est spécifiée comme thread-safe ainsi qu'exception safe ([SWS_DM_02294]). Sur le plan fonctionnel, la fonction correspond à la variante pour tableau ara::diag::DiagnosticSovdArrayContentElementDataView::Erase ([SWS_DM_02247], AUTOSAR_AP_SWS_Diagnostics §8.60.5.1.1.8 « Erase ») et interagit avec les opérations élémentaires de suppression de la classe de conteneur DiagnosticSovdContentElementData pour les tableaux ([SWS_DM_02352]) et les records ([SWS_DM_02374]).

La fonction membre synchrone Find de la classe View ara::diag::DiagnosticSovdRecordContentElementDataView sert à trouver un élément à l'aide de sa clé ([SWS_DM_02285], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.15 « Find »). Le paramètre transmis est key de type ara::core::StringView ; comme résultat, la fonction fournit un itérateur modifiable de type DiagnosticSovdRecordContentElementDataIterator ([SWS_DM_02285]). La condition préalable à l'utilisation est que le DiagnosticSovdContentElementData associé soit de type RecordContentElementData ou ContentData ([SWS_DM_02285]).

Concernant la gestion des erreurs et la concurrence, la fonction est déclarée comme noexcept, considérée comme sûre vis-à-vis des exceptions (exception safe) et est, selon la spécification, sûre pour les threads (thread-safe) ([SWS_DM_02285]). Étant donné que le type de retour est directement un itérateur et non un ara::core::Result, la fonction ne signale aucun code d'erreur spécifique ; si la clé recherchée n'existe pas, un itérateur de fin (end iterator) devrait vraisemblablement être renvoyé. Question Q-a34054c9851517ae (ouverte)

En interaction avec les interfaces associées, il existe sur la même classe View une surcharge constante ([SWS_DM_02286], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.16 « Find ») qui renvoie un DiagnosticSovdRecordContentElementDataConstIterator. La classe DiagnosticSovdRecordContentElementDataConstView propose également une interface constante analogue ([SWS_DM_02306], AUTOSAR_AP_SWS_Diagnostics §8.60.9.1.1.7 « Find »). En revanche, la méthode Find sur DiagnosticSovdContentElementData encapsule son itérateur dans un ara::core::Result afin de représenter les types non valides ou les clés manquantes sous forme d'erreurs ([SWS_DM_02365], [SWS_DM_02366], AUTOSAR_AP_SWS_Diagnostics §8.60.6.1.2.25 « Find »).

La fonction membre synchrone Find de la classe ara::diag::DiagnosticSovdRecordContentElementDataView sert à la recherche en lecture seule d'un élément de données à partir de sa clé ([SWS_DM_02286], AUTOSAR AP SWS Diagnostics §8.60.11.1.1.16 « Find »).

Utilisation et paramètres

La fonction prend en paramètre la clé recherchée key en tant que ara::core::StringView ([SWS_DM_02286]). La condition préalable à l'appel est que l'instance soit du type de diagnostic RecordContentElementData ou ContentData ([SWS_DM_02286]). Comme valeur de retour, elle fournit de manière synchrone un itérateur constant de type DiagnosticSovdRecordContentElementDataConstIterator ([SWS_DM_02286]). Si aucun élément correspondant à la clé n'existe, un itérateur marquant la fin de la séquence devrait probablement être renvoyé (interprétation). Question Q-41a1eba77c0bc236 (ouverte)

Gestion des erreurs et concurrence

L'interface est déclarée avec noexcept, garantit la sécurité vis-à-vis des exceptions (exception safe) et est spécifiée comme sûre pour les threads (thread-safe) pour l'accès concurrent ([SWS_DM_02286]). Contrairement à la méthode sur ara::diag::DiagnosticSovdContentElementData ([SWS_DM_02366]), aucun retour n'a lieu via ara::core::Result, raison pour laquelle les cas d'erreur ne sont pas représentés par des codes d'erreur.

Interaction

Pour les accès en écriture ou de modification sur la même vue, il existe la surcharge non constante [SWS_DM_02285] avec un itérateur modifiable. Pour les vues en lecture pure, la classe DiagnosticSovdRecordContentElementDataConstView fournit une fonction Find analogue ([SWS_DM_02306]).

La fonction membre synchrone Remove de la classe ara::diag::DiagnosticSovdRecordContentElementDataView sert à supprimer de manière ciblée une entrée à l'aide de sa clé [SWS_DM_02287]. Elle est définie dans l'en-tête ara/diag/diagnostic_sovd_content_element_data.h et traite le paramètre key de type ara::core::StringView AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.19 « Remove ».

Comme valeur de retour, la fonction fournit un ara::core::Result<bool> [SWS_DM_02287] :

• En cas de succès, la valeur booléenne contenue indique si l'élément ciblé a effectivement pu être supprimé.
• Une erreur est signalée via le ara::core::Result si l'élément n'est pas de type RecordContentElementData ou ContentData ou si la clé spécifiée n'a pas été trouvée [SWS_DM_02287].

Concernant la concurrence et les restrictions, la fonction est spécifiée comme sûre vis-à-vis des exceptions (exception safe) et thread-safe (thread-safe), et est déclarée avec noexcept [SWS_DM_02287]. Comme condition d'appel, la spécification exige impérativement que l'instance sous-jacente soit de type RecordContentElementData ou ContentData [SWS_DM_02287].

Interprétation : sur le plan fonctionnel, l'opération devrait correspondre à la suppression sur la classe de données ara::diag::DiagnosticSovdContentElementData::Remove [SWS_DM_02367], dans la mesure où la signature, les paramètres et les scénarios d'erreur sont spécifiés de manière totalement identique AUTOSAR_AP_SWS_Diagnostics §8.60.6.1.2.54 « Remove ». Question Q-5a9ac29a9b5814be (ouverte)

La méthode Reserve de la classe ara::diag::DiagnosticSovdRecordContentElementDataView ([SWS_DM_02283], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.20 « Reserve ») réserve de manière synchrone la capacité mémoire souhaitée pour RecordContentElementData. L'appel est mis à disposition via l'en-tête #include "ara/diag/diagnostic_sovd_content_element_data.h" et prend le paramètre capacity de type std::size_t. La fonction renvoie void comme valeur de retour.

L'interface est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (« exception safe ») ([SWS_DM_02283]). Ni codes d'erreur spécifiques ni structures d'erreur ne sont renvoyés. Interprétation : si l'allocation de la capacité requise échoue, l'erreur devrait, en l'absence d'un canal de retour tel que ara::core::Result, être interceptée en interne ou conduire à un arrêt du programme. Question Q-ddbaac36f8ed58ad (ouverte)

Concernant la concurrence, la fonction est définie comme sûre pour les threads (« thread-safe ») ([SWS_DM_02283]). Elle peut donc être appelée en parallèle et sans mesures de synchronisation supplémentaires depuis plusieurs threads.

En interaction avec des interfaces apparentées, la variante pour tableau DiagnosticSovdArrayContentElementDataView::Reserve ([SWS_DM_02240]) se comporte de manière analogue. Par opposition, DiagnosticSovdContentElementData::Reserve ([SWS_DM_02345]) renvoie un ara::core::Result<void> pour signaler des conflits de type. La fonction DiagnosticServiceDynamicAccessList::Reserve ([SWS_DM_01163]) sert quant à elle à une préallocation au pire des cas pour des modèles de service, attend deux paramètres et n'est pas thread-safe.