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

usar

La función SetReceiveHandler sirve en el lado del cliente, dentro del ámbito <SI-Namespace>::proxy::events::<Event>, para registrar un manejador de callback para sucesos entrantes [SWS_CM_00181]. Como parámetro se pasa un ara::com::EventReceiveHandler, que está definido como una función sin parámetros y es invocado por Communication Management al recibir un evento [SWS_CM_00181]. La función no tiene valor de retorno (void) [SWS_CM_00181].

Tratamiento de errores y comportamiento ante excepciones

La operación está especificada como noexcept y segura frente a excepciones (exception safe) [SWS_CM_00181]. Si el invocable suministrado no existe o es null, esto se considera como InvalidHandlerViolation [SWS_CM_00181].

Contexto de ejecución e interacción

Dentro de las interfaces de proxy, SetReceiveHandler pertenece a los mecanismos fundamentales junto a llamadas como UnsetReceiveHandler() y GetNewSamples() ARAComAPI §5.3.1 «Proxy Class API’s». Si el manejador debe ejecutarse en un contexto determinado, se encuentra disponible la sobrecarga de plantilla con ExecutorT [SWS_CM_11356] (ARAComAPI p. 10).

El mismo enfoque de notificación se utiliza también para disparadores mediante [SWS_CM_00250] (con contexto: [SWS_CM_00352]), así como para campos mediante [SWS_CM_11605] (con contexto: [SWS_CM_11611]) ARAComAPI §4.2 «Means of Communication».

El método SetSubscriptionStateChangeHandler en el espacio de nombres proxy::events::<Event> registra una función de retrollamada a la que llama Communication Management en cuanto cambia el estado ara::com::SubscriptionState del evento ([SWS_CM_00333]). La función está declarada como noexcept y se considera segura ante excepciones ([SWS_CM_00333]).

Uso y semántica asíncrona

Las llamadas a Subscribe() funcionan por principio de forma asíncrona; una suscripción correcta solo debe considerarse completada cuando el manejador registrado o GetSubscriptionState() devuelva el estado kSubscribed ([SWS_CM_12006]). Se invoca el manejador con kSubscriptionPending si la suscripción no surte efecto inmediatamente (por ejemplo, como resultado de latencias del protocolo de bus) o si la instancia del servidor no está accesible debido a reinicios o errores de red ([SWS_CM_00313]). La cancelación del registro del manejador se realiza mediante UnsetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 «Proxy Class API’s»).

Tratamiento de errores y condiciones límite

Si no se pasa un objeto de retrollamada válido o si este es null, se produce el caso de error InvalidHandlerViolation ([SWS_CM_00333]). En cuanto al orden de llamadas, es de esperar que el manejador se registre convenientemente antes de Subscribe() para capturar con fiabilidad las transiciones de estado tempranas. Pregunta Q-3b9c25c6aa2d0a0f (abierta)

Interacción y variantes

Para la ejecución del manejador en un contexto de hilo o de trabajo predeterminado, está disponible la variante de plantilla sobrecargada con el parámetro ExecutorT ([SWS_CM_11354]). Existen interfaces paralelas para disparadores de proxy ([SWS_CM_01107]), campos de proxy ([SWS_CM_11607]) y a nivel de esqueleto ([SWS_CM_12008]).

La función miembro de plantilla SetSubscriptionStateChangeHandler sirve en el ámbito proxy::events::<Event> para registrar una función de retrollamada para cambios de estado de la suscripción (ara::com::SubscriptionState) ([SWS_CM_11354], AP EXP ARAComAPI §5.3.1 «Proxy Class API’s»). A diferencia de la función básica [SWS_CM_00333], el manejador no se ejecuta en el contexto interno de Communication Management, sino que se pasa mediante el parámetro de plantilla ExecutorT a un contexto de ejecución executor proporcionado ([SWS_CM_11360], AP EXP ARAComAPI §1.0 «SetSubscriptionState with ExecutorT»).

Parámetros y valores de retorno

• handler: el invocable que se debe llamar, al que se notifica cuando se produce un cambio en el ara::com::SubscriptionState del evento ([SWS_CM_00333]).
• executor: el contexto de ejecución según [SWS_CM_11360] en el que se debe procesar el manejador.
• Valor de retorno: la función no tiene valor de retorno (void).

Tratamiento de errores y ejecución

