class ara::diag::DiagnosticSovdRecordContentElementDataView

Verwendung

Die synchrone Funktion [SWS_DM_02288] fügt einen vorzeichenbehafteten Ganzzahlwert (std::int64_t) unter dem angegebenen Schlüssel key (ara::core::StringView) in eine SOVD-Datenstruktur ein. Sie ist als Methode der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView deklariert und über den Header ara/diag/diagnostic_sovd_content_element_data.h eingebunden.

Voraussetzungen und Fehlerbehandlung

Gemäß [SWS_DM_02288] muss das zugrunde liegende DiagnosticSovdContentElementData-Objekt vom Typ RecordContentElementData oder ContentData sein, während das hinzuzufügende Element selbst kein ContentData sein darf. Die Funktion ist als noexcept definiert und liefert ein ara::core::Result<void> zurück. Schlägt die Operation fehl – etwa weil der Zielcontainer einen inkompatiblen Typ besitzt oder das Element nicht hinzugefügt werden kann –, enthält das Ergebnis einen Fehlercode; Interpretation: Dies dürfte typischerweise auch bei Schlüsselkollisionen der Fall sein. Frage Q-524c832a794559b7 (offen)

Nebenläufigkeit und Zusammenspiel

Die Ausführung ist threadsicher und ausnahmesicher spezifiziert [SWS_DM_02288]. Innerhalb der Schnittstelle existieren typgleiche Überladungen für vorzeichenlose Ganzzahlen ([SWS_DM_02289]), Fließkommazahlen ([SWS_DM_02290]), boolesche Werte ([SWS_DM_02291]), Zeichenketten ([SWS_DM_02292]) sowie verschachtelte Datenelemente ([SWS_DM_02293]). Dieselbe Methode wird zudem auf der Trägerklasse DiagnosticSovdContentElementData bereitgestellt ([SWS_DM_02368]).

Die synchrone Memberfunktion Add der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem Hinzufügen eines vorzeichenlosen 64-Bit-Ganzzahlwerts unter einem vorgegebenen Schlüssel ([SWS_DM_02289]). Sie wird im Rahmen der SOVD-Funktionalität des Diagnostic Management eingesetzt, welche Diagnosekommunikation gemäß ASAM SOVD bereitstellt (AUTOSAR_AP_SWS_Diagnostics §1.0 „Introduction and functional overview“, [SWS_DM_01369]).

Verwendung und Aufruf

Die Methode wird über den Header ara/diag/diagnostic_sovd_content_element_data.h eingebunden. Als Parameter erwartet sie den Bezeichner key als ara::core::StringView sowie den hinzuzufügenden Wert content_element als std::uint64_t ([SWS_DM_02289]). Der Aufruf erfolgt synchron, ist als noexcept spezifiziert und gibt das Ergebnis in Form von ara::core::Result<void> zurück.

Fehlerbehandlung und Randbedingungen

• Typbedingungen: Das instanziierte DiagnosticSovdContentElementData muss entweder vom Typ RecordContentElementData oder ContentData sein. Zudem darf das hinzuzufügende Element selbst nicht vom Typ ContentData sein ([SWS_DM_02289]).
• Fehlerverhalten: Wird eine dieser Typanforderungen verletzt oder kann das Element nicht hinzugefügt werden, liefert die Funktion ein fehlerhaftes ara::core::Result zurück ([SWS_DM_02289]). Spezifische Fehlercodes nennt die Spezifikation an dieser Stelle nicht; vermutlich liefert das Result-Objekt einen entsprechenden Fehlercode der Diagnosedomäne. Frage Q-ffca131eece93b35 (offen)
• Nebenläufigkeit: Die Funktion ist explizit als thread-safe und exception safe spezifiziert ([SWS_DM_02289]).

Zusammenspiel

