class ara::diag::ClientAuthenticationHandle

The method Append of class ara::diag::ClientAuthenticationHandle is used by applications to append a dynamic access list (dynamicAccessList) to the already existing DynamicAccessList of an active diagnostic conversation [SWS_DM_01152]. The interface is provided via header ara/diag/client_authentication_handle.h AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.1 “Append”.

The call is executed synchronously and is specified as noexcept [SWS_DM_01152]. As an input parameter, the function accepts a DiagnosticServiceDynamicAccessList. The return type ara::core::Result<void> signals successful completion or, in the event of an error, carries error code DiagErrc::kServiceNotAvailable [SWS_DM_01152]. The latter indicates that essential functions of Diagnostic Management are currently not available. For this error case, rollback semantics apply, so that the previous state of the access list is preserved [SWS_DM_01152].

Regarding concurrency, the operation is considered exception safe (exception safe), but is explicitly classified as not thread-safe (not thread-safe) [SWS_DM_01152]. For parallel accesses to the same handle object, external synchronization by the calling application is therefore likely to be necessary. Question Q-f0da9a0538a86a16 (open)

The synchronous default constructor [SWS_DM_01146] creates an instance of class ara::diag::ClientAuthenticationHandle. The call accepts no input parameters and returns no return value. The function is declared as noexcept and specified as thread-safe (thread-safe) as well as exception safe [SWS_DM_01146], so that no error codes or exceptions occur during creation.

The following restrictions apply to the passing and life cycle of the created object:

• Copy construction and copy assignment are explicitly deleted ([SWS_DM_01150], [SWS_DM_01151]).
• Move constructor [SWS_DM_01148] and move assignment operator [SWS_DM_01149] are supported.
• All instance methods such as Set [SWS_DM_01153], Append [SWS_DM_01152], Revoke [SWS_DM_01154] as well as the destructor [SWS_DM_01147] are defined as not thread-safe (not thread-safe).

In the overall system, the Diagnostic Server regularly provides active handles bound to a client via Authenticate [SWS_DM_01142] or OverrideDefaultRoles [SWS_DM_01141] (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”). An instance created via the default constructor is therefore likely to serve as an unbound placeholder that only receives a valid handle for controlling access lists through subsequent move assignment [SWS_DM_01149]. Question Q-ce182402bd1d4072 (open)

The method Refresh of class ara::diag::ClientAuthenticationHandle (header file #include "ara/diag/client_authentication_handle.h") serves an application to extend active authentication or role timers (AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.2 “Refresh”). It resets the timer that was previously started by Authenticate or OverrideDefaultRoles. If both methods were called previously, calling it renews both timers simultaneously [SWS_DM_01155].

The synchronous call (interpretation: direct return without asynchronous future) occurs parameterless on an existing instance of ClientAuthenticationHandle, which the application received from the diagnostic server after successful completion of Authenticate or OverrideDefaultRoles (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”). Question Q-b07e81ff4629ada7 (open) The function is declared as noexcept and exception-safe (exception safe), but specified as not thread-safe (not thread-safe) [SWS_DM_01155]. Concurrent calls on the same instance must therefore be synchronized by the caller.

If the operation fails, the function returns the error code DiagErrc::kServiceNotAvailable via ara::core::Result<void> [SWS_DM_01155]. This indicates via rollback semantics that the call could not be executed because essential functionalities of Diagnostic Management (DM) are currently unavailable [SWS_DM_01155].

The synchronous method Revoke of class ara::diag::ClientAuthenticationHandle (SWS Diagnostics §8.6.1.1.3.3 “Revoke”) is used by applications to deauthenticate a previously authenticated diagnostic client and to completely discard its dynamic access list (DynamicAccessList) and overridden default roles ([SWS_DM_01154], [SWS_DM_01216]).

The function has no input parameters and returns a ara::core::Result<void> ([SWS_DM_01154]). In case of success, the client's authentication status is terminated. If an essential functionality of the Diagnostic Manager is not available at invocation time, the operation fails and returns error DiagErrc::kServiceNotAvailable with rollback semantics ([SWS_DM_01154]).

Regarding concurrency, the interface is specified as exception safe (exception safe), but as not thread-safe (not thread-safe) ([SWS_DM_01154]). Interpretation: For concurrent accesses to the same handle instance from multiple threads, the calling application is therefore likely to have to ensure external synchronization. Question Q-8781261c9a2f5f8e (open)

In the overall sequence, the instance of ClientAuthenticationHandle is provided to the application by the Diagnostic Server instance after successful authentication or after overriding default roles (SWS Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”). While the active handle allows replacing ([SWS_DM_01213]) or extending ([SWS_DM_01215]) the DynamicAccessList in addition to revocation, Revoke definitively terminates these permissions of the client.

The synchronous method Set of class ara::diag::ClientAuthenticationHandle ([SWS_DM_01153]) is used by an application to set or completely replace the dynamic access list (DynamicAccessList) for a diagnostic conversation or an authenticated client in the Diagnostic Server ([SWS_DM_01213]). The Diagnostic Manager maintains such a DynamicAccessList for each authenticated client, which can grant the client additional access rights to diagnostic resources beyond the configuration stored in the diagnostic extract (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 “ClientAuthenticationHandle”).

When using it, the following aspects are relevant:

• Call context and parameters: The function is called on an instance of ara::diag::ClientAuthenticationHandle (declared in #include "ara/diag/client_authentication_handle.h"). Such a handle instance is provided to the application when either ara::diag::ClientAuthentication::Authenticate ([SWS_DM_01206]) or ara::diag::ClientAuthentication::OverrideDefaultRoles ([SWS_DM_01209]) has previously completed successfully. As the only passed parameter, dynamicAccessList of type DiagnosticServiceDynamicAccessList is passed, which defines the new access list ([SWS_DM_01153]).
• Return value and error handling: The method is specified as noexcept and returns a ara::core::Result<void>. It operates with rollback semantics: If the call cannot be executed because essential DM functionality is currently unavailable, the call fails with error code DiagErrc::kServiceNotAvailable ([SWS_DM_01153]). Regarding exception handling, the method is classified as exception safe.
• Concurrency: The operation is explicitly defined as not thread-safe ([SWS_DM_01153]). If calls are made concurrently from multiple threads on the same handle instance, the necessary synchronization is the responsibility of the application.

Usage and Semantics

The function ~ClientAuthenticationHandle() is the destructor of class ara::diag::ClientAuthenticationHandle and is declared via header file ara/diag/client_authentication_handle.h ([SWS_DM_01147], AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.1.3 “Destructor”). It accepts no parameters and provides no return value. The call usually occurs implicitly at the end of the object's lifetime. Interpretation: In doing so, all resources of the client authentication bound internally by the handle are likely to be released. Question Q-ea8f47232fd9951f (open)

Error Handling and Exception Safety

The destructor is declared as noexcept and explicitly specified as exception safe ([SWS_DM_01147]). Consequently, no C++ exceptions are thrown and no specific error codes are reported during the destruction of the object, so that the cleanup procedure is guaranteed to complete without error.

Concurrency and Limitations

The destruction of a ClientAuthenticationHandle is classified as not thread-safe according to the specification ([SWS_DM_01147]). The calling application must ensure that no other threads access the same instance concurrently while the destructor is being executed.