classe ara::diag::DiagnosticSovdRecordContentElementDataView

usar

A função síncrona [SWS_DM_02288] insere um valor inteiro com sinal (std::int64_t) sob a chave informada key (ara::core::StringView) em uma estrutura de dados SOVD. Ela é declarada como método da classe ara::diag::DiagnosticSovdRecordContentElementDataView e incluída por meio do cabeçalho ara/diag/diagnostic_sovd_content_element_data.h.

Pré-requisitos e tratamento de erros

De acordo com [SWS_DM_02288], o objeto DiagnosticSovdContentElementData subjacente deve ser do tipo RecordContentElementData ou ContentData, enquanto o próprio elemento a ser adicionado não pode ser um ContentData. A função é definida como noexcept e retorna um ara::core::Result<void>. Se a operação falhar – por exemplo, porque o contêiner de destino possui um tipo incompatível ou o elemento não pode ser adicionado –, o resultado conterá um código de erro; interpretação: este provavelmente também será o caso em colisões de chaves. Pergunta Q-524c832a794559b7 (aberta)

Concorrência e interação

A execução é especificada como thread-safe e segura contra exceções [SWS_DM_02288]. Dentro da interface existem sobrecargas de mesmo tipo para inteiros sem sinal ([SWS_DM_02289]), números de ponto flutuante ([SWS_DM_02290]), valores booleanos ([SWS_DM_02291]), cadeias de caracteres ([SWS_DM_02292]), bem como elementos de dados aninhados ([SWS_DM_02293]). O mesmo método também é disponibilizado na classe portadora DiagnosticSovdContentElementData ([SWS_DM_02368]).

A função-membro síncrona Add da classe ara::diag::DiagnosticSovdRecordContentElementDataView serve para adicionar um valor inteiro não assinado de 64 bits sob uma chave predefinida ([SWS_DM_02289]). É utilizada no âmbito da funcionalidade SOVD do Diagnostic Management, que disponibiliza comunicação de diagnóstico em conformidade com ASAM SOVD (AUTOSAR_AP_SWS_Diagnostics §1.0 «Introduction and functional overview», [SWS_DM_01369]).

Uso e chamada

O método é incluído através do cabeçalho ara/diag/diagnostic_sovd_content_element_data.h. Como parâmetros, espera o identificador key como ara::core::StringView, bem como o valor a adicionar content_element como std::uint64_t ([SWS_DM_02289]). A chamada ocorre de forma síncrona, está especificada como noexcept e retorna o resultado sob a forma de ara::core::Result<void>.

Tratamento de erros e condições de contorno

• Condições de tipo: o DiagnosticSovdContentElementData instanciado deve ser do tipo RecordContentElementData ou ContentData. Além disso, o próprio elemento a adicionar não pode ser do tipo ContentData ([SWS_DM_02289]).
• Comportamento em caso de erro: se um destes requisitos de tipo for violado ou se o elemento não puder ser adicionado, a função retorna um ara::core::Result com erro ([SWS_DM_02289]). A especificação não menciona códigos de erro específicos neste ponto; presumivelmente, o objeto Result fornece um código de erro correspondente do domínio de diagnóstico. Pergunta Q-ffca131eece93b35 (aberta)
• Concorrência: a função está explicitamente especificada como thread-safe e exception safe ([SWS_DM_02289]).

Interação

O método pertence a uma família de sobrecargas tipadas para o registo de elementos de dados primitivos e complexos, incluindo variantes para inteiros com sinal ([SWS_DM_02288]) e subelementos estruturados ([SWS_DM_02293]). Uma interface equivalente é disponibilizada em paralelo na classe DiagnosticSovdContentElementData ([SWS_DM_02369]).

A função-membro síncrona Add da classe ara::diag::DiagnosticSovdRecordContentElementDataView adiciona a um registro de dados um valor primitivo de ponto flutuante do tipo double sob a chave especificada key [SWS_DM_02290]. A função serve para a estruturação de dados de diagnóstico para a funcionalidade de servidor SOVD do Diagnostic Management [SWS_DM_01369].

Para a execução aplicam-se as seguintes pré-condições relacionadas a tipos [SWS_DM_02290]:

• O objeto de destino deve ser do tipo RecordContentElementData ou ContentData.
• O elemento a ser adicionado não pode ser ele próprio do tipo ContentData.