Die Methode gehört zu einer Familie typisierter Überladungen zur Erfassung primitiver und komplexer Datenelemente, darunter Varianten für vorzeichenbehaftete Ganzzahlen ([SWS_DM_02288]) und strukturierte Unterelemente ([SWS_DM_02293]). Eine gleichwertige Schnittstelle wird parallel auf der Klasse DiagnosticSovdContentElementData angeboten ([SWS_DM_02369]).

Die synchrone Elementfunktion Add der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView fügt einem Datensatz einen primitiven Gleitkommawert vom Typ double unter dem angegebenen Schlüssel key hinzu [SWS_DM_02290]. Die Funktion dient dem Aufbau strukturierter Diagnosedaten für die SOVD-Serverfunktionalität des Diagnostic Management [SWS_DM_01369].

Für die Ausführung gelten folgende typbezogene Vorbedingungen [SWS_DM_02290]:

• Das Zielobjekt muss vom Typ RecordContentElementData oder ContentData sein.
• Das hinzuzufügende Element darf selbst nicht vom Typ ContentData sein.

Die Methode ist als noexcept deklariert (exception safe) und für den nebenläufigen Zugriff als threadsicher (thread-safe) spezifiziert [SWS_DM_02290]. Scheitert das Hinzufügen – etwa weil der Objekttyp inkompatibel ist oder das Element nicht eingefügt werden kann –, wird ein Fehler über das zurückgegebene ara::core::Result<void> gemeldet [SWS_DM_02290]. Interpretation: Die genaue Fehlerursache dürfte dabei im ara::core::ErrorCode des Result-Objekts abgebildet werden. Frage Q-c987f75d785d3e90 (offen)

Im Verbund mit den verwandten Überladungen von Add ermöglicht die Methode das strukturierte Befüllen von SOVD-Datensätzen mit ganzzahligen Werten ([SWS_DM_02288], [SWS_DM_02289]), Wahrheitswerten [SWS_DM_02291], Zeichenketten [SWS_DM_02292] oder komplexeren Elementdaten [SWS_DM_02293].

Die Funktion Add der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem Hinzufügen eines booleschen primitiven Werts unter einem angegebenen Schlüssel zu einem SOVD-Datenelement [SWS_DM_02291]. Der Aufruf erfolgt über die Header-Datei ara/diag/diagnostic_sovd_content_element_data.h mit dem Parameternamen key vom Typ ara::core::StringView sowie dem Nutzdatenwert content_element vom Typ bool [SWS_DM_02291]. Da die Methode unmittelbar ein ara::core::Result<void> zurückgibt und keine Asynchronität spezifiziert ist, dürfte der Vorgang synchron ablaufen. Frage Q-a16b08bf68f8590b (offen)

Die Fehlerbehandlung erfolgt über das zurückgegebene ara::core::Result<void>. Ein Fehler wird zurückgemeldet, wenn das zugrunde liegende DiagnosticSovdContentElementData weder vom Typ RecordContentElementData noch ContentData ist oder das Element nicht hinzugefügt werden kann [SWS_DM_02291]. Spezifische Fehlercodes sind im Spezifikationsauszug nicht näher aufgeführt.

Hinsichtlich Nebenläufigkeit und Ausführungssicherheit ist die Methode als thread-safe klassifiziert und bietet Exception-Sicherheit (noexcept) [SWS_DM_02291]. Als strukturelle Einschränkung verlangt die Spezifikation, dass das hinzuzufügende Element selbst nicht vom Typ ContentData sein darf [SWS_DM_02291].

Im Gesamtsystem ergänzt diese Methode verwandte Überladungen für vorzeichenbehaftete Ganzzahlen [SWS_DM_02288], vorzeichenlose Ganzzahlen [SWS_DM_02289], Gleitkommazahlen [SWS_DM_02290], Zeichenketten [SWS_DM_02292] sowie untergeordnete Inhaltselemente [SWS_DM_02293]. Zudem existiert die analoge Schnittstelle an der Klasse DiagnosticSovdContentElementData [SWS_DM_02371] im Kontext der SOVD-Serverfunktionalität des Diagnostic Managements [SWS_DM_01369].

