klasse ara::diag::ClientAuthenticationHandle

De methode Append van de klasse ara::diag::ClientAuthenticationHandle wordt door applicaties gebruikt om een dynamische toegangslijst (dynamicAccessList) toe te voegen aan de reeds bestaande DynamicAccessList van een actieve diagnoseconversatie [SWS_DM_01152]. De interface wordt beschikbaar gesteld via de header ara/diag/client_authentication_handle.h AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.1 “Append”.

De aanroep wordt synchroon uitgevoerd en is gespecificeerd als noexcept [SWS_DM_01152]. Als invoerparameter accepteert de functie een DiagnosticServiceDynamicAccessList. Het retourtype ara::core::Result<void> signaleert de succesvolle afronding of transporteert bij een fout de foutcode DiagErrc::kServiceNotAvailable [SWS_DM_01152]. Deze laatste geeft aan dat essentiële functies van Diagnostic Management momenteel niet beschikbaar zijn. Voor dit foutgeval geldt een rollback-semantiek, zodat de eerdere toestand van de toegangslijst behouden blijft [SWS_DM_01152].

Met betrekking tot gelijktijdigheid geldt de operatie als uitzonderingsveilig (exception safe), maar is deze uitdrukkelijk geclassificeerd als niet threadveilig (not thread-safe) [SWS_DM_01152]. Bij parallelle toegang tot hetzelfde handle-object is externe synchronisatie door de aanroepende applicatie dan ook vermoedelijk vereist. Vraag Q-f0da9a0538a86a16 (open)

De synchrone standaardconstructor [SWS_DM_01146] genereert een instantie van de klasse ara::diag::ClientAuthenticationHandle. De aanroep accepteert geen overdrachtsparameters en levert geen retourwaarde op. De functie is gedeclareerd als noexcept en gespecificeerd als thread-safe (thread-safe) en uitzonderingsveilig [SWS_DM_01146], zodat bij het aanmaken geen foutcodes of exceptions optreden.

Voor de doorgifte en de levenscyclus van het aangemaakte object gelden de volgende beperkingen:

• Copy-constructie en copy-toewijzing zijn expliciet verwijderd ([SWS_DM_01150], [SWS_DM_01151]).
• Move-constructor [SWS_DM_01148] en move-toewijzingsoperator [SWS_DM_01149] worden ondersteund.
• Alle instantiemethoden zoals Set [SWS_DM_01153], Append [SWS_DM_01152], Revoke [SWS_DM_01154] evenals de destructor [SWS_DM_01147] zijn gedefinieerd als niet thread-safe (not thread-safe).

In het totale systeem stelt de Diagnostic Server actieve, aan een client gebonden handles regulier beschikbaar via Authenticate [SWS_DM_01142] of OverrideDefaultRoles [SWS_DM_01141] (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”). Een via de standaardconstructor gegenereerd exemplaar dient daarom vermoedelijk als een niet-gebonden tijdelijke aanduiding, die pas door een daaropvolgende move-toewijzing [SWS_DM_01149] een geldige handle opneemt om de toegangslijsten te beheren. Vraag Q-ce182402bd1d4072 (open)