O método está declarado como noexcept (exception safe) e especificado como seguro para threads (thread-safe) para o acesso concorrente [SWS_DM_02290]. Se a adição falhar – por exemplo, porque o tipo de objeto é incompatível ou o elemento não pode ser inserido –, um erro é reportado por meio do ara::core::Result<void> retornado [SWS_DM_02290]. Interpretação: presume-se que a causa exata do erro seja representada no ara::core::ErrorCode do objeto de resultado. Pergunta Q-c987f75d785d3e90 (aberta)

Em conjunto com as sobrecargas relacionadas de Add, o método possibilita o preenchimento estruturado de registros de dados SOVD com valores inteiros ([SWS_DM_02288], [SWS_DM_02289]), valores booleanos [SWS_DM_02291], cadeias de caracteres [SWS_DM_02292] ou dados de elementos mais complexos [SWS_DM_02293].

A função Add da classe ara::diag::DiagnosticSovdRecordContentElementDataView serve para adicionar um valor primitivo booleano sob uma chave especificada a um elemento de dados SOVD [SWS_DM_02291]. A chamada ocorre por meio do arquivo de cabeçalho ara/diag/diagnostic_sovd_content_element_data.h com o nome de parâmetro key do tipo ara::core::StringView, bem como o valor de dados úteis content_element do tipo bool [SWS_DM_02291]. Como o método retorna imediatamente um ara::core::Result<void> e nenhuma assincronia está especificada, presume-se que o processo seja síncrono. Pergunta Q-a16b08bf68f8590b (aberta)

O tratamento de erros é feito por meio do ara::core::Result<void> retornado. Um erro é retornado quando o DiagnosticSovdContentElementData subjacente não é do tipo RecordContentElementData nem ContentData, ou quando o elemento não pode ser adicionado [SWS_DM_02291]. Códigos de erro específicos não estão detalhados no trecho da especificação.

Em relação à concorrência e à segurança de execução, o método é classificado como thread-safe e oferece segurança contra exceções (noexcept) [SWS_DM_02291]. Como restrição estrutural, a especificação exige que o próprio elemento a ser adicionado não seja do tipo ContentData [SWS_DM_02291].

No sistema global, este método complementa sobrecargas relacionadas para inteiros com sinal [SWS_DM_02288], inteiros sem sinal [SWS_DM_02289], números de ponto flutuante [SWS_DM_02290], cadeias de caracteres [SWS_DM_02292] e elementos de conteúdo subordinados [SWS_DM_02293]. Além disso, existe a interface análoga na classe DiagnosticSovdContentElementData [SWS_DM_02371] no contexto da funcionalidade de servidor SOVD do Diagnostic Management [SWS_DM_01369].

usar

O método síncrono Add da classe ara::diag::DiagnosticSovdRecordContentElementDataView serve para adicionar uma entrada com uma chave e um valor de cadeia de caracteres primitivo a um elemento de dados SOVD [SWS_DM_02292]. A chamada ocorre por meio dos dois parâmetros key e content_element, que são passados respectivamente como ara::core::StringView [SWS_DM_02292]. Como valor de retorno, a função fornece um ara::core::Result<void> para sinalizar o resultado da operação [SWS_DM_02292].

Tratamento de erros

Se a adição falhar, o método retorna um erro no ara::core::Result [SWS_DM_02292]. Isso ocorre se o objeto subjacente não for do tipo RecordContentElementData ou ContentData, ou se o elemento não puder ser adicionado [SWS_DM_02292]. Interpretação: presume-se que os códigos de erro concretos sejam determinados pelo domínio de erros correspondente da implementação, uma vez que a especificação não os enumera explicitamente na definição da função. Pergunta Q-ba196615f0cd8fc8 (aberta)

Simultaneidade e condições marginais

A operação está declarada como thread-safe (thread-safe) e como segura contra exceções (exception safe), além de estar anotada com noexcept [SWS_DM_02292]. Uma pré-condição essencial é que o elemento passado como parâmetro não pode ser ele próprio do tipo ContentData [SWS_DM_02292].

Interação

