classe <SI-Namespace>::proxy::events::<Event>

usar

A função SetReceiveHandler serve no lado do cliente, no escopo <SI-Namespace>::proxy::events::<Event>, para registrar um manipulador de callback para eventos recebidos [SWS_CM_00181]. Como parâmetro, é passado um ara::com::EventReceiveHandler, definido como uma função sem parâmetros e chamado pelo Communication Management quando um evento chega [SWS_CM_00181]. A função não possui valor de retorno (void) [SWS_CM_00181].

Tratamento de erros e comportamento com exceções

A operação é especificada como noexcept e segura contra exceções (exception safe) [SWS_CM_00181]. Se o callable fornecido não existir ou for null, isso é considerado um InvalidHandlerViolation [SWS_CM_00181].

Contexto de execução e interação

Dentro das interfaces de proxy, SetReceiveHandler pertence aos mecanismos fundamentais, juntamente com chamadas como UnsetReceiveHandler() e GetNewSamples() ARAComAPI §5.3.1 «Proxy Class API’s». Se o manipulador deve ser executado em um contexto predefinido, a sobrecarga de template com ExecutorT está disponível [SWS_CM_11356] (ARAComAPI p. 10).

A mesma abordagem de notificação também é utilizada para triggers via [SWS_CM_00250] (com contexto: [SWS_CM_00352]), bem como para fields via [SWS_CM_11605] (com contexto: [SWS_CM_11611]) ARAComAPI §4.2 «Means of Communication».

O método SetSubscriptionStateChangeHandler no namespace proxy::events::<Event> regista uma função de callback que o Communication Management chama assim que o estado ara::com::SubscriptionState do evento se altera ([SWS_CM_00333]). A função está declarada como noexcept e é considerada segura contra exceções ([SWS_CM_00333]).

Uso e semântica assíncrona

As chamadas a Subscribe() funcionam por princípio de forma assíncrona; uma subscrição bem-sucedida só pode ser considerada concluída quando o manipulador registado ou GetSubscriptionState() reportar o estado kSubscribed ([SWS_CM_12006]). O manipulador é chamado com kSubscriptionPending se a subscrição não entrar em vigor imediatamente (por exemplo, em virtude de latências do protocolo de barramento) ou se a instância do servidor estiver inacessível devido a reinicializações ou falhas de rede ([SWS_CM_00313]). O cancelamento do registo do manipulador é realizado através de UnsetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 «Proxy Class API’s»).

Tratamento de erros e condições de contorno

Se não for passado nenhum objeto de callback válido ou se este for null, ocorre o caso de erro InvalidHandlerViolation ([SWS_CM_00333]). Quanto à ordem de chamada, o manipulador deverá convenientemente ser registado antes de Subscribe(), a fim de capturar transições precoces de estado com fiabilidade. Pergunta Q-3b9c25c6aa2d0a0f (aberta)

Interação e variantes

Para a execução do manipulador num contexto de thread ou de trabalho predefinido, está disponível a variante de modelo sobrecarregada com o parâmetro ExecutorT ([SWS_CM_11354]). Existem interfaces paralelas para triggers de proxy ([SWS_CM_01107]), campos de proxy ([SWS_CM_11607]), bem como ao nível do skeleton ([SWS_CM_12008]).

A função-membro de modelo SetSubscriptionStateChangeHandler serve, no âmbito proxy::events::<Event>, para registar uma função de callback para alterações de estado da subscrição (ara::com::SubscriptionState) ([SWS_CM_11354], AP EXP ARAComAPI §5.3.1 «Proxy Class API’s»). Ao contrário da função básica [SWS_CM_00333], o manipulador não é executado no contexto interno do Communication Management, sendo em vez disso passado através do parâmetro de modelo ExecutorT para um contexto de execução executor fornecido ([SWS_CM_11360], AP EXP ARAComAPI §1.0 «SetSubscriptionState with ExecutorT»).

Parâmetros e valores de retorno

• handler: O invocável a ser chamado, que é notificado mediante uma alteração do ara::com::SubscriptionState do evento ([SWS_CM_00333]).
• executor: O contexto de execução de acordo com [SWS_CM_11360] no qual o manipulador deve ser processado.
• Valor de retorno: A função não possui qualquer valor de retorno (void).

