classe <SI-Namespace>::proxy::fields::<Field>

usar

O método Get serve, no âmbito do proxy <SI-Namespace>::proxy::fields::<Field>, para a obtenção assíncrona do valor atual do campo ([SWS_CM_00112]; ver também AUTOSAR_AP_EXP_ARAComAPI §6 «FieldGet»). A função é disponibilizada através do cabeçalho do proxy <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h e só existe se para o campo estiver modelado Field.hasGetter == TRUE ([SWS_CM_00112]). Não recebe parâmetros e retorna um ara::core::Future<FieldType>, o qual contém o valor atual após uma transmissão bem-sucedida ([SWS_CM_00112]).

Tratamento de erros e condições de contorno

A interface está definida como noexcept e segura contra exceções ([SWS_CM_00112]). Se a operação falhar, o ara::core::Future retornado contém um código de erro com semântica de rollback ([SWS_CM_00112]):

• ComErrc::kCommunicationFailure: O binding de rede reporta um erro de comunicação recuperável ou a falha de uma comunicação protegida ([SWS_CM_00112]).
• ComErrc::kMinimumSendIntervalViolationError: Um pedido de envio ocorreu mais depressa do que o permitido pelo intervalo mínimo de envio configurado para o elemento (minimumSendInterval) ([SWS_CM_00112]).
• InsufficientPermissionsViolation: A execução é rejeitada pelo Grant Enforcement ([SWS_CM_00112]).

Não existem erros de aplicação (Application Errors) para o getter ([SWS_CM_00113]).

Interação

Do lado do skeleton, o processamento do pedido do getter pressupõe um callback, o qual é configurado através de RegisterGetHandler ([SWS_CM_00114]). Cada chamada a Get() executa uma verificação End-to-End (E2E); o estado resultante pode ser consultado de forma síncrona do lado do proxy através de GetE2EStateMachineStateGetter ([SWS_CM_00145]).

Utilização e contexto de chamada

A função Set é disponibilizada no namespace <SI-Namespace>::proxy::fields::<Field> e está disponível exclusivamente se para o campo estiver configurado Field.hasSetter == TRUE [SWS_CM_00113]. Antes da utilização, a instância de serviço tem de ter sido oferecida no lado do servidor (OfferService()) e encontrada bem como conectada no lado do cliente ARAComAPI §4.2 «Means of Communication». A chamada ocorre de forma assíncrona: passa o novo valor do campo através do parâmetro value e retorna um ara::core::Future<FieldType> [SWS_CM_00113]. O método está especificado como noexcept e é considerado seguro contra exceções [SWS_CM_00113].

Tratamento de erros

Se a transmissão falhar, o respetivo erro é disponibilizado através do ara::core::Future retornado [SWS_CM_00113]:

• ComErrc::kCommunicationFailure: Reporta um erro de comunicação recuperável ou uma anomalia na transmissão segura; em caso de timeout, pode verificar-se um estado indeterminado no lado do servidor sem semântica de rollback [SWS_CM_00113].
• ComErrc::kMinimumSendIntervalViolationError: Ocorre quando um pedido de envio foi emitido mais depressa do que o intervalo mínimo de envio configurado (minimumSendInterval) (igualmente sem semântica de rollback) [SWS_CM_00113].
• Permissões de acesso em falta conduzem a uma recusa por parte do Grant Enforcement (InsufficientPermissionsViolation) [SWS_CM_00113].
• Os erros de aplicação não são transmitidos através de exceções, mas sim retornando, em caso de sucesso do future, um valor divergente do parâmetro do pedido [SWS_CM_00113].

Interação e concorrência

No lado do servidor, a chamada corresponde a um callback na instância de skeleton, o qual tem de ser registado previamente por meio de RegisterSetHandler [SWS_CM_00116] ARAComAPI §4.2 «Means of Communication». Para monitorizar a segurança de transmissão E2E no lado do cliente, o estado da máquina de estados E2E da última chamada a Set() pode ser consultado através de GetE2EStateMachineStateSetter() [SWS_CM_00146].

Utilização e contexto de chamada

