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

Gebruik

De functie SetReceiveHandler dient aan clientzijde in de scope <SI-Namespace>::proxy::events::<Event> voor de registratie van een callback-handler voor binnenkomende gebeurtenissen [SWS_CM_00181]. Als parameter wordt een ara::com::EventReceiveHandler doorgegeven, die gedefinieerd is als een parameterloze functie en bij event-ontvangst door Communication Management wordt aangeroepen [SWS_CM_00181]. De functie heeft geen retourwaarde (void) [SWS_CM_00181].

Foutafhandeling en uitzonderingsgedrag

De bewerking is gespecificeerd als noexcept en uitzonderingsveilig (exception safe) [SWS_CM_00181]. Indien het meegegeven callable niet bestaat of null is, wordt dit als InvalidHandlerViolation beschouwd [SWS_CM_00181].

Uitvoeringscontext en interactie

Binnen de proxy-interfaces behoort SetReceiveHandler tot de basismechanismen naast aanroepen zoals UnsetReceiveHandler() en GetNewSamples() ARAComAPI §5.3.1 “Proxy Class API’s”. Indien de handler in een vooraf opgegeven context moet worden uitgevoerd, staat de template-overload met ExecutorT ter beschikking [SWS_CM_11356] (ARAComAPI p. 10).

Dezelfde notificatiebenadering wordt ook gebruikt voor triggers via [SWS_CM_00250] (met context: [SWS_CM_00352]) en voor fields via [SWS_CM_11605] (met context: [SWS_CM_11611]) ARAComAPI §4.2 “Means of Communication”.

De methode SetSubscriptionStateChangeHandler in de namespace proxy::events::<Event> registreert een callback-functie die door Communication Management wordt aangeroepen zodra de toestand ara::com::SubscriptionState van het event verandert ([SWS_CM_00333]). De functie is gedeclareerd als noexcept en geldt als uitzonderingsveilig ([SWS_CM_00333]).

Gebruik en asynchrone semantiek

Aanroepen van Subscribe() werken in beginsel asynchroon; een succesvol abonnement mag pas als voltooid worden beschouwd wanneer de geregistreerde handler of GetSubscriptionState() de toestand kSubscribed terugmeldt ([SWS_CM_12006]). De handler wordt aangeroepen met kSubscriptionPending wanneer het abonnement niet onmiddellijk van kracht wordt (bijvoorbeeld als gevolg van busprotocol-latenties) of wanneer de serverinstantie wegens herstarts of netwerkfouten niet bereikbaar is ([SWS_CM_00313]). Het opheffen van de handler-registratie gebeurt via UnsetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 “Proxy Class API’s”).

Foutafhandeling en randvoorwaarden

Indien er geen geldig callback-object wordt doorgegeven of indien dit null is, doet zich het foutgeval InvalidHandlerViolation voor ([SWS_CM_00333]). Wat de aanroepvolgorde betreft, verdient het aanbeveling de handler vóór Subscribe() te registreren, om vroege statusovergangen betrouwbaar te detecteren. Vraag Q-3b9c25c6aa2d0a0f (open)

Interactie en varianten

Voor de uitvoering van de handler in een vooraf bepaalde thread- of werkcontext staat de overbelaste template-variant met parameter ExecutorT gereed ([SWS_CM_11354]). Parallelle interfaces bestaan voor proxy-triggers ([SWS_CM_01107]), proxy-fields ([SWS_CM_11607]) en op skeleton-niveau ([SWS_CM_12008]).

De template-lidfunctie SetSubscriptionStateChangeHandler dient er in de scope proxy::events::<Event> voor om een callback-functie voor toestandsveranderingen van het abonnement (ara::com::SubscriptionState) te registreren ([SWS_CM_11354], AP EXP ARAComAPI §5.3.1 “Proxy Class API’s”). In tegenstelling tot de basisfunctie [SWS_CM_00333] wordt de handler niet uitgevoerd in de interne context van Communication Management, maar via de template-parameter ExecutorT overgedragen aan een ter beschikking gestelde uitvoeringscontext executor ([SWS_CM_11360], AP EXP ARAComAPI §1.0 “SetSubscriptionState with ExecutorT”).

Parameters en retourwaarden

• handler: Het aan te roepen callable dat bij een wijziging van de ara::com::SubscriptionState van het event wordt gewaarschuwd ([SWS_CM_00333]).
• executor: De uitvoeringscontext volgens [SWS_CM_11360] waarin de handler moet worden verwerkt.
• Retourwaarde: De functie heeft geen retourwaarde (void).

Foutafhandeling en uitvoering