A função é parte integrante do AUTOSAR Diagnostic Management (DM) para a implementação de SOVD para a Adaptive Platform AUTOSAR_AP_SWS_Diagnostics §1 «Introduction and functional overview», em que o DM atua como servidor SOVD [SWS_DM_01369]. Para o mesmo escopo, existem sobrecargas análogas de Add para números inteiros com sinal [SWS_DM_02288], inteiros sem sinal [SWS_DM_02289], números de ponto flutuante [SWS_DM_02290], valores booleanos [SWS_DM_02291] e elementos de dados complexos [SWS_DM_02293]. Além disso, ara::diag::DiagnosticSovdContentElementData disponibiliza uma sobrecarga correspondente para cadeias de caracteres [SWS_DM_02372].

A função síncrona Add da classe ara::diag::DiagnosticSovdRecordContentElementDataView adiciona um elemento aninhado do tipo DiagnosticSovdContentElementData a um elemento de dados sob a chave especificada key [SWS_DM_02293]. Isso serve para a disponibilização estruturada de dados de diagnóstico no âmbito do SOVD (Service-Oriented Vehicle Diagnostics), que é suportado pelo Diagnostic Management (DM) na Adaptive Platform ([SWS_DM_01369], AUTOSAR_AP_SWS_Diagnostics §1 «Introduction and functional overview»).

Durante o uso, devem ser cumpridas diretrizes obrigatórias de tipo:

• O objeto de dados chamador deve ser do tipo RecordContentElementData ou ContentData [SWS_DM_02293].
• O elemento a ser adicionado content_element não pode ser explicitamente do tipo ContentData [SWS_DM_02293].
• Em complemento a estruturas de dados complexas, estão disponíveis sobrecargas separadas para valores elementares, por exemplo para valores inteiros ([SWS_DM_02288], [SWS_DM_02289]), números de ponto flutuante [SWS_DM_02290], valores booleanos [SWS_DM_02291] ou cadeias de caracteres [SWS_DM_02292], conforme também definido em DiagnosticSovdContentElementData [SWS_DM_02373].

Para o tratamento de erros, a função retorna um ara::core::Result<void>. Se a operação falhar – por exemplo, porque os pré-requisitos de tipo foram violados ou o elemento não pôde ser inserido –, o resultado conterá um erro [SWS_DM_02293]. A codificação exata do erro provavelmente deve basear-se em erros específicos de domínio do gerenciamento de diagnóstico. Pergunta Q-56c929209d0c7358 (aberta) Em termos de concorrência e segurança, o método é declarado como noexcept, é considerado seguro contra exceções (exception safe) e especificado como thread-safe (thread-safe) para acesso concorrente [SWS_DM_02293].

Utilização e semântica

O método Clear da classe ara::diag::DiagnosticSovdRecordContentElementDataView serve para a remoção síncrona de todos os elementos de conteúdo de um RecordContentElementData [SWS_DM_02276]. A chamada ocorre sem parâmetros por meio do cabeçalho #include "ara/diag/diagnostic_sovd_content_element_data.h" e não possui valor de retorno (void) [SWS_DM_02276].

Como pré-requisito para a execução, está definido que a instância de dados subjacente deve ser do tipo RecordContentElementData ou ContentData [SWS_DM_02276]. Interpretação: como a função é declarada como noexcept e não reporta status de erro, supõe-se que a conformidade com este tipo de dados já esteja assegurada previamente na criação do objeto de view. Pergunta Q-93e43eee235a8f12 (aberta)

Tratamento de erros e simultaneidade

Quanto à segurança de execução, o método é especificado como exception safe e não lança exceções devido à declaração noexcept [SWS_DM_02276]. A chamada é, além disso, explicitamente classificada como thread-safe, de modo que acessos concorrentes são permitidos [SWS_DM_02276].

Interação e distinção

No ambiente SOVD, esta função diferencia-se do método Clear em DiagnosticSovdContentElementData [SWS_DM_02338], que é definido para elementos de array e fornece um ara::core::Result<void>. Da mesma forma, existe uma distinção funcional em relação ao método de view para arrays [SWS_DM_02233], bem como em relação à exclusão assíncrona de DTCs via ara::diag::DTCInformation::Clear, que retorna um ara::core::Future<void> e não é thread-safe [SWS_DM_00671].

