classe ara::diag::ClientAuthenticationHandle

O método Append da classe ara::diag::ClientAuthenticationHandle é utilizado por aplicações para anexar uma lista de acesso dinâmica (dynamicAccessList) à DynamicAccessList já existente de uma conversação de diagnóstico ativa [SWS_DM_01152]. A interface é disponibilizada por meio do cabeçalho ara/diag/client_authentication_handle.h AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.1 «Append».

A chamada é executada de forma síncrona e está especificada como noexcept [SWS_DM_01152]. Como parâmetro de entrada, a função recebe uma DiagnosticServiceDynamicAccessList. O tipo de retorno ara::core::Result<void> sinaliza a conclusão bem-sucedida ou transporta, em caso de erro, o código de erro DiagErrc::kServiceNotAvailable [SWS_DM_01152]. Este último indica que funções essenciais do Diagnostic Management não estão disponíveis no momento. Para este caso de erro aplica-se uma semântica de rollback, de modo que o estado anterior da lista de acesso permaneça preservado [SWS_DM_01152].

Em termos de concorrência, a operação é considerada segura contra exceções (exception safe), mas está expressamente classificada como não segura para threads (not thread-safe) [SWS_DM_01152]. Em caso de acessos paralelos ao mesmo objeto handle, presume-se, portanto, que uma sincronização externa pela aplicação chamadora seja necessária. Pergunta Q-f0da9a0538a86a16 (aberta)

O construtor padrão síncrono [SWS_DM_01146] cria uma instância da classe ara::diag::ClientAuthenticationHandle. A chamada não aceita parâmetros de passagem e não fornece nenhum valor de retorno. A função está declarada como noexcept e especificada como segura entre threads (thread-safe), bem como segura em termos de exceções [SWS_DM_01146], de modo que não ocorrem códigos de erro nem exceções aquando da criação.

Aplicam-se as seguintes restrições à transmissão e ao ciclo de vida do objeto criado:

• A construção por cópia e a atribuição por cópia estão explicitamente eliminadas ([SWS_DM_01150], [SWS_DM_01151]).
• O construtor de movimento [SWS_DM_01148] e o operador de atribuição por movimento [SWS_DM_01149] são suportados.
• Todos os métodos de instância como Set [SWS_DM_01153], Append [SWS_DM_01152], Revoke [SWS_DM_01154], bem como o destrutor [SWS_DM_01147], estão definidos como não seguros entre threads (not thread-safe).

No sistema global, o Diagnostic Server disponibiliza regularmente manipuladores ativos e vinculados a um cliente através de Authenticate [SWS_DM_01142] ou OverrideDefaultRoles [SWS_DM_01141] (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 «ClientAuthenticationHandle»). Uma instância criada através do construtor padrão deverá, portanto, servir como marcador de posição não vinculado, que apenas recebe um manipulador válido para o controlo das listas de acesso através de uma subsequente atribuição por movimento [SWS_DM_01149]. Pergunta Q-ce182402bd1d4072 (aberta)