A função SetReceiveHandler é fornecida no lado do proxy no namespace <SI-Namespace>::proxy::fields::<Field> através do arquivo de cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h ([SWS_CM_11605]). Ela registra no lado do cliente um callback para notificações em caso de alterações de valor de um campo ([SWS_CM_11605]). Esse mecanismo segue o procedimento de notificação de eventos, pelo qual o Communication Management informa o cliente sobre atualizações (EXP_ARAComAPI §4.2 «Means of Communication»).

Como parâmetro é passado um ara::com::FieldReceiveHandler, que representa uma função sem parâmetros ([SWS_CM_11605]). A função não retorna nenhum valor (void) e é especificada como segura contra exceções (noexcept) ([SWS_CM_11605]).

Tratamento de erros e simultaneidade

Caso o objeto chamável passado não exista ou seja nulo, a função relata a violação InvalidHandlerViolation ([SWS_CM_11605]). Se a execução do manipulador dever ocorrer em um contexto de execução definido, a variante de template com ExecutorT está disponível ([SWS_CM_11611]).

Interação

O comportamento corresponde aos registros de manipuladores para eventos ([SWS_CM_00181]) e gatilhos ([SWS_CM_00250]). O cancelamento do registro deve ocorrer via UnsetReceiveHandler(), seguindo o padrão de interface da classe proxy (EXP_ARAComAPI §5.3.1 «Proxy Class API’s»). Pergunta Q-74cd83b99aadec16 (aberta)

Utilização e contexto de chamada

A função de template SetReceiveHandler faz parte da classe proxy class <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11611]; cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h"). Ela serve para registrar no lado do cliente um manipulador de recepção para notificações em caso de alterações de valor de um campo (AUTOSAR_AP_EXP_ARAComAPI §4.2 «Means of Communication», [SWS_CM_11605]). Através dos parâmetros, são passados um objeto chamável handler do tipo ara::com::FieldReceiveHandler e um contexto de execução executor como referência universal ExecutorT&& ([SWS_CM_11611]). A função não possui valor de retorno (void).

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

O método é declarado como noexcept e especificado como seguro contra exceções (exception safe) ([SWS_CM_11611]). Se o chamável passado handler não existir ou for nulo, ocorre um InvalidHandlerViolation ([SWS_CM_11611]). Portanto, os chamadores devem garantir que uma função ou objeto de função válido seja fornecido antes da chamada.

Concorrência e interação

Diferentemente do registro padrão sem executor ([SWS_CM_11605]), o callback é processado no contexto de execução fornecido por executor na chegada de uma notificação de campo ([SWS_CM_11611]). Interpretação: Isso provavelmente deve causar um desacoplamento, de modo que o processamento de dados específico da aplicação não ocorra nos contextos de execução de threads internas de middleware. Pergunta Q-cbe1af19bea15a88 (aberta) O método pertence às APIs da classe proxy (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s») e segue o mesmo padrão que as variantes de executor para eventos ([SWS_CM_11356] com base em [SWS_CM_00181]) e gatilhos ([SWS_CM_00352] com base em [SWS_CM_00250]).

A função SetSubscriptionStateChangeHandler regista num campo de proxy (âmbito <SI-Namespace>::proxy::fields::<Field>) um callback personalizado, que é chamado pelo Communication Management assim que o estado da subscrição (ara::com::SubscriptionState) do campo se alterar ([SWS_CM_11607], [SWS_CM_00333]). A chamada efetua-se de forma síncrona e não retorna nenhum valor de retorno ([SWS_CM_11607]). Pertence às interfaces centrais de proxy para a gestão de subscrições de eventos e de campos (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s»).

Em relação ao tratamento de erros, a função de registo é especificada como exception safe e declarada com noexcept ([SWS_CM_11607]). Caso o objeto callable handler passado não exista ou seja null, ocorre uma violação da especificação sob a forma de um InvalidHandlerViolation ([SWS_CM_11607]).

Na interação com o estabelecimento da ligação, deve ter-se em conta que Subscribe() tem de ser considerada, por princípio, como uma operação assíncrona ([SWS_CM_12006]). As aplicações só devem, por isso, presumir uma subscrição bem-sucedida, mesmo após o retorno sem erros de Subscribe(), quando o handler registado tiver sinalizado o estado kSubscribed ([SWS_CM_12006]). Além disso, o Communication Management chama o handler com kSubscriptionPending se a associação efetiva não puder ser concluída imediatamente ou se a instância do servidor falhar, por exemplo, na sequência de um reinício ou de um erro de rede ([SWS_CM_00313]). Caso o handler deva ser executado num contexto de execução específico, está disponível para o efeito a variante de template sobrecarregada com um ExecutorT ([SWS_CM_11608]).