De functie is gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig (exception safe). Indien het meegegeven callable handler niet bestaat of null is, wordt een InvalidHandlerViolation geactiveerd ([SWS_CM_11354]).

Samenspel

Het patroon van contextgebonden statusbewaking met ExecutorT bestaat analoog voor proxy-triggers ([SWS_CM_01106]) en proxy-velden ([SWS_CM_11608]). Indien uitbesteding naar een specifieke context niet vereist is, staat de variant [SWS_CM_00333] ter beschikking.

De lidfunctie SetTransportFaultConditionHandler dient bij een proxy-event ([SWS_CM_00099]) voor de registratie van een callback-functie van het type ara::com::e2e::TransportFaultConditionHandler. Via deze handler worden overdrachtsfouten gemeld die op de transportlaag van de communicatie-binding worden gedetecteerd ([SWS_CM_00211]).

Gebruik en semantiek:

• Aanroep en parameters: De functie neemt het aanroepbare handler-object handler in ontvangst en levert geen retourwaarde op ([SWS_CM_00099]). De methodesignatuur is gedeclareerd als noexcept ([SWS_CM_00099]).
• Overgedragen fouttoestanden: De geregistreerde handler meldt in geval van fouten waarden van de enum ara::com::e2e::TransportFaultCondition, zoals bijvoorbeeld kSampleRejected bij verworpen samples van het onderliggende transportkanaal ([SWS_CM_00211]).
• Uitvoeringscontext: Voor asynchrone uitvoeringen staat een template-overbelasting met een extra executor-object ExecutorT&& executor gereed ([SWS_CM_00100]).

Foutafhandeling en randvoorwaarden:

• Uitzonderingsveiligheid: De functie geldt als uitzonderingsveilig (exception safe) ([SWS_CM_00099]).
• Overtredingen: Indien het meegegeven callable niet bestaat of null is, is er sprake van een InvalidHandlerViolation ([SWS_CM_00099]).
• Interactie: Equivalente interfaces voor de registratie van een TransportFaultConditionHandler bestaan ook voor triggers ([SWS_CM_00106]), field-notifiers ([SWS_CM_00109]) en skeleton-methoden ([SWS_CM_00093]).

De template-functie SetTransportFaultConditionHandler registreert bij een proxy-event een toepassingsspecifieke handler van het type ara::com::e2e::TransportFaultConditionHandler samen met een door de gebruiker gedefinieerde executor ([SWS_CM_00100]). Deze vormt de execution-context-overbelasting van de basisfunctionaliteit met minder parameters ([SWS_CM_00099]).

Gebruik en parameters: De methode wordt aangeroepen op instanties van <SI-Namespace>::proxy::events::<Event> en geeft geen waarde terug (void) ([SWS_CM_00100]). Ze neemt de aan te roepen handler (handler) in ontvangst en accepteert een executor-object (executor als universele referentie ExecutorT&&), in de context waarvan elke asynchrone uitvoering van de handler in gang wordt gezet ([SWS_CM_00100]). De functiesignatuur is gedeclareerd met noexcept ([SWS_CM_00100]).

Foutafhandeling: De operatie is gespecificeerd als exception safe ([SWS_CM_00100]). Indien een ongeldig of niet-bestaand callable wordt doorgegeven (null), is er sprake van een overtreding in de vorm van InvalidHandlerViolation ([SWS_CM_00100]). Via de geregistreerde handler worden gedetecteerde transportfouten gemeld, zoals bijvoorbeeld TransportFaultCondition::kSampleRejected bij het verwerpen van binnenkomende datasamples door de onderliggende transportentiteit ([SWS_CM_00211]).

Interactie: Terwijl [SWS_CM_00099] de registratie zonder expliciete executor uitvoert, maakt deze overbelasting de uitvoering in de gewenste thread- respectievelijk taakcontext mogelijk ([SWS_CM_00100]). Analoge overbelastingen met executor zijn beschikbaar voor skeleton-methoden ([SWS_CM_00094]) en skeleton-velden ([SWS_CM_00097]), evenals aan proxy-zijde voor triggers ([SWS_CM_00107]) en veldnotifiers ([SWS_CM_00110]).

Gebruik

De methode Subscribe registreert het proxy-element voor de ontvangst van service-events conform [SWS_CM_00141]. De aanroep is van asynchrone aard: de terugkeer van de functie bevestigt enkel dat Communication Management het registratieverzoek heeft geaccepteerd (AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 “Monitoring Event Subscription”). Met de verplichte parameter maxSampleCount deelt de applicatie bindend mee hoeveel event-samples zij maximaal gelijktijdig zal vasthouden, en initialiseert daardoor de lokale ontvangstbuffer (AUTOSAR_AP_EXP_ARAComAPI p. 40).

