klasse <SI-Namespace>::proxy::triggers::<Trigger>

Gebruik

De functie SetReceiveHandler wordt aangeroepen in de scope van de trigger-klasse van een service-proxy (<SI-Namespace>::proxy::triggers::<Trigger>) en opgenomen via de header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h [SWS_CM_00250]. Triggers vormen naast events, methods en fields een van de vier communicatiemechanismen in ara::com EXP_ARAComAPI §4.2 “Means of Communication”.

De parameter handler van het type ara::com::TriggerReceiveHandler accepteert een aanroepbaar object dat door Communication Management wordt aangeroepen bij ontvangst van een trigger. De handler zelf heeft geen parameters; om de actuele tellersstand van de trigger op te vragen, moet binnen de callback-functie de methode GetNewTriggers van de specifieke trigger-klasse worden aangeroepen [SWS_CM_00250].

Foutafhandeling en exception-veiligheid

De registratie levert geen retourwaarde op (void) en is gedefinieerd als noexcept en exception safe [SWS_CM_00250]. Een overtreding van de aanroepconventie in de vorm van een InvalidHandlerViolation treedt op wanneer het overgedragen callable niet bestaat of null is [SWS_CM_00250].

Interactie en varianten

Voor scenario's waarin de trigger-handler in een gedefinieerde uitvoeringscontext moet worden afgehandeld, bestaat de template-overload met ExecutorT [SWS_CM_00352]. Vergelijkbare registratiemethoden voor callbacks zijn op proxy-niveau ook beschikbaar voor events ([SWS_CM_00181], [SWS_CM_11356]) en fields ([SWS_CM_11605], [SWS_CM_11611]) EXP_ARAComAPI §5.3.1 “Proxy Class API’s”.

Gebruik

De templatefunctie SetSubscriptionStateChangeHandler binnen het geldigheidsbereik <SI-Namespace>::proxy::triggers::<Trigger> registreert een callback voor meldingen over wijzigingen van de abonnementsstatus ([SWS_CM_01106]). Deze wordt via het headerbestand <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h gedeclareerd en accepteert twee parameters:

• handler: De aanroepbare eenheid van het type ara::com::SubscriptionStateChangeHandler die bij een statuswijziging moet worden uitgevoerd ([SWS_CM_01107]).
• executor: Een uitvoeringscontext van het type ExecutorT ([SWS_CM_11360]) waarin de uitvoering van de handler moet plaatsvinden.

De registratie zelf gedraagt zich synchroon en heeft geen retourwaarde (void). De geregistreerde callback wordt bij statuswijzigingen in de opgegeven uitvoeringscontext uitgevoerd.

Foutafhandeling en exception-veiligheid

De methode is gedeclareerd als noexcept en gespecificeerd als exception safe ([SWS_CM_01106]). Wanneer de meegegeven callable-instantie niet bestaat of null is, is er sprake van een InvalidHandlerViolation ([SWS_CM_01106]). Aangezien er geen excepties worden geworpen, leidt een ongeldige handler vermoedelijk tot een platformspecifiek foutpad (interpretatie). Vraag Q-cbb90bfbfa10338d (open)

Gelijktijdigheid en wisselwerking

Door het meegeven van de executor ([SWS_CM_11360]) regelt de applicatie de uitvoeringscontext voor status-callbacks zelf. Dit zal vermoedelijk voorkomen dat langlopende handler-aanroepen de interne gebeurtenisverwerking van het communicatiebeheer blokkeren (interpretatie). Vraag (open) De functie breidt de contextloze variant [SWS_CM_01107] uit en vormt de trigger-tegenhanger van de op executor gebaseerde interfaces voor proxy-events ([SWS_CM_11354]), proxy-fields ([SWS_CM_11608]) en skeleton-triggers ([SWS_CM_11111]).

Met de functie [SWS_CM_01107] wordt in het proxy-bereik van een trigger (<SI-Namespace>::proxy::triggers::<Trigger>) een callback-handler geregistreerd, die door Communication Management bij elke wijziging van de abonnementsstatus (ara::com::SubscriptionState) wordt aangeroepen. De functie heeft geen retourwaarde en is als uitzonderingsveilig (noexcept) gespecificeerd.