A função de template SetSubscriptionStateChangeHandler no namespace <SI-Namespace>::proxy::fields::<Field> serve para registrar uma função de callback para monitorar alterações de estado da assinatura de um campo ([SWS_CM_11608]). Ela estende o comportamento básico de [SWS_CM_11607] para que o manipulador registrado seja executado em um contexto de execução explicitamente passado (executor) ([SWS_CM_11608]).

O método recebe dois parâmetros ([SWS_CM_11608]):

• handler: O callback a ser chamado do tipo ara::com::SubscriptionStateChangeHandler ([SWS_CM_11354]), que é acionado assim que o ara::com::SubscriptionState é alterado ([SWS_CM_00333]).
• executor: Uma referência de encaminhamento do tipo ExecutorT&& ([SWS_CM_11360]), que fornece o contexto para a execução do manipulador ([SWS_CM_11608]).

A função não retorna nenhum valor (void) e é declarada como noexcept ([SWS_CM_11608]). Ela é especificada como exception safe ([SWS_CM_11608]). Como violação é definido InvalidHandlerViolation caso o chamável passado não exista ou seja null ([SWS_CM_11608]).

Interpretação: Com a passagem de executor, a execução do manipulador deve ser transferida do contexto interno do gerenciamento de comunicação para o contexto de thread ou de tarefa da aplicação. Na interação das APIs de proxy, a chamada junta-se a métodos como Subscribe(), Unsubscribe() e UnsetSubscriptionStateChangeHandler() (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s»). Variantes sobrecarregadas análogas com contexto de execução existem para eventos de proxy ([SWS_CM_11354]), bem como para gatilhos de proxy ([SWS_CM_01106]). Pergunta Q-647f618545799c4e (aberta)

Utilização e contexto de chamada

A função-membro SetTransportFaultConditionHandler serve para registar um manipulador de erros para o notificador de um campo de proxy no namespace <SI-Namespace>::proxy::fields::<Field> [SWS_CM_00109]. Como parâmetro, é passado um objeto invocável (callable) do tipo ara::com::e2e::TransportFaultConditionHandler. A função não fornece qualquer valor de retorno e vincula o callback aos notificadores de instâncias de serviço individuais, a fim de receber erros de transmissão do backend de comunicação AUTOSAR_AP_SWS_CommunicationManagement §7.4 «End-to-end communication protection» p. 235.

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

O método está declarado como noexcept e especificado como seguro contra exceções (exception safe) [SWS_CM_00109]. Se o invocável passado for inválido ou null, ocorre uma violação de pré-condição sob a forma de uma InvalidHandlerViolation [SWS_CM_00109]. Interpretação: Como a função não pode lançar exceções, uma tal violação em AUTOSAR Adaptive deverá tipicamente conduzir à interrupção imediata do programa. Pergunta Q-74df6934d4ae3c93 (aberta)

Concorrência e interação

Enquanto esta forma básica regista o manipulador diretamente, existe com [SWS_CM_00110] uma variante de modelo sobrecarregada que aceita adicionalmente um executor (ExecutorT&& executor) para a definição do contexto de execução assíncrono. A função integra-se no tratamento de erros ponta a ponta: Enquanto notificadores ([SWS_CM_00109], [SWS_CM_00110]), eventos ([SWS_CM_00099]) e triggers ([SWS_CM_00106]) comunicam erros de transmissão de forma assíncrona através de tais manipuladores, os erros de transporte em pedidos de métodos bem como de getters e setters são, em vez disso, reportados através de ComErrc::kCommunicationFailure no ara::core::Future resultante [SWS_CM_00090].

usar

A função-membro de template SetTransportFaultConditionHandler serve, no escopo de uma classe de campo de proxy (<SI-Namespace>::proxy::fields::<Field>), para registrar um handler para o notificador do respectivo campo [SWS_CM_00110]. Ela aceita dois parâmetros de entrada:

• handler: o chamável a ser registrado do tipo ara::com::e2e::TransportFaultConditionHandler [SWS_CM_00110].
• executor: uma referência rvalue para um objeto executor (ExecutorT&&), em cujo contexto de execução eventuais cálculos iniciados de forma assíncrona são disparados [SWS_CM_00110].

A função não retorna nenhum valor (void) e está declarada como noexcept [SWS_CM_00110].

Tratamento de erros e segurança de execução

A interface está especificada como segura contra exceções (exception safe) [SWS_CM_00110]. Se for passado como handler um chamável inexistente ou com valor nulo, isso resulta em uma InvalidHandlerViolation [SWS_CM_00110]. Através deste handler são reportadas condições específicas de erro de transporte, enquanto métodos bem como getters e setters de campo sinalizam eventuais erros de transporte através de ComErrc::kCommunicationFailure em seus respectivos futures de retorno [SWS_CM_00090].

Concorrência e interação

O método constitui a sobrecarga de contexto de execução para a função básica com menos parâmetros [SWS_CM_00109]. Através do objeto executor passado, a implementação desacopla a execução do handler do contexto interno de recepção do gerenciamento de comunicação [SWS_CM_00110]. Sobrecargas semelhantes estão disponíveis para eventos de proxy [SWS_CM_00100], disparadores de proxy [SWS_CM_00107], bem como para métodos do skeleton [SWS_CM_00094] e campos do skeleton [SWS_CM_00097]. Interpretação: a chamada deve sensatamente ocorrer antes da chegada de mensagens do notificador ou da subscrição do notificador, a fim de assegurar um monitoramento contínuo de erros. Pergunta Q-bc5c62dd39c09029 (aberta)

O método Subscribe destina-se a subscrever notificações para um campo de uma instância de proxy de serviço no âmbito proxy::fields::<Field> ([SWS_CM_11601]). Através do parâmetro maxSampleCount, a aplicação define o número máximo de amostras de dados que pretende reter simultaneamente, configurando assim a cache de receção local ([SWS_CM_11601], EXP ARAComAPI §5.3 «Proxy Class API’s»). A chamada é assíncrona: o ara::core::Result<void> retornado sinaliza apenas a aceitação da subscrição pelo Communication Management (EXP ARAComAPI §5.3.5.2 «Monitoring Event Subscription»).

Relativamente ao comportamento dos estados e ao tratamento de erros, aplicam-se as seguintes regras:

• Idempotência: Se o campo já se encontrar no estado kSubscribed ou kSubscriptionPending e o maxSampleCount transmitido coincidir com o valor da subscrição atual, o método regressa sem efeito ([SWS_CM_11601]).
• Códigos de erro: Se a cache solicitada não puder ser disponibilizada, a operação falha com o erro ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_11601], [SWS_CM_10432]).
• Verificação de autorização: Se faltarem os direitos necessários, a chamada é rejeitada pelo Grant Enforcement com um InsufficientPermissionsViolation ([SWS_CM_11601]).

O método está declarado como noexcept e especificado como Exception-safe ([SWS_CM_11601]). Semanticamente, segue o comportamento da subscrição de eventos ([SWS_CM_00141]); a cache configurada constitui a base para a subsequente receção de amostras através de métodos como GetNewSamples ([SWS_CM_00701]).

A função UnsetReceiveHandler() destina-se, ao nível de proxy, a anular o registo de um manipulador de receção previamente registado para notificações de campo ([SWS_CM_11606]). Pertence às APIs de classes de proxy de ara::com (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s») e situa-se no espaço de nomes <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11606]).

Relativamente ao contexto de chamada e semântica, o método não recebe parâmetros e não retorna nenhum valor ([SWS_CM_11606]). Através da chamada, uma aplicação pode a qualquer momento alternar de um modelo de notificação orientado a eventos para uma operação de polling baseada em consulta, revogando o callback específico do utilizador (AUTOSAR_AP_EXP_ARAComAPI §5.3.2 «RadarService Proxy Class Example»).