Tratamento de erros e execução

A função está declarada como noexcept e especificada como segura contra exceções (exception safe). Se o invocável passado handler não existir ou for null, é desencadeada uma InvalidHandlerViolation ([SWS_CM_11354]).

Interação

O padrão de monitorização de estado vinculada a contexto com ExecutorT existe de forma análoga para triggers de proxy ([SWS_CM_01106]) bem como campos de proxy ([SWS_CM_11608]). Se não for necessária a delegação para um contexto específico, está disponível a variante [SWS_CM_00333].

A função-membro SetTransportFaultConditionHandler serve para registar uma função de callback do tipo ara::com::e2e::TransportFaultConditionHandler num evento de proxy ([SWS_CM_00099]). Através deste manipulador são comunicados erros de transmissão detetados na camada de transporte do binding de comunicação ([SWS_CM_00211]).

Utilização e semântica:

• Chamada e parâmetros: A função recebe o objeto invocável de manipulador handler e não fornece qualquer valor de retorno ([SWS_CM_00099]). A assinatura do método está declarada como noexcept ([SWS_CM_00099]).
• Estados de erro transmitidos: Em caso de erro, o manipulador registado comunica valores do enum ara::com::e2e::TransportFaultCondition, como por exemplo kSampleRejected no caso de amostras descartadas do canal de transporte subjacente ([SWS_CM_00211]).
• Contexto de execução: Para execuções assíncronas, está disponível uma sobrecarga de modelo com um objeto executor adicional ExecutorT&& executor ([SWS_CM_00100]).

Tratamento de erros e restrições:

• Segurança contra exceções: A função é considerada segura contra exceções (exception safe) ([SWS_CM_00099]).
• Violações: Se o invocável passado não existir ou for null, ocorre uma InvalidHandlerViolation ([SWS_CM_00099]).
• Interação: Existem também interfaces equivalentes para o registo de um TransportFaultConditionHandler para triggers ([SWS_CM_00106]), notificadores de campos ([SWS_CM_00109]) e métodos skeleton ([SWS_CM_00093]).

A função de modelo SetTransportFaultConditionHandler regista num evento de proxy um manipulador específico da aplicação do tipo ara::com::e2e::TransportFaultConditionHandler juntamente com um executor definido pelo utilizador ([SWS_CM_00100]). Representa a sobrecarga de contexto de execução para a função básica com menos parâmetros ([SWS_CM_00099]).

Utilização e parâmetros: O método é chamado em instâncias de <SI-Namespace>::proxy::events::<Event> e não devolve qualquer valor (void) ([SWS_CM_00100]). Recebe o manipulador a chamar (handler) e aceita um objeto executor (executor como referência universal ExecutorT&&), em cujo contexto é iniciada qualquer execução assíncrona do manipulador ([SWS_CM_00100]). A assinatura da função está declarada com noexcept ([SWS_CM_00100]).

Tratamento de erros: A operação está especificada como exception safe ([SWS_CM_00100]). Se for passado um invocável inválido ou inexistente (null), ocorre uma violação sob a forma de InvalidHandlerViolation ([SWS_CM_00100]). Através do manipulador registado são comunicados erros de transporte detetados, tais como TransportFaultCondition::kSampleRejected aquando do descarte de amostras de dados de entrada pela entidade de transporte subjacente ([SWS_CM_00211]).

Interação: Enquanto [SWS_CM_00099] realiza o registo sem um executor explícito, esta sobrecarga permite a execução no contexto pretendido de thread ou de tarefa ([SWS_CM_00100]). Estão disponíveis sobrecargas análogas com executor para métodos skeleton ([SWS_CM_00094]) e campos skeleton ([SWS_CM_00097]), bem como do lado do proxy para triggers ([SWS_CM_00107]) e notificadores de campos ([SWS_CM_00110]).

usar

O método Subscribe registra o elemento de proxy para o recebimento de eventos de serviço de acordo com [SWS_CM_00141]. A chamada é de natureza assíncrona: o retorno da função apenas confirma que o Communication Management aceitou a solicitação de registro (AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 «Monitoring Event Subscription»). Com o parâmetro obrigatório maxSampleCount, a aplicação informa vinculativamente quantas amostras de evento ela manterá simultaneamente no máximo, inicializando assim o buffer de recepção local (AUTOSAR_AP_EXP_ARAComAPI p. 40).