De methode Refresh van de klasse ara::diag::ClientAuthenticationHandle (headerbestand #include "ara/diag/client_authentication_handle.h") dient er voor een applicatie toe om actieve authenticatie- of rollentimers te verlengen (AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.2 “Refresh”). Ze reset de timer die eerder door Authenticate of OverrideDefaultRoles is gestart. Indien eerder beide methoden werden aangeroepen, worden door de aanroep beide timers gelijktijdig vernieuwd [SWS_DM_01155].

De synchrone aanroep (interpretatie: directe teruggave zonder asynchrone future) vindt parameterloos plaats op een bestaande instantie van ClientAuthenticationHandle, die de applicatie na succesvolle afronding van Authenticate of OverrideDefaultRoles van de Diagnostic Server heeft ontvangen (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”). Vraag Q-b07e81ff4629ada7 (open) De functie is gedeclareerd als noexcept en uitzonderingsveilig (exception safe), maar gespecificeerd als niet-draadveilig (not thread-safe) [SWS_DM_01155]. Gelijktijdige aanroepen op dezelfde instantie moeten daarom door de aanroeper worden gesynchroniseerd.

Mislukt de operatie, dan retourneert de functie via ara::core::Result<void> de foutcode DiagErrc::kServiceNotAvailable [SWS_DM_01155]. Dit geeft via rollback-semantiek aan dat de aanroep niet kon worden uitgevoerd omdat essentiële functionaliteiten van Diagnostic Management (DM) momenteel niet beschikbaar zijn [SWS_DM_01155].

De synchrone methode Revoke van de klasse ara::diag::ClientAuthenticationHandle (SWS Diagnostics §8.6.1.1.3.3 “Revoke”) stelt applicaties in staat om een eerder geauthentiseerde diagnoseclient te deauthentiseren en diens dynamische toegangslijst (DynamicAccessList) en overschreven standaardrollen volledig te verwerpen ([SWS_DM_01154], [SWS_DM_01216]).

De functie heeft geen invoerparameters en geeft een ara::core::Result<void> terug ([SWS_DM_01154]). In het geval van succes wordt de authenticatiestatus van de client beëindigd. Is een essentiële functionaliteit van de Diagnostic Manager op het aanroeptijdstip niet beschikbaar, dan mislukt de operatie en levert deze de fout DiagErrc::kServiceNotAvailable op met rollback-semantiek ([SWS_DM_01154]).

Wat betreft gelijktijdigheid is de interface gespecificeerd als uitzonderingsveilig (exception safe), maar als niet threadveilig (not thread-safe) ([SWS_DM_01154]). Interpretatie: bij gelijktijdige toegang tot dezelfde handle-instantie vanuit meerdere threads moet de aanroepende applicatie vermoedelijk zorgen voor een externe synchronisatie. Vraag Q-8781261c9a2f5f8e (open)

In de algehele flow wordt de instantie van ClientAuthenticationHandle na succesvolle authenticatie of na het overschrijven van standaardrollen door de Diagnostic Server-instantie aan de applicatie beschikbaar gesteld (SWS Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”). Terwijl de actieve handle naast intrekking ook het vervangen ([SWS_DM_01213]) of uitbreiden ([SWS_DM_01215]) van de DynamicAccessList toestaat, beëindigt Revoke deze bevoegdheden van de client definitief.

De synchrone methode Set van de klasse ara::diag::ClientAuthenticationHandle ([SWS_DM_01153]) stelt een applicatie in staat om de dynamische toegangslijst (DynamicAccessList) voor een diagnoseconversatie c.q. een geauthentiseerde client in de Diagnostic Server in te stellen of volledig te vervangen ([SWS_DM_01213]). De Diagnostic Manager beheert voor elke geauthentiseerde client zo'n DynamicAccessList, die de client bovenop de in het Diagnostic Extract vastgelegde configuratie aanvullende toegangsrechten tot diagnoseresources kan verlenen (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”).

Bij het gebruik zijn de volgende aspecten van belang:

• Aanroepcontext en parameters: De functie wordt aangeroepen op een instantie van ara::diag::ClientAuthenticationHandle (gedeclareerd in #include "ara/diag/client_authentication_handle.h"). Een dergelijke handle-instantie wordt aan de applicatie beschikbaar gesteld wanneer vooraf hetzij ara::diag::ClientAuthentication::Authenticate ([SWS_DM_01206]) hetzij ara::diag::ClientAuthentication::OverrideDefaultRoles ([SWS_DM_01209]) succesvol is afgerond. Als enige invoerparameter wordt dynamicAccessList van het type DiagnosticServiceDynamicAccessList overgedragen, die de nieuwe toegangslijst definieert ([SWS_DM_01153]).
• Retourwaarde en foutafhandeling: De methode is gespecificeerd als noexcept en retourneert een ara::core::Result<void>. Zij werkt met rollback-semantiek: kan de aanroep niet worden uitgevoerd omdat essentiële DM-functionaliteit momenteel niet beschikbaar is, dan mislukt de aanroep met de foutcode DiagErrc::kServiceNotAvailable ([SWS_DM_01153]). Wat betreft exceptieafhandeling is de methode geclassificeerd als uitzonderingsveilig (exception safe).
• Gelijktijdigheid: De operatie is expliciet gedefinieerd als niet threadveilig (not thread-safe) ([SWS_DM_01153]). Worden aanroepen op dezelfde handle-instantie gelijktijdig vanuit meerdere threads uitgevoerd, dan rust de noodzakelijke synchronisatie op de applicatie.

Gebruik en semantiek

De functie ~ClientAuthenticationHandle() is de destructor van de klasse ara::diag::ClientAuthenticationHandle en wordt gedeclareerd via het headerbestand ara/diag/client_authentication_handle.h ([SWS_DM_01147], AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.1.3 “Destructor”). Deze accepteert geen overdrachtparameters en levert geen retourwaarde op. De aanroep vindt gewoonlijk impliciet plaats bij het beëindigen van de levensduur van het object. Interpretatie: hierbij worden vermoedelijk alle intern door de handle gebonden resources van de clientauthenticatie vrijgegeven. Vraag Q-ea8f47232fd9951f (open)

Foutafhandeling en exception-veiligheid

De destructor is gedeclareerd als noexcept en expliciet gespecificeerd als exception safe ([SWS_DM_01147]). Tijdens de vernietiging van het object worden er bijgevolg geen C++-exceptions gegenereerd en worden er geen specifieke foutcodes gerapporteerd, zodat het opschoonproces gegarandeerd foutloos wordt afgerond.

Gelijktijdigheid en beperkingen

De vernietiging van een ClientAuthenticationHandle is volgens de specificatie geclassificeerd als not thread-safe ([SWS_DM_01147]). De aanroepende applicatie moet ervoor zorgen dat er geen andere threads parallel toegang hebben tot dezelfde instantie terwijl de destructor wordt uitgevoerd.