La función está declarada como noexcept y especificada como segura ante excepciones (exception safe). Si el invocable handler pasado no existe o es null, se desencadena una InvalidHandlerViolation ([SWS_CM_11354]).

Interacción

El patrón de monitorización de estado vinculada a un contexto con ExecutorT existe de forma análoga para disparadores de proxy ([SWS_CM_01106]) y campos de proxy ([SWS_CM_11608]). Si no se requiere delegar a un contexto específico, se encuentra disponible la variante [SWS_CM_00333].

La función miembro SetTransportFaultConditionHandler sirve, en un evento de Proxy ([SWS_CM_00099]), para registrar una función de callback del tipo ara::com::e2e::TransportFaultConditionHandler. A través de este gestor se notifican errores de transmisión que se detectan en la capa de transporte del enlace de comunicación (communication binding) ([SWS_CM_00211]).

Uso y semántica:

• Llamada y parámetros: La función recibe el objeto gestor invocable handler y no devuelve ningún valor ([SWS_CM_00099]). La firma del método está declarada como noexcept ([SWS_CM_00099]).
• Estados de error transmitidos: En caso de error, el gestor registrado notifica valores del enum ara::com::e2e::TransportFaultCondition, como por ejemplo kSampleRejected en caso de muestras descartadas del canal de transporte subyacente ([SWS_CM_00211]).
• Contexto de ejecución: Para ejecuciones asíncronas está disponible una sobrecarga de plantilla con un objeto ejecutor adicional ExecutorT&& executor ([SWS_CM_00100]).

Tratamiento de errores y condiciones límite:

• Seguridad ante excepciones: La función se considera segura ante excepciones (exception safe) ([SWS_CM_00099]).
• Infracciones: Si el invocable proporcionado no existe o es null, se produce una InvalidHandlerViolation ([SWS_CM_00099]).
• Interacción: También existen interfaces equivalentes para registrar un TransportFaultConditionHandler para disparadores ([SWS_CM_00106]), notificadores de campo ([SWS_CM_00109]) y métodos de Skeleton ([SWS_CM_00093]).

La función de plantilla SetTransportFaultConditionHandler registra en un evento de Proxy un gestor específico de la aplicación de tipo ara::com::e2e::TransportFaultConditionHandler junto con un ejecutor personalizado ([SWS_CM_00100]). Representa la sobrecarga con contexto de ejecución frente a la función básica con menos parámetros ([SWS_CM_00099]).

Uso y parámetros: El método se invoca en instancias de <SI-Namespace>::proxy::events::<Event> y no devuelve ningún valor (void) ([SWS_CM_00100]). Recibe el gestor que se va a invocar (handler) y toma un objeto ejecutor (executor como referencia universal ExecutorT&&), en cuyo contexto se inicia cualquier ejecución asíncrona del gestor ([SWS_CM_00100]). La firma de la función está declarada con noexcept ([SWS_CM_00100]).

Tratamiento de errores: la operación está especificada como exception safe ([SWS_CM_00100]). Si se pasa un invocable no válido o no existente (null), se produce una infracción en forma de InvalidHandlerViolation ([SWS_CM_00100]). A través del manejador registrado se notifican los errores de transporte detectados, como por ejemplo TransportFaultCondition::kSampleRejected al descartar muestras de datos entrantes por parte de la entidad de transporte subyacente ([SWS_CM_00211]).

Interacción: mientras que [SWS_CM_00099] realiza el registro sin un ejecutor explícito, esta sobrecarga permite la ejecución en el contexto de hilo o tarea deseado ([SWS_CM_00100]). Existen sobrecargas análogas con ejecutor para métodos de esqueleto ([SWS_CM_00094]) y campos de esqueleto ([SWS_CM_00097]), así como en el lado del proxy para disparadores ([SWS_CM_00107]) y notificadores de campo ([SWS_CM_00110]).

usar

El método Subscribe registra el elemento de proxy para la recepción de eventos de servicio según [SWS_CM_00141]. La invocación es de naturaleza asíncrona: el retorno de la función únicamente confirma que Communication Management ha aceptado la solicitud de registro (AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 «Monitoring Event Subscription»). Mediante el parámetro obligatorio maxSampleCount, la aplicación comunica de forma vinculante cuántas muestras de eventos conservará como máximo de forma simultánea, inicializando con ello el búfer de recepción local (AUTOSAR_AP_EXP_ARAComAPI p. 40).