Tratamento de erros e condições de contorno

Se, no momento da chamada, o evento já estiver no estado kSubscribed ou kSubscriptionPending e o valor maxSampleCount passado coincidir com a subscrição ativa, o método retorna com sucesso sem nenhuma ação ([SWS_CM_00141]). Se, pelo contrário, o tamanho do cache divergir em uma nova subscrição, a chamada falha e retorna no ara::core::Result o código de erro ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_00141]). Em caso de permissões de acesso ausentes, a chamada é recusada (InsufficientPermissionsViolation de acordo com [SWS_CM_00141]). A assinatura está declarada como noexcept e é considerada segura contra exceções.

Interação

A capacidade de cache reservada limita a posterior recepção de dados via GetNewSamples ([SWS_CM_00701]); se a aplicação retiver mais ponteiros inteligentes do que o especificado, o erro ComErrc::kMaxSamplesExceeded é disparado ([SWS_CM_10432]). Enquanto eventos de campo são subscritos de forma idêntica via maxSampleCount ([SWS_CM_11601]), eventos puramente de disparo não requerem indicação de tamanho de buffer ([SWS_CM_00723]).

usar

A função UnsetReceiveHandler faz parte do wrapper de eventos no âmbito <SI-Namespace>::proxy::events::<Event> e é incluída através do ficheiro de cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00183]). Não recebe parâmetros de transferência e não possui valor de retorno (void). Através da chamada, um handler de receção específico da aplicação previamente registado com SetReceiveHandler para um evento de serviço volta a ser removido (EXP ARAComAPI §5.3.2 «RadarService Proxy Class Example»). Desta forma, a aplicação recetora pode alternar a qualquer momento entre uma receção orientada a eventos («event-driven») e uma operação ativa por consulta («polling style») por meio de GetNewSamples() (EXP ARAComAPI §5.3.2 «RadarService Proxy Class Example»).

Tratamento de erros

O método está declarado com noexcept e possui a propriedade exception safe ([SWS_CM_00183]). Em tempo de execução, não lança exceções nem reporta códigos de erro específicos.

Concorrência e vinculação

Enquanto para o callback handler registado se aplica que este não precisa de ser reentrante, porque o Communication Management serializa as chamadas (EXP ARAComAPI §5.3.2 «RadarService Proxy Class Example»), UnsetReceiveHandler desativa o trigger de evento para a receção de novas notificações ([SWS_CM_00183]). No contexto do binding DDS, o método UnsetReceiveHandler() é mapeado, de acordo com [SWS_CM_11141] e em conformidade com a especificação [SWS_CM_11026], para o respetivo DataReader.

Interação

A função constitui a contraparte direta do registo através de SetReceiveHandler ([SWS_CM_11140], EXP ARAComAPI §5.3.1 «Proxy Class API’s»). Encontram-se funções relacionadas noutras interfaces de proxy:

• Para campos, existe uma função com o mesmo nome UnsetReceiveHandler no âmbito <SI-Namespace>::proxy::fields::<Field>, a qual também está definida como noexcept e exception safe ([SWS_CM_11606]).
• Para triggers, UnsetReceiveHandler está disponível no âmbito <SI-Namespace>::proxy::triggers::<Trigger>, mas está declarada de forma divergente como not exception safe ([SWS_CM_11614]).

usar

A função-membro UnsetSubscriptionStateChangeHandler destina-se à reposição e ao desregisto de um manipulador de callback previamente definido para alterações do estado de subscrição (ara::com::SubscriptionState) no lado do proxy ([SWS_CM_00334], EXP ARAComAPI §1.0). A função é parte integrante da interface de eventos e localiza-se no espaço de nomes específico da aplicação em proxy::events ([SWS_CM_00334], SWS CommunicationManagement §8.3.2.2.4.5 «UnsetSubscriptionStateChangeHandler»). Para a utilização, inclui-se o ficheiro de cabeçalho proxy gerado <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h ([SWS_CM_00334]). A chamada ocorre de forma síncrona, não aceita parâmetros e não fornece valor de retorno ([SWS_CM_00334]).