Verwendung

Die synchrone Methode Add der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem Hinzufügen eines Eintrags mit einem Schlüssel und einem primitiven Zeichenkettenwert zu einem SOVD-Datenelement [SWS_DM_02292]. Der Aufruf erfolgt über die beiden Parameter key sowie content_element, die jeweils als ara::core::StringView übergeben werden [SWS_DM_02292]. Als Rückgabewert liefert die Funktion ein ara::core::Result<void> zur Signalisierung des Operationsergebnisses [SWS_DM_02292].

Fehlerbehandlung

Schlägt das Hinzufügen fehl, liefert die Methode einen Fehler im ara::core::Result zurück [SWS_DM_02292]. Dies tritt auf, wenn das zugrunde liegende Objekt nicht vom Typ RecordContentElementData oder ContentData ist oder das Element nicht hinzugefügt werden kann [SWS_DM_02292]. Interpretation: Die konkreten Fehlercodes dürften durch die zugehörige Fehlerdomäne der Implementierung bestimmt werden, da die Spezifikation diese an der Funktionsdefinition nicht explizit aufzählt. Frage Q-ba196615f0cd8fc8 (offen)

Nebenläufigkeit und Randbedingungen

Die Operation ist als threadsicher (thread-safe) sowie als ausnahmesicher (exception safe) deklariert und mit noexcept annotiert [SWS_DM_02292]. Als wesentliche Vorbedingung gilt, dass das als Parameter übergebene Element selbst nicht vom Typ ContentData sein darf [SWS_DM_02292].

Zusammenspiel

Die Funktion ist Bestandteil des AUTOSAR Diagnostic Management (DM) zur Realisierung von SOVD für die Adaptive Platform AUTOSAR_AP_SWS_Diagnostics §1 „Introduction and functional overview“, wobei der DM als SOVD-Server agiert [SWS_DM_01369]. Für denselben Scope existieren analoge Überladungen von Add für vorzeichenbehaftete Ganzzahlen [SWS_DM_02288], vorzeichenlose Ganzzahlen [SWS_DM_02289], Fließkommazahlen [SWS_DM_02290], Boolesche Werte [SWS_DM_02291] sowie komplexe Datenelemente [SWS_DM_02293]. Zudem stellt ara::diag::DiagnosticSovdContentElementData eine entsprechende Zeichenketten-Überladung bereit [SWS_DM_02372].

Die synchrone Funktion Add der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView fügt einem Datenelement unter dem angegebenen Schlüssel key ein geschachteltes Element vom Typ DiagnosticSovdContentElementData hinzu [SWS_DM_02293]. Dies dient der strukturierten Bereitstellung von Diagnosedaten im Rahmen von SOVD (Service-Oriented Vehicle Diagnostics), das vom Diagnostic Management (DM) auf der Adaptive Platform unterstützt wird ([SWS_DM_01369], AUTOSAR_AP_SWS_Diagnostics §1 „Introduction and functional overview“).

Bei der Verwendung sind zwingende Typvorgaben einzuhalten:

• Das aufrufende Datenobjekt muss vom Typ RecordContentElementData oder ContentData sein [SWS_DM_02293].
• Das hinzuzufügende Element content_element darf explizit nicht vom Typ ContentData sein [SWS_DM_02293].
• Ergänzend zu komplexen Datenstrukturen stehen für elementare Werte separate Überladungen zur Verfügung, beispielsweise für Integer-Werte ([SWS_DM_02288], [SWS_DM_02289]), Fließkommazahlen [SWS_DM_02290], Wahrheitswerte [SWS_DM_02291] oder Zeichenketten [SWS_DM_02292], wie sie auch auf DiagnosticSovdContentElementData definiert sind [SWS_DM_02373].