Tratamiento de errores y condiciones límite

Si el evento ya se encuentra en el estado kSubscribed o kSubscriptionPending en el momento de la llamada y el valor maxSampleCount transmitido coincide con la suscripción activa, el método retorna satisfactoriamente sin realizar acción alguna ([SWS_CM_00141]). Si, por el contrario, el tamaño de la caché difiere en una nueva suscripción, la invocación falla y devuelve en ara::core::Result el código de error ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_00141]). En caso de no disponer de los permisos de acceso requeridos, se deniega la invocación (InsufficientPermissionsViolation de acuerdo con [SWS_CM_00141]). La firma está declarada como noexcept y se considera segura frente a excepciones.

Interacción

La capacidad reservada de la caché limita la recepción posterior de datos a través de GetNewSamples ([SWS_CM_00701]); si la aplicación retiene más punteros inteligentes de lo especificado, se genera el error ComErrc::kMaxSamplesExceeded ([SWS_CM_10432]). Mientras que los eventos de campo se suscriben de forma idéntica mediante maxSampleCount ([SWS_CM_11601]), los eventos de disparador puros no requieren indicación de tamaño de búfer ([SWS_CM_00723]).

usar

La función UnsetReceiveHandler forma parte del contenedor de eventos en el ámbito <SI-Namespace>::proxy::events::<Event> y se incluye a través del archivo de cabecera #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00183]). No recibe parámetros de entrada y no tiene valor de retorno (void). Mediante la llamada, se vuelve a eliminar un manejador de recepción específico de la aplicación para un evento de servicio registrado previamente con SetReceiveHandler (EXP ARAComAPI §5.3.2 «RadarService Proxy Class Example»). De este modo, la aplicación receptora puede cambiar en cualquier momento entre una recepción dirigida por eventos («event-driven») y un modo de consulta activa («polling style») mediante GetNewSamples() (EXP ARAComAPI §5.3.2 «RadarService Proxy Class Example»).

Manejo de errores

El método está declarado con noexcept y posee la propiedad exception safe ([SWS_CM_00183]). En tiempo de ejecución no lanza excepciones ni notifica códigos de error específicos.

Concurrencia y enlace

Mientras que para el manejador de callback registrado se aplica que no necesita ser reentrante, dado que el Communication Management serializa las llamadas (EXP ARAComAPI §5.3.2 «RadarService Proxy Class Example»), UnsetReceiveHandler desactiva el disparador de eventos para la recepción de más notificaciones ([SWS_CM_00183]). En el contexto del enlace DDS, el método UnsetReceiveHandler() según [SWS_CM_11141] se asigna al DataReader correspondiente de conformidad con la especificación [SWS_CM_11026].

Interacción

La función constituye la contraparte directa del registro mediante SetReceiveHandler ([SWS_CM_11140], EXP ARAComAPI §5.3.1 «Proxy Class API’s»). Se encuentran funciones afines en otras interfaces de proxy:

• Para campos existe una función con el mismo nombre UnsetReceiveHandler en el ámbito <SI-Namespace>::proxy::fields::<Field>, que también está definida como noexcept y exception safe ([SWS_CM_11606]).
• Para disparadores está disponible UnsetReceiveHandler en el ámbito <SI-Namespace>::proxy::triggers::<Trigger>, pero a diferencia de estos está declarada como not exception safe ([SWS_CM_11614]).

usar

La función miembro UnsetSubscriptionStateChangeHandler sirve para restablecer y desregistrar un manejador de callback configurado previamente para cambios del estado de suscripción (ara::com::SubscriptionState) en el lado del proxy ([SWS_CM_00334], EXP ARAComAPI §1.0). La función forma parte de la interfaz de eventos y se encuentra en el espacio de nombres específico de la aplicación bajo proxy::events ([SWS_CM_00334], SWS CommunicationManagement §8.3.2.2.4.5 «UnsetSubscriptionStateChangeHandler»). Para su uso, se incluye el archivo de cabecera de proxy generado <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h ([SWS_CM_00334]). La llamada se realiza de forma sincrónica, no recibe parámetros y no devuelve ningún valor ([SWS_CM_00334]).

Manejo de errores