Aangezien het abonneren principieel als een asynchroon proces moet worden behandeld, mag de toepassing pas van een succesvol abonnement uitgaan wanneer de via [SWS_CM_01107] geregistreerde handler of de opvraagfunctie GetSubscriptionState() de status kSubscribed meldt [SWS_CM_12006]. Bij tijdsvertragingen of wanneer de server als gevolg van een herstart respectievelijk netwerkprobleem tijdelijk niet beschikbaar is, activeert Communication Management de handler met de status kSubscriptionPending [SWS_CM_00313].

Voor de foutafhandeling en integratie gelden de volgende randvoorwaarden:

• Foutafhandeling: Het doorgeven van een niet-bestaand of leeg callable (null) is niet toegestaan en leidt tot een InvalidHandlerViolation [SWS_CM_01107].
• Uitvoeringscontext: Indien de handler niet in de standaardcontext, maar binnen een specifieke uitvoeringscontext moet worden uitgevoerd, staat de template-overload met ExecutorT&& ter beschikking [SWS_CM_01106].
• Interactie: Voor service-events bestaat de analoge interface [SWS_CM_00333] in het kader van de algemene proxy-klasse-API's ARAComAPI §5.3.1 “Proxy Class API’s”.

De functie SetTransportFaultConditionHandler dient bij een instantie van proxy::triggers::<Trigger> voor de registratie van een callback-functie van het type ara::com::e2e::TransportFaultConditionHandler ([SWS_CM_00106]). Ze neemt de parameter handler in ontvangst, heeft geen retourwaarde en is gespecificeerd als noexcept en exception safe ([SWS_CM_00106]).

Via de geregistreerde handler signaleert de communicatielaag vastgestelde fouten van de transmissielaag. In de DDS-network-binding meldt de handler gebeurtenissen van de onderliggende DataReader-entiteit als TransportFaultCondition ([SWS_CM_00212]):

• TransportFaultCondition::kSampleRejected bij verworpen samples (bijvoorbeeld door geheugentekort of datacorruptie),
• TransportFaultCondition::kDeadlineMissed bij geschonden ontvangstdeadlines (REQUESTED_DEADLINE_MISSED),
• TransportFaultCondition::kSampleLost bij verlies van gedetecteerde datasamples ([SWS_CM_00212]).

Indien in plaats van een geldig callable een niet-bestaande of lege handler wordt meegegeven, meldt de runtime-omgeving een InvalidHandlerViolation ([SWS_CM_00106]). Omdat de functiesignatuur als noexcept is gedeclareerd, leidt deze overtreding vermoedelijk tot platformspecifieke foutafhandeling in plaats van een C++-exception. Vraag Q-ebaf44b8f7b198e8 (open)

De registratie vindt synchroon plaats in de context van de aanroeper; de uitvoering van de handler wordt bij deze overbelasting niet gedelegeerd naar een specifieke dispatcher. Indien de callback in een gedefinieerde uitvoeringscontext moet draaien, staat de overbelaste template-variant met aanvullende ExecutorT&& ter beschikking ([SWS_CM_00107]). De koppeling vindt vermoedelijk typisch plaats vóór de daadwerkelijke trigger-verwerking, om fouten vanaf het begin te registreren. Vraag (open)

Overeenkomstige registratiemogelijkheden voor TransportFaultConditionHandler bestaan op gelijke wijze voor proxy-events ([SWS_CM_00099]), proxy-fields ([SWS_CM_00109]) en skeleton-methoden ([SWS_CM_00093]) en skeleton-fields ([SWS_CM_00096]).

De functie [SWS_CM_00107] dient voor de registratie van een callback-routine voor transportfouten van een proxy-trigger in de namespace <SI-Namespace>::proxy::triggers::<Trigger>. Als overload met uitvoeringscontext accepteert deze naast de handler van het type ara::com::e2e::TransportFaultConditionHandler een executor-object executor, waarin getriggerde asynchrone berekeningen worden uitgevoerd.

Voor het gebruik en de foutafhandeling gelden de volgende bepalingen:

• Parameters en retourwaarde: De parameter handler draagt het in te stellen callable over, terwijl executor de uitvoeringscontext voor asynchrone taken definieert [SWS_CM_00107]. De functie retourneert geen retourwaarde en is gedeclareerd als noexcept (exceptieveiligheid: exception safe).
• Foutgevallen en overtredingen: Als een niet-bestaande of ongeldige handler wordt doorgegeven (null), meldt de runtime een InvalidHandlerViolation [SWS_CM_00107].
• Gemelde fouttoestanden: De geregistreerde handler ontvangt gedetecteerde transportfouten conform [SWS_CM_00212]. Daartoe behoren TransportFaultCondition::kSampleRejected (bijvoorbeeld bij datacorruptie of gebrek aan resources), TransportFaultCondition::kDeadlineMissed (bij overschreden termijnen) evenals TransportFaultCondition::kSampleLost (bij verloren gegane samples).

In vergelijking met de basisfunctie zonder executor [SWS_CM_00106] maakt deze variant de gerichte besturing mogelijk van de gelijktijdigheidscontext voor de foutverwerking van de trigger. Analoge overloads met uitvoeringscontext bestaan in Communication Management voor proxy-events [SWS_CM_00100], proxy-fields [SWS_CM_00110] evenals op skeleton-niveau voor methoden [SWS_CM_00094] en fields [SWS_CM_00097].

De methode Subscribe dient voor het clientzijdig abonneren op een service-trigger via een proxy-instantie in de namespace <SI-Namespace>::proxy::triggers::<Trigger> [SWS_CM_00723]. Vóór gebruik moet de service-instantie serverzijdig via OfferService() beschikbaar zijn gesteld en door de client via Service Discovery-mechanismen zijn gevonden AUTOSAR_AP_EXP_ARAComAPI §4.2 “Means of Communication”.

In vergelijking met event- ([SWS_CM_00141]) en field-subscripties ([SWS_CM_11601]) vertoont Subscribe voor triggers specifieke eigenschappen:

• Parameters en cache: De functie accepteert geen parameters (void Subscribe() noexcept) [SWS_CM_00723]. Aangezien triggers louter notificaties zonder datasamples verzenden, vervalt de bij events gebruikelijke reservering van een lokale sample-cache via maxSampleCount [SWS_CM_00141].
• Retourwaarde: Er wordt geen ara::core::Result geretourneerd, maar void [SWS_CM_00723].
• Asynchroniciteit: De aanroep brengt het abonnement op gang; de daadwerkelijke totstandbrenging van de verbinding met de service-instantie vindt daarbij vermoedelijk analoog aan event-subscripties asynchroon plaats in het communicatiebeheer AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 “Monitoring Event Subscription”. Vraag Q-92ae3f442b45f3cc (open)

Voor de levenscyclus en de foutafhandeling gelden de volgende voorwaarden:

• Toestandscontrole en idempotentie: Bevindt de trigger zich op het moment van aanroepen al in de toestand kSubscribed of kSubscriptionPending, dan keert de methode direct zonder verdere actie terug [SWS_CM_00723].
• Uitzonderingsveiligheid: De functie is gespecificeerd als noexcept en exception safe [SWS_CM_00723].
• Toegangscontrole: Bij ontoereikende rechten weigert de grant-enforcement de uitvoering met een InsufficientPermissionsViolation [SWS_CM_00723].

Gebruik

De synchrone functie UnsetReceiveHandler in de namespace <SI-Namespace>::proxy::triggers::<Trigger> dient voor de deactivering van de eerder geregistreerde ontvangsthandler voor een service-trigger aan proxyzijde [SWS_CM_11614]. De functie vereist het includeren van het headerbestand #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h", accepteert geen invoerparameters en heeft geen retourwaarde.

Door de aanroep wordt de applicatiespecifieke callback gederegistreerd. Hierdoor kan de applicatie flexibel wisselen tussen een event-gestuurde ontvangst en een polling-gebaseerd model (AUTOSAR_AP_EXP_ARAComAPI p. 46, AUTOSAR_AP_SWS_CommunicationManagement §7.5.18.1).

Foutafhandeling en uitzonderingsveiligheid

In tegenstelling tot de analoge functies voor service-events [SWS_CM_00183] en service-fields [SWS_CM_11606], die expliciet gespecificeerd zijn als noexcept en uitzonderingsveilig, is UnsetReceiveHandler voor triggers gedeclareerd als niet uitzonderingsveilig (not exception safe) [SWS_CM_11614]. Interpretatie: aanroepers moeten er rekening mee houden dat bij interne fouten in de communicatie-infrastructuur vermoedelijk exceptions worden geworpen, hoewel specifieke exception-typen of foutcodes in de standaard niet worden vermeld. Vraag Q-92e16243a7ddee35 (open)

