class ara::diag::ClientAuthenticationHandle

Die Methode Append der Klasse ara::diag::ClientAuthenticationHandle wird von Anwendungen genutzt, um eine dynamische Zugriffsliste (dynamicAccessList) an die bereits bestehende DynamicAccessList einer aktiven Diagnosekonversation anzufügen [SWS_DM_01152]. Die Schnittstelle wird über den Header ara/diag/client_authentication_handle.h bereitgestellt AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.1 „Append“.

Der Aufruf wird synchron ausgeführt und ist als noexcept spezifiziert [SWS_DM_01152]. Als Eingabeparameter nimmt die Funktion eine DiagnosticServiceDynamicAccessList entgegen. Der Rückgabetyp ara::core::Result<void> signalisiert den erfolgreichen Abschluss oder transportiert im Fehlerfall den Fehlercode DiagErrc::kServiceNotAvailable [SWS_DM_01152]. Letzterer weist darauf hin, dass wesentliche Funktionen des Diagnostic Management derzeit nicht verfügbar sind. Für diesen Fehlerfall gilt eine Rollback-Semantik, sodass der vorherige Zustand der Zugriffsliste erhalten bleibt [SWS_DM_01152].

In Bezug auf Nebenläufigkeit gilt die Operation als ausnahmesicher (exception safe), ist aber ausdrücklich als nicht threadsicher (not thread-safe) klassifiziert [SWS_DM_01152]. Bei parallelen Zugriffen auf dasselbe Handle-Objekt dürfte somit eine externe Synchronisation durch die aufrufende Anwendung notwendig sein. Frage Q-f0da9a0538a86a16 (offen)

Der synchrone Standardkonstruktor [SWS_DM_01146] erzeugt eine Instanz der Klasse ara::diag::ClientAuthenticationHandle. Der Aufruf nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert. Die Funktion ist als noexcept deklariert und als threadsicher (thread-safe) sowie ausnahmesicher spezifiziert [SWS_DM_01146], sodass bei der Erzeugung keine Fehlercodes oder Exceptions auftreten.

Für die Weitergabe und den Lebenszyklus des erzeugten Objekts gelten folgende Einschränkungen:

• Kopierkonstruktion und Kopierzuweisung sind explizit gelöscht ([SWS_DM_01150], [SWS_DM_01151]).
• Move-Konstruktor [SWS_DM_01148] und Move-Zuweisungsoperator [SWS_DM_01149] werden unterstützt.
• Sämtliche Instanzmethoden wie Set [SWS_DM_01153], Append [SWS_DM_01152], Revoke [SWS_DM_01154] sowie der Destruktor [SWS_DM_01147] sind als nicht threadsicher (not thread-safe) definiert.

Im Gesamtsystem stellt der Diagnostic Server aktive, an einen Client gebundene Handles regulär über Authenticate [SWS_DM_01142] oder OverrideDefaultRoles [SWS_DM_01141] bereit (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 „ClientAuthenticationHandle“). Ein über den Standardkonstruktor erzeugtes Exemplar dürfte daher als ungebundener Platzhalter dienen, der erst durch anschließende Move-Zuweisung [SWS_DM_01149] ein gültiges Handle zur Steuerung der Zugriffslisten aufnimmt. Frage Q-ce182402bd1d4072 (offen)