O método Refresh da classe ara::diag::ClientAuthenticationHandle (arquivo de cabeçalho #include "ara/diag/client_authentication_handle.h") serve para que uma aplicação estenda temporizadores ativos de autenticação ou de papéis (AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.3.2 «Refresh»). Ele reinicia o temporizador que foi previamente iniciado por Authenticate ou OverrideDefaultRoles. Caso ambos os métodos tenham sido chamados anteriormente, ambos os temporizadores são renovados simultaneamente pela chamada [SWS_DM_01155].

A chamada síncrona (interpretação: retorno direto sem Future assíncrono) ocorre sem parâmetros em uma instância existente de ClientAuthenticationHandle, a qual a aplicação recebeu do Diagnostic Server após a conclusão bem-sucedida de Authenticate ou OverrideDefaultRoles (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 «ClientAuthenticationHandle»). Pergunta Q-b07e81ff4629ada7 (aberta) A função é declarada como noexcept e segura contra exceções (exception safe), porém especificada como não segura para threads (not thread-safe) [SWS_DM_01155]. Chamadas concorrentes na mesma instância devem, portanto, ser sincronizadas pelo chamador.

Se a operação falhar, a função retorna o código de erro DiagErrc::kServiceNotAvailable via ara::core::Result<void> [SWS_DM_01155]. Isso indica, por meio de semântica de rollback, que a chamada não pôde ser executada porque funcionalidades essenciais do Diagnostic Management (DM) estão indisponíveis no momento [SWS_DM_01155].

O método síncrono Revoke da classe ara::diag::ClientAuthenticationHandle (SWS Diagnostics §8.6.1.1.3.3 «Revoke») serve para que aplicações desautentiquem um cliente de diagnóstico previamente autenticado, bem como descartem completamente sua lista de acesso dinâmica (DynamicAccessList) e funções padrão sobrepostas ([SWS_DM_01154], [SWS_DM_01216]).

A função não possui parâmetros de passagem e retorna um ara::core::Result<void> ([SWS_DM_01154]). Em caso de sucesso, o status de autenticação do cliente é encerrado. Se uma funcionalidade essencial do Diagnostic Manager não estiver disponível no momento da chamada, a operação falha e fornece o erro DiagErrc::kServiceNotAvailable com semântica de rollback ([SWS_DM_01154]).

Em relação à concorrência, a interface está especificada como segura contra exceções (exception safe), porém como não segura para threads (not thread-safe) ([SWS_DM_01154]). Interpretação: em caso de acessos concorrentes à mesma instância de handle a partir de múltiplas threads, presume-se, portanto, que a aplicação chamadora deva assegurar uma sincronização externa. Pergunta Q-8781261c9a2f5f8e (aberta)

No fluxo global, a instância de ClientAuthenticationHandle é disponibilizada à aplicação pela instância do servidor de diagnóstico após a autenticação bem-sucedida ou após a sobreposição de funções padrão (SWS Diagnostics §7.3.2.3.3 «ClientAuthenticationHandle»). Enquanto o handle ativo permite, além da revogação, também a substituição ([SWS_DM_01213]) ou extensão ([SWS_DM_01215]) da DynamicAccessList, Revoke encerra definitivamente essas permissões do cliente.

O método síncrono Set da classe ara::diag::ClientAuthenticationHandle ([SWS_DM_01153]) serve para uma aplicação definir ou substituir completamente a lista de acesso dinâmica (DynamicAccessList) para uma conversação de diagnóstico ou para um cliente autenticado no Diagnostic Server ([SWS_DM_01213]). O Diagnostic Manager mantém para cada cliente autenticado uma DynamicAccessList desse tipo, que pode conceder ao cliente direitos de acesso adicionais a recursos de diagnóstico além da configuração registrada no Diagnostic Extract (AUTOSAR_AP_SWS_Diagnostics §7.3.2.3.3 «ClientAuthenticationHandle»).

Ao utilizar, os seguintes aspectos são determinantes:

• Contexto de chamada e parâmetros: A função é chamada em uma instância de ara::diag::ClientAuthenticationHandle (declarada em #include "ara/diag/client_authentication_handle.h"). Tal instância de handle é disponibilizada à aplicação quando previamente ara::diag::ClientAuthentication::Authenticate ([SWS_DM_01206]) ou ara::diag::ClientAuthentication::OverrideDefaultRoles ([SWS_DM_01209]) foi concluído com sucesso. Como único parâmetro de passagem é transmitida a dynamicAccessList do tipo DiagnosticServiceDynamicAccessList, a qual define a nova lista de acesso ([SWS_DM_01153]).
• Valor de retorno e tratamento de erros: O método está especificado como noexcept e retorna um ara::core::Result<void>. Ele trabalha com semântica de rollback: se a chamada não puder ser executada porque a funcionalidade essencial de DM não está disponível no momento, a chamada falha com o código de erro DiagErrc::kServiceNotAvailable ([SWS_DM_01153]). Quanto ao tratamento de exceções, o método é classificado como seguro contra exceções (exception safe).
• Concorrência: A operação é explicitamente definida como não segura para threads (not thread-safe) ([SWS_DM_01153]). Se forem realizadas chamadas na mesma instância de handle de forma concorrente a partir de múltiplas threads, a sincronização necessária cabe à aplicação.

Utilização e semântica

A função ~ClientAuthenticationHandle() é o destrutor da classe ara::diag::ClientAuthenticationHandle e é declarada por meio do arquivo de cabeçalho ara/diag/client_authentication_handle.h ([SWS_DM_01147], AUTOSAR_AP_SWS_Diagnostics §8.6.1.1.1.3 «Destructor»). Ela não recebe parâmetros de passagem e não fornece valor de retorno. A chamada ocorre habitualmente de forma implícita no encerramento do tempo de vida do objeto. Interpretação: com isso, presume-se que todos os recursos da autenticação de cliente vinculados internamente pelo handle sejam liberados. Pergunta Q-ea8f47232fd9951f (aberta)

Tratamento de erros e segurança de exceções

O destrutor está declarado como noexcept e explicitamente especificado como exception safe ([SWS_DM_01147]). Consequentemente, durante a destruição do objeto, nenhuma exceção C++ é disparada e nenhum código de erro específico é reportado, de modo que o processo de limpeza é garantidamente concluído sem falhas.

Simultaneidade e restrições

A destruição de um ClientAuthenticationHandle é classificada de acordo com a especificação como not thread-safe ([SWS_DM_01147]). A aplicação chamadora deve garantir que nenhuma outra thread acesse a mesma instância em paralelo enquanto o destrutor estiver sendo executado.