Para o tratamento de erros, a função está especificada como noexcept bem como exception safe ([SWS_CM_11606]); segundo a especificação, não existem códigos de erro específicos. A chamada ocorre de forma síncrona; após a revogação bem-sucedida do manipulador, o Communication Management deixa de acionar quaisquer outras chamadas de callback aquando da chegada de novos dados (interpretação: execuções em curso ou já agendadas deverão ainda ser concluídas ou processadas de forma serializada antes da revogação, visto que as chamadas de callback pelo Communication Management devem ocorrer de forma serializada; ver AUTOSAR_AP_EXP_ARAComAPI §5.3.2 «RadarService Proxy Class Example»). Pergunta Q-fbc65e80b8d8be38 (aberta)

Na interação, o método corresponde à desativação de acionadores em eventos de serviço ([SWS_CM_00183]; AUTOSAR_AP_EXP_ARAComAPI §10) e acionadores ([SWS_CM_11614]). No binding DDS, o comportamento é refletido através do mapeamento de UnsetReceiveHandler() no respetivo DataReader ([SWS_CM_11141]).

usar

O método UnsetSubscriptionStateChangeHandler serve, no âmbito da plataforma AUTOSAR Adaptive, para remover um callback previamente registrado para alterações do status de assinatura (ara::com::SubscriptionState) de um campo [SWS_CM_11609]. Ele é chamado sincronamente em instâncias de campos de um service proxy no namespace <SI-Namespace>::proxy::fields::<Field> e exige a inclusão do cabeçalho gerado #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 «UnsetSubscriptionStateChangeHandler». A chamada não recebe parâmetros de entrada e não retorna valor.

Tratamento de erros e simultaneidade

A interface é declarada como noexcept e, de acordo com a especificação, cumpre a propriedade exception safe [SWS_CM_11609]. A ocorrência de erros ou exceções está, portanto, excluída. Como o cancelamento do registro entra em vigor imediatamente, assume-se (interpretação) que nenhuma nova notificação seja repassada ao antigo manipulador após a conclusão do método. Pergunta Q-30238329b76b64f4 (aberta)

Interação

A função pertence às APIs básicas de classes proxy para o gerenciamento de assinaturas em ara::com AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s». Métodos semelhantes para desativar manipuladores de alterações de status existem para proxy events [SWS_CM_00334] e triggers [SWS_CM_01108], bem como de forma espelhada no lado do skeleton para events [SWS_CM_12010] e triggers [SWS_CM_01112].

usar

A função UnsetTransportFaultConditionHandler serve para cancelar novamente o registro de um ara::com::e2e::TransportFaultConditionHandler previamente registrado para o notificador de um determinado campo de proxy [SWS_CM_00126]. Ela está definida dentro do escopo <SI-Namespace>::proxy::fields::<Field> e é incluída através do arquivo de cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.1.4 «UnsetTransportFaultConditionHandler». A chamada é feita sem parâmetros e não fornece valor de retorno (void).

Tratamento de erros

O método está declarado como noexcept e possui a garantia de exceção exception safe [SWS_CM_00126]. Não são retornados códigos de erro nem lançadas exceções. Se nenhum handler tiver sido registrado anteriormente, uma chamada repetida deverá presumivelmente permanecer sem efeito. Pergunta Q-85da9a7b00678748 (aberta)

Simultaneidade e restrições

A especificação não define requisitos adicionais de concorrência ou segurança de threads. Como a interface opera de forma síncrona e não utiliza tipos assíncronos, a revogação do handler de erro deverá ter efeito síncrono e imediato. Pergunta Q-ed4cc712bb55aee5 (aberta) Os chamadores devem coordenar a chamada no ciclo de vida da aplicação de forma que mensagens de notificador de instâncias de serviço individuais não sejam processadas descontroladamente sem handler AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 «End-to-end communication protection for SOMEIP».

Interação

O cancelamento de registro segue um padrão consistente de nomes e funções no AUTOSAR Adaptive:

• No nível de proxy, funções equivalentes estão disponíveis para eventos ([SWS_CM_00105]) bem como para disparadores ([SWS_CM_00108]).
• No nível de skeleton, existem contrapartes correspondentes para getters e setters de campo ([SWS_CM_00098]), bem como de forma abrangente para todos os métodos da interface do skeleton ([SWS_CM_00095]).