Según la especificación, la función está declarada con el identificador noexcept y clasificada como segura frente a excepciones («exception safe») ([SWS_CM_00334]). En caso de error, no lanza excepciones de C++ ni devuelve códigos de error ([SWS_CM_00334]).

Concurrencia e interacción

La función actúa conjuntamente con otras API del proxy para la búsqueda de servicios y la gestión de eventos como Subscribe(), Unsubscribe(), GetSubscriptionState() y SetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 «Proxy Class API’s»). Como interpretación, es previsible que tras la llamada no se activen más notificaciones a través del manejador desregistrado. Pregunta Q-6173c01e6ca93876 (abierta) En la especificación se definen contrapartes simétricas para restablecer manejadores ante cambios de estado para Fields ([SWS_CM_11609], SWS CommunicationManagement §8.3.3.2.4.5 «UnsetSubscriptionStateChangeHandler») y Triggers ([SWS_CM_01108]) del proxy, así como en el lado del proveedor de servicios (skeleton) para Events ([SWS_CM_12010]) y Triggers ([SWS_CM_01112]).

usar

La función UnsetTransportFaultConditionHandler en el espacio de nombres <SI-Namespace>::proxy::events::<Event> sirve para cancelar el registro de un ara::com::e2e::TransportFaultConditionHandler registrado previamente para un evento de proxy concreto [SWS_CM_00105]. La declaración de la función se proporciona a través del archivo de cabecera <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.1.3 «UnsetTransportFaultConditionHandler». La llamada no acepta parámetros y no devuelve ningún valor (void).

Tratamiento de fallos y seguridad frente a excepciones

La función está declarada con el identificador noexcept y especificada como segura frente a excepciones (exception safe) [SWS_CM_00105]. En el estándar no se definen códigos de error específicos ni notificaciones a subsistemas de diagnóstico o de error.

Secuencia y condiciones marco

Es de prever que la llamada se ejecute de forma síncrona para desactivar inmediatamente el tratamiento de errores E2E a nivel de evento, por ejemplo, cuando el evento ya no deba ser monitorizado o antes de que se libere el objeto proxy correspondiente (interpretación). Pregunta Q-ff00695fff5407fe (abierta) Tras la ejecución, la capa de comunicación deja de procesar errores de transporte E2E a través de la retrollamada configurada previamente para este evento.

Interacción

La cancelación del registro de manejadores para errores de transporte sigue un patrón uniforme a través de diversos elementos de comunicación:

• Para notificadores de campos a nivel de proxy se utiliza la función [SWS_CM_00126].
• Para activadores de proxy, el manejador se da de baja mediante [SWS_CM_00108].
• En el lado del Skeleton se dispone de interfaces análogas para la totalidad de métodos de una interfaz de servicio ([SWS_CM_00095]), así como para getters/setters de campos ([SWS_CM_00098]).

usar

El método Unsubscribe() finaliza la suscripción activa a un evento de servicio en el lado del proxy ([SWS_CM_00151], EXP_ARAComAPI §5.5). Está definido en el ámbito de validez <SI-Namespace>::proxy::events::<Event> y se incluye mediante el archivo de cabecera #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00151]). La función no acepta parámetros de entrada y no devuelve ningún valor (void). Si el evento no estaba suscrito en el momento de la llamada, el método retorna sin ejecutar ninguna acción ([SWS_CM_00151]).

Tratamiento de errores y seguridad frente a excepciones

La operación está declarada con el identificador noexcept y especificada como segura frente a excepciones ([SWS_CM_00151]). Como infracción (violation) está prevista una DanglingSamplesViolation en caso de que, antes de la llamada al método, se haya infringido la condición previa según [SWS_CM_00085] ([SWS_CM_00151]).

Interacción e interfaces relacionadas

A nivel de red, la finalización de la suscripción desencadena el envío de mensajes SOME/IP del tipo StopSubscribeEventgroup ([SWS_CM_10378], SWS_CommunicationManagement §7.2.1.2.6). Dentro de las interfaces de proxy, Unsubscribe() pertenece al grupo de métodos para la gestión de suscripciones (EXP_ARAComAPI §5.3.1). Una semántica de cancelación de suscripción idéntica también está disponible para disparadores de servicio ([SWS_CM_00810], EXP_ARAComAPI §4), así como para notificaciones de campos ([SWS_CM_11602]).