A função-membro Erase da classe ara::diag::DiagnosticSovdRecordContentElementDataView serve para a remoção de um elemento de conteúdo subordinado de um record de dados de diagnóstico ([SWS_DM_02294], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.14 «Erase»). A declaração é disponibilizada por meio do cabeçalho #include "ara/diag/diagnostic_sovd_content_element_data.h" ([SWS_DM_02294]).

Uso e semântica: como parâmetro de entrada, a função recebe o iterador iterator do tipo DiagnosticSovdRecordContentElementDataIterator, que aponta para o elemento a ser concretamente excluído ([SWS_DM_02294]). Interpretação: como a função é declarada com noexcept e retorna diretamente ara::core::Result<void> em vez de um objeto future, supõe-se que o processo de exclusão seja executado de forma síncrona na thread do chamador. Pergunta Q-148ae95c28910b16 (aberta) Em caso de execução bem-sucedida, o método retorna um ara::core::Result<void> vazio ([SWS_DM_02294]).

Tratamento de erros: a operação falha se o elemento de dados afetado não for do tipo RecordContentElementData nem ContentData, ou se o elemento não tiver podido ser removido do contêiner ([SWS_DM_02294]). Nesses casos de erro, a função retorna um erro com o código de erro DiagErrc::kInvalidArgument ([SWS_DM_02294]).

Concorrência e interação: para a chamada, a interface é especificada como thread-safe bem como exception safe ([SWS_DM_02294]). Em termos técnicos, a função corresponde à variante para arrays ara::diag::DiagnosticSovdArrayContentElementDataView::Erase ([SWS_DM_02247], AUTOSAR_AP_SWS_Diagnostics §8.60.5.1.1.8 «Erase») e interage com as operações elementares de exclusão da classe de contêiner DiagnosticSovdContentElementData para arrays ([SWS_DM_02352]) e records ([SWS_DM_02374]).

A função-membro síncrona Find da classe View ara::diag::DiagnosticSovdRecordContentElementDataView serve para encontrar um elemento com base na sua chave ([SWS_DM_02285], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.15 «Find»). Como parâmetro é passado key do tipo ara::core::StringView; como resultado a função fornece um iterador modificável do tipo DiagnosticSovdRecordContentElementDataIterator ([SWS_DM_02285]). Pré-requisito para a utilização é que o respectivo DiagnosticSovdContentElementData seja do tipo RecordContentElementData ou ContentData ([SWS_DM_02285]).

Em relação ao tratamento de erros e à concorrência, a função é declarada como noexcept, é considerada segura contra exceções (exception safe) e, de acordo com a especificação, é segura para threads (thread-safe) ([SWS_DM_02285]). Como o tipo de retorno é diretamente um iterador e não um ara::core::Result, a função não relata códigos de erro específicos; se a chave procurada não existir, presume-se que seja retornado um iterador de fim (end). Pergunta Q-a34054c9851517ae (aberta)

Na interação com interfaces relacionadas, existe na mesma classe View uma sobrecarga constante ([SWS_DM_02286], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.16 «Find»), que retorna um DiagnosticSovdRecordContentElementDataConstIterator. Uma interface constante análoga também é oferecida pela classe DiagnosticSovdRecordContentElementDataConstView ([SWS_DM_02306], AUTOSAR_AP_SWS_Diagnostics §8.60.9.1.1.7 «Find»). Em contrapartida, o método Find em DiagnosticSovdContentElementData encapsula o seu iterador em um ara::core::Result, a fim de mapear tipos inválidos ou chaves ausentes como erros ([SWS_DM_02365], [SWS_DM_02366], AUTOSAR_AP_SWS_Diagnostics §8.60.6.1.2.25 «Find»).

A função-membro síncrona Find da classe ara::diag::DiagnosticSovdRecordContentElementDataView serve para a localização somente leitura de um elemento de dados com base na sua chave ([SWS_DM_02286], AUTOSAR AP SWS Diagnostics §8.60.11.1.1.16 «Find»).

Utilização e parâmetros

A função recebe a chave procurada key como ara::core::StringView ([SWS_DM_02286]). O pré-requisito para a chamada é que a instância seja do tipo de diagnóstico RecordContentElementData ou ContentData ([SWS_DM_02286]). Como valor de retorno, ela fornece de forma síncrona um iterador constante do tipo DiagnosticSovdRecordContentElementDataConstIterator ([SWS_DM_02286]). Caso não exista nenhum elemento correspondente à chave, presume-se que seja retornado um iterador que marca o fim da sequência (interpretação). Pergunta Q-41a1eba77c0bc236 (aberta)