Zur Fehlerbehandlung liefert die Funktion ein ara::core::Result<void> zurück. Schlägt die Operation fehl – etwa weil die Typvoraussetzungen verletzt sind oder das Element nicht eingefügt werden kann –, enthält das Ergebnis einen Fehler [SWS_DM_02293]. Die genaue Fehlerkodierung dürfte vermutlich auf domänenspezifischen Fehlern der Diagnoseverwaltung basieren. Frage Q-56c929209d0c7358 (offen) Hinsichtlich Nebenläufigkeit und Sicherheit ist die Methode als noexcept deklariert, gilt als ausnahmesicher (exception safe) und ist für den nebenläufigen Zugriff als threadsicher (thread-safe) spezifiziert [SWS_DM_02293].

Verwendung und Semantik

Die Methode Clear der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem synchronen Entfernen aller Inhaltselemente aus einem RecordContentElementData [SWS_DM_02276]. Der Aufruf erfolgt parameterlos über den Header #include "ara/diag/diagnostic_sovd_content_element_data.h" und besitzt keinen Rückgabewert (void) [SWS_DM_02276].

Als Voraussetzung für die Ausführung ist definiert, dass die zugrundeliegende Dateninstanz vom Typ RecordContentElementData oder ContentData sein muss [SWS_DM_02276]. Interpretation: Da die Funktion als noexcept deklariert ist und keinen Fehlerstatus meldet, dürfte die Einhaltung dieses Datentyps bereits vorab bei der Erstellung des View-Objekts sichergestellt sein. Frage Q-93e43eee235a8f12 (offen)

Fehlerbehandlung und Nebenläufigkeit

Hinsichtlich der Ausführungssicherheit ist die Methode als exception safe spezifiziert und löst durch die noexcept-Deklaration keine Exceptions aus [SWS_DM_02276]. Der Aufruf ist zudem explizit als thread-safe eingestuft, sodass nebenläufige Zugriffe zulässig sind [SWS_DM_02276].

Zusammenspiel und Abgrenzung

Im SOVD-Umfeld grenzt sich diese Funktion von der Methode Clear auf DiagnosticSovdContentElementData [SWS_DM_02338] ab, welche für Array-Elemente definiert ist und ein ara::core::Result<void> liefert. Ebenso besteht eine funktionale Unterscheidung zur View-Methode für Arrays [SWS_DM_02233] sowie zum asynchronen Löschen von DTCs über ara::diag::DTCInformation::Clear, das ein ara::core::Future<void> zurückgibt und nicht threadsicher ist [SWS_DM_00671].

Die Elementfunktion Erase der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem Entfernen eines untergeordneten Inhaltselements aus einem Diagnosedaten-Record ([SWS_DM_02294], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.14 „Erase“). Die Deklaration wird über den Header #include "ara/diag/diagnostic_sovd_content_element_data.h" bereitgestellt ([SWS_DM_02294]).

Verwendung und Semantik: Als Eingabeparameter übernimmt die Funktion den Iterator iterator vom Typ DiagnosticSovdRecordContentElementDataIterator, der auf das konkret zu löschende Element verweist ([SWS_DM_02294]). Interpretation: Da die Funktion mit noexcept deklariert ist und direkt ara::core::Result<void> statt eines Zukunftsobjekts zurückgibt, dürfte der Löschvorgang synchron im Thread des Aufrufers ausgeführt werden. Frage Q-148ae95c28910b16 (offen) Bei erfolgreicher Ausführung liefert die Methode ein leeres ara::core::Result<void> zurück ([SWS_DM_02294]).

Fehlerbehandlung: Die Operation schlägt fehl, wenn das betroffene Datenelement weder vom Typ RecordContentElementData noch ContentData ist oder das Element aus dem Container nicht entfernt werden konnte ([SWS_DM_02294]). In diesen Fehlerfällen gibt die Funktion einen Fehler mit dem Fehlercode DiagErrc::kInvalidArgument zurück ([SWS_DM_02294]).