Foutafhandeling en randvoorwaarden

Als het event bij de aanroep reeds in de toestand kSubscribed of kSubscriptionPending is en de meegegeven waarde maxSampleCount overeenkomt met het actieve abonnement, keert de methode zonder actie succesvol terug ([SWS_CM_00141]). Wijkt de cache-grootte bij een hernieuwd abonnement daarentegen af, dan mislukt de aanroep en levert deze in ara::core::Result de foutcode ComErrc::kMaxSampleCountNotRealizable op ([SWS_CM_00141]). Bij ontbrekende toegangsrechten wordt de aanroep geweigerd (InsufficientPermissionsViolation conform [SWS_CM_00141]). De signatuur is gedeclareerd als noexcept en geldt als uitzonderingsveilig.

Samenspel

De gereserveerde cache-capaciteit begrenst de latere gegevensontvangst via GetNewSamples ([SWS_CM_00701]); houdt de applicatie meer smart pointers vast dan gespecificeerd, dan wordt de fout ComErrc::kMaxSamplesExceeded geactiveerd ([SWS_CM_10432]). Terwijl field-events identiek via maxSampleCount worden geabonneerd ([SWS_CM_11601]), vereisen zuivere trigger-events geen specificatie van de buffergrootte ([SWS_CM_00723]).

Gebruik

De functie UnsetReceiveHandler maakt deel uit van de event-wrapper in de scope <SI-Namespace>::proxy::events::<Event> en wordt ingesloten via het headerbestand #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00183]). Ze accepteert geen overdrachtsparameters en heeft geen retourwaarde (void). Door de aanroep wordt een eerder met SetReceiveHandler geregistreerde toepassingsspecifieke ontvangst-handler voor een service-event weer verwijderd (EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”). Daardoor kan de ontvangende toepassing te allen tijde wisselen tussen een gebeurtenisgestuurde ontvangst („event-driven”) en een actieve opvraagmodus („polling style”) door middel van GetNewSamples() (EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”).

Foutafhandeling

De methode is gedeclareerd met noexcept en bezit de eigenschap exception safe ([SWS_CM_00183]). Ze werpt tijdens runtime geen excepties op en meldt geen specifieke foutcodes terug.

Gelijktijdigheid en binding

Terwijl voor de geregistreerde callback-handler geldt dat deze niet re-entrant hoeft te zijn, omdat Communication Management aanroepen serialiseert (EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”), deactiveert UnsetReceiveHandler de event-trigger voor de ontvangst van verdere notificaties ([SWS_CM_00183]). In de context van de DDS-binding wordt de methode UnsetReceiveHandler() conform [SWS_CM_11141] overeenkomstig de specificatie [SWS_CM_11026] afgebeeld op de bijbehorende DataReader.

Samenspel

De functie vormt het directe tegenstuk van de registratie via SetReceiveHandler ([SWS_CM_11140], EXP ARAComAPI §5.3.1 “Proxy Class API’s”). Verwante functies zijn te vinden in andere proxy-interfaces:

• Voor velden bestaat een identiek benoemde functie UnsetReceiveHandler in de scope <SI-Namespace>::proxy::fields::<Field>, die eveneens gedefinieerd is als noexcept en exception safe ([SWS_CM_11606]).
• Voor triggers staat UnsetReceiveHandler in de scope <SI-Namespace>::proxy::triggers::<Trigger> ter beschikking, maar is in afwijking hiervan gedeclareerd als not exception safe ([SWS_CM_11614]).

Gebruik

De lidfunctie UnsetSubscriptionStateChangeHandler dient voor het resetten en deregistreren van een eerder ingestelde callback-handler voor wijzigingen van de abonnementsstatus (ara::com::SubscriptionState) aan proxyzijde ([SWS_CM_00334], EXP ARAComAPI §1.0). De functie maakt deel uit van de event-interface en bevindt zich in de applicatiespecifieke namespace onder proxy::events ([SWS_CM_00334], SWS CommunicationManagement §8.3.2.2.4.5 “UnsetSubscriptionStateChangeHandler”). Voor gebruik wordt het gegenereerde proxy-headerbestand <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h ingevoegd ([SWS_CM_00334]). De aanroep verloopt synchroon, accepteert geen parameters en levert geen retourwaarde op ([SWS_CM_00334]).

Foutafhandeling