Die Methode Refresh der Klasse ara::diag::ClientAuthenticationHandle (Header-Datei #include "ara/diag/client_authentication_handle.h") dient einer Anwendung dazu, aktive Authentifizierungs- oder Rollen-Timer zu verlängern (AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.2 „Refresh“). Sie setzt den Timer zurück, der zuvor durch Authenticate oder OverrideDefaultRoles gestartet wurde. Falls zuvor beide Methoden aufgerufen wurden, werden durch den Aufruf beide Timer gleichzeitig erneuert [SWS_DM_01155].

Der synchrone Aufruf (Interpretation: direkte Rückgabe ohne asynchronen Future) erfolgt parameterlos auf einer bestehenden Instanz von ClientAuthenticationHandle, welche die Anwendung nach erfolgreichem Abschluss von Authenticate oder OverrideDefaultRoles vom Diagnostic Server erhalten hat (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 „ClientAuthenticationHandle“). Frage Q-b07e81ff4629ada7 (offen) Die Funktion ist als noexcept deklariert und ausnahmesicher (exception safe), jedoch als nicht threadsicher (not thread-safe) spezifiziert [SWS_DM_01155]. Nebenläufige Aufrufe auf derselben Instanz müssen daher durch den Aufrufer synchronisiert werden.

Schlägt die Operation fehl, gibt die Funktion über ara::core::Result<void> den Fehlercode DiagErrc::kServiceNotAvailable zurück [SWS_DM_01155]. Dies zeigt über Rollback-Semantik an, dass der Aufruf nicht ausgeführt werden konnte, weil essenzielle Funktionalitäten des Diagnostic Management (DM) zurzeit nicht verfügbar sind [SWS_DM_01155].

Die synchrone Methode Revoke der Klasse ara::diag::ClientAuthenticationHandle (SWS Diagnostics §8.6.1.1.3.3 „Revoke“) dient Anwendungen dazu, einen zuvor authentifizierten Diagnose-Client zu deauthentifizieren sowie dessen dynamische Zugriffsliste (DynamicAccessList) und überschriebene Standardrollen vollständig zu verwerfen ([SWS_DM_01154], [SWS_DM_01216]).

Die Funktion besitzt keine Übergabeparameter und gibt ein ara::core::Result<void> zurück ([SWS_DM_01154]). Im Erfolgsfall wird der Authentifizierungsstatus des Clients beendet. Ist eine essenzielle Funktionalität des Diagnostic Managers zum Aufrufzeitpunkt nicht verfügbar, schlägt die Operation fehl und liefert den Fehler DiagErrc::kServiceNotAvailable mit Rollback-Semantik ([SWS_DM_01154]).

Hinsichtlich der Nebenläufigkeit ist die Schnittstelle als ausnahmesicher (exception safe), jedoch als nicht threadsicher (not thread-safe) spezifiziert ([SWS_DM_01154]). Interpretation: Bei nebenläufigen Zugriffen auf dieselbe Handle-Instanz aus mehreren Threads dürfte die aufrufende Anwendung daher eine externe Synchronisation sicherstellen müssen. Frage Q-8781261c9a2f5f8e (offen)

Im Gesamtablauf wird die Instanz von ClientAuthenticationHandle der Anwendung nach erfolgreicher Authentifizierung oder nach dem Überschreiben von Standardrollen durch die Diagnose-Server-Instanz bereitgestellt (SWS Diagnostics §7.3.2.3.3 „ClientAuthenticationHandle“). Während der aktive Handle neben dem Widerruf auch das Ersetzen ([SWS_DM_01213]) oder Erweitern ([SWS_DM_01215]) der DynamicAccessList erlaubt, beendet Revoke diese Berechtigungen des Clients endgültig.

Die synchrone Methode Set der Klasse ara::diag::ClientAuthenticationHandle ([SWS_DM_01153]) dient einer Applikation dazu, die dynamische Zugriffsliste (DynamicAccessList) für eine Diagnose-Konversation bzw. einen authentifizierten Client im Diagnostic Server zu setzen oder vollständig zu ersetzen ([SWS_DM_01213]). Der Diagnostic Manager führt für jeden authentifizierten Client eine solche DynamicAccessList, die dem Client über die im Diagnostic Extract hinterlegte Konfiguration hinaus zusätzliche Zugriffsrechte auf Diagnose-Ressourcen einräumen kann (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 „ClientAuthenticationHandle“).

Bei der Verwendung sind folgende Aspekte maßgeblich:

• Aufrufkontext und Parameter: Die Funktion wird an einer Instanz von ara::diag::ClientAuthenticationHandle aufgerufen (deklariert in #include "ara/diag/client_authentication_handle.h"). Eine solche Handle-Instanz wird der Applikation bereitgestellt, wenn zuvor entweder ara::diag::ClientAuthentication::Authenticate ([SWS_DM_01206]) oder ara::diag::ClientAuthentication::OverrideDefaultRoles ([SWS_DM_01209]) erfolgreich abgeschlossen wurde. Als einziger Übergabeparameter wird dynamicAccessList vom Typ DiagnosticServiceDynamicAccessList übergeben, welche die neue Zugriffsliste definiert ([SWS_DM_01153]).
• Rückgabewert und Fehlerbehandlung: Die Methode ist als noexcept spezifiziert und liefert ein ara::core::Result<void> zurück. Sie arbeitet mit Rollback-Semantik: Kann der Aufruf nicht ausgeführt werden, weil essenzielle DM-Funktionalität aktuell nicht verfügbar ist, schlägt der Aufruf mit dem Fehlercode DiagErrc::kServiceNotAvailable fehl ([SWS_DM_01153]). Hinsichtlich der Ausnahmebehandlung ist die Methode als ausnahmesicher (exception safe) eingestuft.
• Nebenläufigkeit: Die Operation ist explizit als nicht threadsicher (not thread-safe) definiert ([SWS_DM_01153]). Werden Aufrufe an derselben Handle-Instanz nebenläufig aus mehreren Threads heraus getätigt, obliegt die notwendige Synchronisation der Applikation.

Verwendung und Semantik

Die Funktion ~ClientAuthenticationHandle() ist der Destruktor der Klasse ara::diag::ClientAuthenticationHandle und wird über die Header-Datei ara/diag/client_authentication_handle.h deklariert ([SWS_DM_01147], AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.1.3 „Destructor“). Er nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert. Der Aufruf erfolgt üblicherweise implizit bei Beendigung der Lebensdauer des Objekts. Interpretation: Dabei dürften alle intern durch das Handle gebundenen Ressourcen der Client-Authentifizierung freigegeben werden. Frage Q-ea8f47232fd9951f (offen)

Fehlerbehandlung und Exception-Sicherheit

Der Destruktor ist als noexcept deklariert und explizit als exception safe spezifiziert ([SWS_DM_01147]). Während der Zerstörung des Objekts werden folglich keine C++-Exceptions ausgelöst und keine spezifischen Fehlercodes zurückgemeldet, sodass der Bereinigungsvorgang garantiert fehlerfrei abschließt.

Nebenläufigkeit und Einschränkungen

Die Zerstörung eines ClientAuthenticationHandle ist gemäß Spezifikation als not thread-safe eingestuft ([SWS_DM_01147]). Die aufrufende Anwendung hat sicherzustellen, dass keine anderen Threads parallel auf dieselbe Instanz zugreifen, während der Destruktor ausgeführt wird.