Nebenläufigkeit und Zusammenspiel: Für den Aufruf ist die Schnittstelle als thread-safe sowie exception safe spezifiziert ([SWS_DM_02294]). Fachlich entspricht die Funktion der Array-Variante ara::diag::DiagnosticSovdArrayContentElementDataView::Erase ([SWS_DM_02247], AUTOSAR_AP_SWS_Diagnostics §8.60.5.1.1.8 „Erase“) und interagiert mit den elementaren Löschoperationen der Containerklasse DiagnosticSovdContentElementData für Arrays ([SWS_DM_02352]) und Records ([SWS_DM_02374]).

Die synchrone Memberfunktion Find der View-Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem Auffinden eines Elements anhand seines Schlüssels ([SWS_DM_02285], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.15 „Find“). Als Parameter wird key vom Typ ara::core::StringView übergeben; als Ergebnis liefert die Funktion einen modifizierbaren Iterator vom Typ DiagnosticSovdRecordContentElementDataIterator ([SWS_DM_02285]). Voraussetzung für die Nutzung ist, dass das zugehörige DiagnosticSovdContentElementData vom Typ RecordContentElementData oder ContentData ist ([SWS_DM_02285]).

Hinsichtlich der Fehlerbehandlung und Nebenläufigkeit ist die Funktion als noexcept deklariert, gilt als ausnahmesicher (exception safe) und ist laut Spezifikation threadsicher (thread-safe) ([SWS_DM_02285]). Da der Rückgabetyp direkt ein Iterator und kein ara::core::Result ist, meldet die Funktion keine spezifischen Fehlercodes; existiert der gesuchte Schlüssel nicht, dürfte vermutlich ein End-Iterator zurückgegeben werden. Frage Q-a34054c9851517ae (offen)

Im Zusammenspiel mit verwandten Schnittstellen existiert auf derselben View-Klasse eine konstante Überladung ([SWS_DM_02286], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.16 „Find“), welche einen DiagnosticSovdRecordContentElementDataConstIterator zurückgibt. Eine analoge konstante Schnittstelle bietet auch die Klasse DiagnosticSovdRecordContentElementDataConstView ([SWS_DM_02306], AUTOSAR_AP_SWS_Diagnostics §8.60.9.1.1.7 „Find“). Dagegen kapselt die Methode Find auf DiagnosticSovdContentElementData ihren Iterator in einem ara::core::Result, um ungültige Typen oder fehlende Schlüssel als Fehler abzubilden ([SWS_DM_02365], [SWS_DM_02366], AUTOSAR_AP_SWS_Diagnostics §8.60.6.1.2.25 „Find“).

Die synchrone Elementfunktion Find der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem schreibgeschützten Auffinden eines Datenelements anhand seines Schlüssels ([SWS_DM_02286], AUTOSAR AP SWS Diagnostics §8.60.11.1.1.16 „Find“).

Verwendung und Parameter

Die Funktion nimmt den gesuchten Schlüssel key als ara::core::StringView entgegen ([SWS_DM_02286]). Voraussetzung für den Aufruf ist, dass die Instanz vom Diagnosetyp RecordContentElementData oder ContentData ist ([SWS_DM_02286]). Als Rückgabewert liefert sie synchron einen konstanten Iterator vom Typ DiagnosticSovdRecordContentElementDataConstIterator ([SWS_DM_02286]). Falls kein zum Schlüssel passendes Element existiert, dürfte vermutlich ein Iterator zurückgegeben werden, der das Sequenzende markiert (Interpretation). Frage Q-41a1eba77c0bc236 (offen)

Fehlerbehandlung und Nebenläufigkeit

Die Schnittstelle ist mit noexcept deklariert, gewährleistet Ausnahmesicherheit (exception safe) und ist für den nebenläufigen Zugriff als threadsicher (thread-safe) spezifiziert ([SWS_DM_02286]). Anders als bei der Methode auf ara::diag::DiagnosticSovdContentElementData ([SWS_DM_02366]) erfolgt keine Rückgabe über ara::core::Result, weshalb Fehlerfälle nicht über Fehlercodes abgebildet werden.