Volgens de specificatie is de functie gedeclareerd met de identifier noexcept en geclassificeerd als uitzonderingsveilig („exception safe”) ([SWS_CM_00334]). Deze werpt bij fouten geen C++-excepties op en meldt geen foutcodes terug ([SWS_CM_00334]).

Gelijktijdigheid en wisselwerking

De functie staat in verband met andere proxy-API's voor servicezoekopdrachten en event-beheer zoals Subscribe(), Unsubscribe(), GetSubscriptionState() en SetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 “Proxy Class API’s”). Als interpretatie mogen na de aanroep geen verdere meldingen via de gederegistreerde handler worden geactiveerd. Vraag Q-6173c01e6ca93876 (open) Symmetrische tegenhangers voor het resetten van handlers voor statuswijzigingen zijn in de specificatie gedefinieerd voor proxy-fields ([SWS_CM_11609], SWS CommunicationManagement §8.3.3.2.4.5 “UnsetSubscriptionStateChangeHandler”) en triggers ([SWS_CM_01108]), evenals aan service-providerzijde (skeleton) voor events ([SWS_CM_12010]) en triggers ([SWS_CM_01112]).

Gebruik

De functie UnsetTransportFaultConditionHandler in de namespace <SI-Namespace>::proxy::events::<Event> dient ertoe een eerder geregistreerde ara::com::e2e::TransportFaultConditionHandler voor een concreet proxy-event te deregistreren [SWS_CM_00105]. De functiedeclaratie wordt ter beschikking gesteld via het headerbestand <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.1.3 “UnsetTransportFaultConditionHandler”. De aanroep accepteert geen parameters en levert geen retourwaarde op (void).

Foutafhandeling en uitzonderingsveiligheid

De functie is gedeclareerd met de identifier noexcept en gespecificeerd als uitzonderingsveilig (exception safe) [SWS_CM_00105]. Noch specifieke foutcodes, noch meldingen aan fout- of diagnosesubsystemen zijn in de standaard gedefinieerd.

Verloop en randvoorwaarden

De aanroep zal vermoedelijk synchroon worden uitgevoerd om de E2E-foutafhandeling op event-niveau onmiddellijk uit te schakelen, bijvoorbeeld wanneer het event niet meer gemonitord hoeft te worden of voordat het bijbehorende proxy-object wordt vrijgegeven (interpretatie). Vraag Q-ff00695fff5407fe (open) Na uitvoering verwerkt de communicatielaag geen E2E-transportfouten meer via de eerder ingestelde callback van dit event.

Samenspel

Het deregistreren van handlers voor transportfouten volgt een uniform patroon over verschillende communicatie-elementen heen:

• Voor notifiers van fields op proxy-niveau dient de functie [SWS_CM_00126].
• Voor proxy-triggers wordt de handler via [SWS_CM_00108] afgemeld.
• Aan skeleton-zijde staan analoge interfaces voor alle methoden van een service-interface ([SWS_CM_00095]) en voor getters/setters van fields ([SWS_CM_00098]) ter beschikking.

Gebruik

De methode Unsubscribe() beëindigt het actieve abonnement op een service-event aan proxyzijde ([SWS_CM_00151], EXP_ARAComAPI §5.5). Deze is gedefinieerd binnen de scope <SI-Namespace>::proxy::events::<Event> en wordt via het headerbestand #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ingesloten ([SWS_CM_00151]). De functie accepteert geen overdrachtsparameters en levert geen retourwaarde op (void). Was het event op het tijdstip van de aanroep niet geabonneerd, dan keert de methode terug zonder een actie uit te voeren ([SWS_CM_00151]).

Foutafhandeling en exception-veiligheid

De operatie is gedeclareerd met de identifier noexcept en gespecificeerd als exceptieveilig ([SWS_CM_00151]). Als schending (violation) is een DanglingSamplesViolation voorzien indien voorafgaand aan de methodeaanroep de preconditie volgens [SWS_CM_00085] is geschonden ([SWS_CM_00151]).

Samenspel en verwante interfaces

Op netwerkniveau initieert het beëindigen van het abonnement het verzenden van SOME/IP-berichten van het type StopSubscribeEventgroup ([SWS_CM_10378], SWS_CommunicationManagement §7.2.1.2.6). Binnen de proxy-interfaces behoort Unsubscribe() tot de groep methoden voor abonnementsbeheer (EXP_ARAComAPI §5.3.1). Een identieke afmeldingssemantiek is eveneens beschikbaar voor service-triggers ([SWS_CM_00810], EXP_ARAComAPI §4) en voor field-notificaties ([SWS_CM_11602]).