Tratamento de erros e simultaneidade

A interface é declarada com noexcept, garante segurança contra exceções (exception safe) e está especificada como thread-safe (thread-safe) para acesso concorrente ([SWS_DM_02286]). Diferentemente do método em ara::diag::DiagnosticSovdContentElementData ([SWS_DM_02366]), não ocorre retorno via ara::core::Result, razão pela qual casos de erro não são mapeados por meio de códigos de erro.

Interação

Para acessos de escrita ou modificadores à mesma visualização, existe a sobrecarga não constante [SWS_DM_02285] com iterador modificável. Para views puramente de leitura, a classe DiagnosticSovdRecordContentElementDataConstView disponibiliza uma função Find análoga ([SWS_DM_02306]).

A função de elemento síncrona Remove da classe ara::diag::DiagnosticSovdRecordContentElementDataView serve para a remoção direcionada de uma entrada a partir de sua chave [SWS_DM_02287]. Ela é definida no cabeçalho ara/diag/diagnostic_sovd_content_element_data.h e processa o parâmetro key do tipo ara::core::StringView AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.19 «Remove».

Como valor de retorno, a função fornece um ara::core::Result<bool> [SWS_DM_02287]:

• Em caso de sucesso, o valor booleano contido sinaliza se o elemento endereçado pôde realmente ser removido.
• Um erro é reportado através do ara::core::Result se o elemento não for do tipo RecordContentElementData ou ContentData ou se a chave especificada não tiver sido encontrada [SWS_DM_02287].

Em relação à concorrência e restrições, a função é especificada como segura contra exceções (exception safe) e segura para threads (thread-safe), bem como declarada com noexcept [SWS_DM_02287]. Como pré-condição de chamada, a especificação exige obrigatoriamente que a instância subjacente seja do tipo RecordContentElementData ou ContentData [SWS_DM_02287].

Interpretação: Funcionalmente, a operação deve corresponder à remoção na classe de dados ara::diag::DiagnosticSovdContentElementData::Remove [SWS_DM_02367], uma vez que a assinatura, os parâmetros e os cenários de erro são especificados de forma completamente idêntica AUTOSAR_AP_SWS_Diagnostics §8.60.6.1.2.54 «Remove». Pergunta Q-5a9ac29a9b5814be (aberta)

O método Reserve da classe ara::diag::DiagnosticSovdRecordContentElementDataView ([SWS_DM_02283], AUTOSAR_AP_SWS_Diagnostics §8.60.11.1.1.20 «Reserve») reserva de forma síncrona a capacidade de memória desejada para RecordContentElementData. A chamada é disponibilizada por meio do cabeçalho #include "ara/diag/diagnostic_sovd_content_element_data.h" e recebe o parâmetro capacity do tipo std::size_t. Como valor de retorno, a função fornece void.

A interface é declarada como noexcept e especificada como segura para exceções (“exception safe”) ([SWS_DM_02283]). Não são retornados códigos de erro específicos nem estruturas de erro. Interpretação: caso a alocação da capacidade requerida falhe, o erro presumivelmente é capturado internamente ou leva à terminação do programa, devido à ausência de um canal de retorno como ara::core::Result. Pergunta Q-ddbaac36f8ed58ad (aberta)

No que diz respeito à concorrência, a função é definida como segura para threads (“thread-safe”) ([SWS_DM_02283]). Ela pode, portanto, ser chamada em paralelo e sem medidas adicionais de sincronização a partir de múltiplas threads.

Na interação com interfaces correlatas, a variante de array DiagnosticSovdArrayContentElementDataView::Reserve ([SWS_DM_02240]) comporta-se de forma análoga. Diferentemente disso, DiagnosticSovdContentElementData::Reserve ([SWS_DM_02345]) retorna um ara::core::Result<void> para relatar conflitos de tipo. Já a função DiagnosticServiceDynamicAccessList::Reserve ([SWS_DM_01163]) destina-se a uma pré-alocação de pior caso para service patterns, espera dois parâmetros e não é segura para threads.