Tratamento de erros

De acordo com a especificação, a função está declarada com o identificador noexcept e classificada como segura quanto a exceções («exception safe») ([SWS_CM_00334]). Em caso de erro, não lança exceções C++ e não devolve códigos de erro ([SWS_CM_00334]).

Concorrência e interação

A função integra-se com outras APIs de proxy para pesquisa de serviços e gestão de eventos, tais como Subscribe(), Unsubscribe(), GetSubscriptionState() e SetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 «Proxy Class API’s»). Como interpretação, após a chamada não deverão ser acionadas mais notificações através do manipulador desregistado. Pergunta Q-6173c01e6ca93876 (aberta) Contrapartes simétricas para reposição de manipuladores para alterações de estado estão definidas na especificação para campos (fields) de proxy ([SWS_CM_11609], SWS CommunicationManagement §8.3.3.2.4.5 «UnsetSubscriptionStateChangeHandler») e triggers ([SWS_CM_01108]), bem como no lado do fornecedor de serviços (skeleton) para eventos ([SWS_CM_12010]) e triggers ([SWS_CM_01112]).

usar

A função UnsetTransportFaultConditionHandler no namespace <SI-Namespace>::proxy::events::<Event> serve para cancelar o registro de um ara::com::e2e::TransportFaultConditionHandler previamente registrado para um evento de proxy concreto [SWS_CM_00105]. A declaração da função é fornecida através do arquivo de cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.1.3 «UnsetTransportFaultConditionHandler». A chamada não aceita parâmetros e não fornece valor de retorno (void).

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

A função está declarada com o identificador noexcept e especificada como segura contra exceções (exception safe) [SWS_CM_00105]. Nem códigos de erro específicos nem notificações para subsistemas de erro ou diagnóstico estão definidos no padrão.

Fluxo e condições de contorno

A chamada deve ser executada de forma síncrona para desativar imediatamente o tratamento de erros de E2E no nível de eventos, por exemplo, quando o evento não deve mais ser monitorado ou antes que o objeto proxy correspondente seja liberado (interpretação). Pergunta Q-ff00695fff5407fe (aberta) Após a execução, a camada de comunicação não processa mais erros de transporte de E2E através do callback anteriormente configurado deste evento.

Interação

O cancelamento de registro de handlers para erros de transporte segue um padrão uniforme através de diferentes elementos de comunicação:

• Para notificadores de campos no nível do proxy, serve a função [SWS_CM_00126].
• Para disparadores de proxy, o handler é cancelado através de [SWS_CM_00108].
• No lado do skeleton, estão disponíveis interfaces análogas para todos os métodos de uma interface de serviço ([SWS_CM_00095]), bem como para getters/setters de campos ([SWS_CM_00098]).

usar

O método Unsubscribe() encerra a assinatura ativa de um evento de serviço no lado do proxy ([SWS_CM_00151], EXP_ARAComAPI §5.5). Ele é definido no escopo <SI-Namespace>::proxy::events::<Event> e é incluído através do arquivo de cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00151]). A função não recebe parâmetros de entrada e não fornece valor de retorno (void). Se o evento não estava assinado no momento da chamada, o método retorna sem executar nenhuma ação ([SWS_CM_00151]).

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

A operação é declarada com o identificador noexcept e especificada como segura contra exceções ([SWS_CM_00151]). Como violação (violation), está prevista uma DanglingSamplesViolation, caso a pré-condição de acordo com [SWS_CM_00085] tenha sido violada antes da chamada do método ([SWS_CM_00151]).

Interação e interfaces relacionadas

No nível de rede, o encerramento da assinatura aciona o envio de mensagens SOME/IP do tipo StopSubscribeEventgroup ([SWS_CM_10378], SWS_CommunicationManagement §7.2.1.2.6). Dentro das interfaces de proxy, Unsubscribe() pertence ao grupo de métodos para gerenciamento de assinaturas (EXP_ARAComAPI §5.3.1). Uma semântica de cancelamento de assinatura idêntica também está disponível para acionadores de serviço (triggers) ([SWS_CM_00810], EXP_ARAComAPI §4), bem como para notificações de campo (field) ([SWS_CM_11602]).