Zusammenspiel

Für schreibende bzw. modifizierende Zugriffe auf dieselbe Sicht existiert die nicht-konstante Überladung [SWS_DM_02285] mit veränderbarem Iterator. Für reine Lese-Views stellt die Klasse DiagnosticSovdRecordContentElementDataConstView eine analoge Find-Funktion bereit ([SWS_DM_02306]).

Die synchrone Elementfunktion Remove der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView dient dem gezielten Entfernen eines Eintrags anhand seines Schlüssels [SWS_DM_02287]. Sie ist im Header ara/diag/diagnostic_sovd_content_element_data.h definiert und verarbeitet den Parameter key vom Typ ara::core::StringView AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.19 „Remove“.

Als Rückgabewert liefert die Funktion ein ara::core::Result<bool> [SWS_DM_02287]:

• Im Erfolgsfall signalisiert der enthaltene boolesche Wert, ob das adressierte Element tatsächlich entfernt werden konnte.
• Ein Fehler wird über das ara::core::Result zurückgemeldet, wenn das Element nicht vom Typ RecordContentElementData oder ContentData ist oder der angegebene Schlüssel nicht gefunden wurde [SWS_DM_02287].

Hinsichtlich Nebenläufigkeit und Einschränkungen ist die Funktion als ausnahmesicher (exception safe) und threadsicher (thread-safe) spezifiziert sowie mit noexcept deklariert [SWS_DM_02287]. Als Aufrufbedingung verlangt die Spezifikation zwingend, dass die zugrunde liegende Instanz vom Typ RecordContentElementData oder ContentData ist [SWS_DM_02287].

Interpretation: Funktional dürfte die Operation dem Entfernen auf der Datenklasse ara::diag::DiagnosticSovdContentElementData::Remove entsprechen [SWS_DM_02367], da Signatur, Parameter und Fehlerszenarien vollkommen deckungsgleich spezifiziert sind AUTOSAR_AP_SWS_Diagnostics §8.60.6.1.2.54 „Remove“. Frage Q-5a9ac29a9b5814be (offen)

Die Methode Reserve der Klasse ara::diag::DiagnosticSovdRecordContentElementDataView ([SWS_DM_02283], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.20 „Reserve“) reserviert synchron die gewünschte Speicherkapazität für RecordContentElementData. Der Aufruf wird über den Header #include "ara/diag/diagnostic_sovd_content_element_data.h" bereitgestellt und nimmt den Parameter capacity vom Typ std::size_t entgegen. Als Rückgabewert liefert die Funktion void.

Die Schnittstelle ist als noexcept deklariert und als ausnahmesicher („exception safe“) spezifiziert ([SWS_DM_02283]). Es werden weder spezifische Fehlercodes noch Fehlerstrukturen zurückgegeben. Interpretation: Schlägt die Allokation der geforderten Kapazität fehl, dürfte der Fehler mangels eines Rückgabekanals wie ara::core::Result intern abgefangen werden oder zu einem Programmabbruch führen. Frage Q-ddbaac36f8ed58ad (offen)

Bezüglich der Nebenläufigkeit ist die Funktion als threadsicher („thread-safe“) definiert ([SWS_DM_02283]). Sie kann somit parallel und ohne zusätzliche Synchronisationsmaßnahmen aus mehreren Threads aufgerufen werden.

Im Zusammenspiel mit verwandten Schnittstellen verhält sich die Array-Variante DiagnosticSovdArrayContentElementDataView::Reserve ([SWS_DM_02240]) analog. Im Unterschied dazu liefert DiagnosticSovdContentElementData::Reserve ([SWS_DM_02345]) ein ara::core::Result<void> zurück, um Typkonflikte zu melden. Die Funktion DiagnosticServiceDynamicAccessList::Reserve ([SWS_DM_01163]) dient hingegen einer Worst-Case-Vorallokation für Service-Patterns, erwartet zwei Parameter und ist nicht threadsicher.