Wisselwerking en bindings

De methode maakt deel uit van de trigger-klassen in de proxy-namespace (AUTOSAR_AP_EXP_ARAComAPI §5.3.1). Bij gebruik van een DDS-binding wordt de methode-aanroep conform [SWS_CM_11141] via de toegewezen DataReader afgebeeld volgens de in [SWS_CM_11026] vastgelegde voorschriften.

De functie UnsetSubscriptionStateChangeHandler dient aan clientzijde ertoe een eerder geregistreerde callback voor toestandswijzigingen van het abonnement (ara::com::SubscriptionState) van een trigger te verwijderen [SWS_CM_01108]. Deze is gedeclareerd binnen het geldigheidsbereik <SI-Namespace>::proxy::triggers::<Trigger> en moet via de header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" worden ingesloten [SWS_CM_01108].

Gebruik en aanroepcontext

De methode heeft de signatuur void UnsetSubscriptionStateChangeHandler () noexcept;, accepteert geen overdrachtsparameters en levert geen retourwaarde op [SWS_CM_01108]. Deze wordt synchroon aangeroepen op de instantie van de desbetreffende trigger van een proxy-klasse om notificaties bij wijzigingen van de abonnementsstatus weer af te melden AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”. Interpretatie: Na uitvoering van de aanroep zullen vermoedelijk geen verdere statuswijzigingen meer aan de eerdere handler worden afgeleverd. Vraag Q-d08dc975aacba85c (open)

Foutafhandeling en gelijktijdigheid

De interface is gedeclareerd als noexcept en expliciet gespecificeerd als uitzonderingsveilig (exception safe) [SWS_CM_01108]. Het mislukken van de aanroep of het werpen van excepties is daarom uitgesloten, en er bestaan geen foutretourwaarden.

Samenspel

De functie past in het uniforme schema van de proxy-interfaces. Analoge deregistratiemethoden staan in de proxy-context ter beschikking voor events conform [SWS_CM_00334] AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.4.5 “UnsetSubscriptionStateChangeHandler” alsook voor fields conform [SWS_CM_11609] AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 “UnsetSubscriptionStateChangeHandler”. Aan server- respectievelijk skeleton-zijde bestaan overeenkomstige tegenhangers voor triggers [SWS_CM_01112] en events [SWS_CM_12010].

De functie UnsetTransportFaultConditionHandler dient ertoe een eerder geregistreerde ara::com::e2e::TransportFaultConditionHandler voor een specifieke proxy-trigger weer af te melden ([SWS_CM_00108], gedocumenteerd in AUTOSAR_AP_SWS_CommunicationManagement §8.3.7.1.1.3 “UnsetTransportFaultConditionHandler”). Deze bevindt zich in de namespace <SI-Namespace>::proxy::triggers::<Trigger> en moet worden ingesloten via het headerbestand #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00108]).

De signatuur luidt void UnsetTransportFaultConditionHandler() noexcept;. De aanroep accepteert geen parameters en geeft geen retourwaarde terug ([SWS_CM_00108]). Door de noexcept-declaratie en de classificatie als exception safe werpt de functie bij reguliere werking geen excepties ([SWS_CM_00108]). Specifieke foutcodes, foutkanalen of terugvalwaarden zijn in de specificatie niet voorzien.

Wat betreft het verloop heft de functie de koppeling met de foutafhandelingsroutine synchroon op; dientengevolge zullen er na succesvolle uitvoering vermoedelijk geen verdere meldingen over E2E-transportfouten voor de desbetreffende trigger aan de eerdere handler worden afgeleverd (interpretatie). Vraag Q-ae8477bc6530e352 (open)

Binnen het totale systeem vormt het element de tegenhanger van analoge afmeldfuncties voor andere communicatiepatronen in AUTOSAR_AP_SWS_CommunicationManagement §8.3/8.4:

• Proxy-events: UnsetTransportFaultConditionHandler op event-niveau ([SWS_CM_00105]).
• Proxy-fields: afmelding voor field-notifiers ([SWS_CM_00126]).
• Skeleton-niveau: afmelding voor field-get/set ([SWS_CM_00098]) en voor alle methoden van een skeleton ([SWS_CM_00095]).