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

Gebruik

De methode Get dient in de proxy-scope <SI-Namespace>::proxy::fields::<Field> voor het asynchroon ophalen van de actuele veldwaarde ([SWS_CM_00112]; zie ook AUTOSAR_AP_EXP_ARAComAPI §6 “FieldGet”). De functie wordt beschikbaar gesteld via de proxy-header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h en bestaat alleen wanneer voor het veld Field.hasGetter == TRUE gemodelleerd is ([SWS_CM_00112]). Ze accepteert geen parameters en levert een ara::core::Future<FieldType> terug, die na succesvolle overdracht de actuele waarde bevat ([SWS_CM_00112]).

Foutafhandeling en randvoorwaarden

De interface is gedefinieerd als noexcept en exceptieveilig ([SWS_CM_00112]). Mislukt de operatie, dan bevat de geretourneerde ara::core::Future een foutcode met rollback-semantiek ([SWS_CM_00112]):

• ComErrc::kCommunicationFailure: De netwerkbinding meldt een herstelbare communicatiefout of het mislukken van een beveiligde communicatie ([SWS_CM_00112]).
• ComErrc::kMinimumSendIntervalViolationError: Een verzendverzoek vond sneller plaats dan het voor het element geconfigureerde minimale verzendinterval (minimumSendInterval) toestaat ([SWS_CM_00112]).
• InsufficientPermissionsViolation: De uitvoering wordt afgewezen door Grant Enforcement ([SWS_CM_00112]).

Toepassingsfouten (Application Errors) bestaan niet voor de getter ([SWS_CM_00113]).

Samenspel

Aan de skeleton-zijde vereist de verwerking van het getter-verzoek een callback die via RegisterGetHandler wordt geregistreerd ([SWS_CM_00114]). Elke aanroep van Get() voert een end-to-end-controle (E2E) uit; de daaruit resulterende toestandstatus kan aan de proxy-zijde synchroon via GetE2EStateMachineStateGetter worden opgevraagd ([SWS_CM_00145]).

Gebruik en aanroepcontext

De functie Set wordt beschikbaar gesteld in de namespace <SI-Namespace>::proxy::fields::<Field> en is uitsluitend beschikbaar wanneer voor het veld Field.hasSetter == TRUE geconfigureerd is [SWS_CM_00113]. Vóór gebruik moet de service-instantie aan serverzijde zijn aangeboden (OfferService()) en aan clientzijde zijn gevonden en verbonden ARAComAPI §4.2 “Means of Communication”. De aanroep geschiedt asynchroon: deze geeft de nieuwe veldwaarde door via de parameter value en retourneert een ara::core::Future<FieldType> [SWS_CM_00113]. De methode is gespecificeerd als noexcept en geldt als exceptieveilig [SWS_CM_00113].

Foutafhandeling

Mislukt de overdracht, dan wordt de desbetreffende fout via de geretourneerde ara::core::Future beschikbaar gesteld [SWS_CM_00113]:

• ComErrc::kCommunicationFailure: Meldt een herstelbare communicatiefout of een storing in de veilige overdracht; in het geval van een time-out kan er sprake zijn van een onbepaalde toestand aan serverzijde zonder rollback-semantiek [SWS_CM_00113].
• ComErrc::kMinimumSendIntervalViolationError: Treedt op wanneer een verzendverzoek sneller werd verzonden dan het geconfigureerde minimale verzendinterval (minimumSendInterval) (eveneens zonder rollback-semantiek) [SWS_CM_00113].
• Ontbrekende toegangsrechten leiden tot een weigering door Grant Enforcement (InsufficientPermissionsViolation) [SWS_CM_00113].
• Toepassingsfouten worden niet getransporteerd via excepties, maar doordat in het geval van succes van de future een waarde wordt geretourneerd die afwijkt van de aanvraagparameter [SWS_CM_00113].

Interactie en gelijktijdigheid

Aan serverzijde correspondeert de aanroep met een callback op de skeleton-instantie, die vooraf door middel van RegisterSetHandler moet worden geregistreerd [SWS_CM_00116] ARAComAPI §4.2 “Means of Communication”. Voor het bewaken van de E2E-overdrachtsveiligheid aan clientzijde kan de status van de E2E-toestandsmachine van de laatste Set()-aanroep via GetE2EStateMachineStateSetter() worden opgevraagd [SWS_CM_00146].

Gebruik en aanroepcontext

De functie SetReceiveHandler wordt aan proxyzijde in de namespace <SI-Namespace>::proxy::fields::<Field> via het headerbestand <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h beschikbaar gesteld ([SWS_CM_11605]). Deze registreert aan de clientzijde een callback voor notificaties bij waardewijzigingen van een veld ([SWS_CM_11605]). Dit mechanisme volgt de notificatieprocedure van events, waardoor Communication Management de client bij updates informeert (EXP_ARAComAPI §4.2 “Means of Communication”).

Als parameter wordt een ara::com::FieldReceiveHandler overgedragen, wat een parameterloze functie representeert ([SWS_CM_11605]). De functie levert geen retourwaarde (void) op en is gespecificeerd als exceptieveilig (noexcept) ([SWS_CM_11605]).

Foutafhandeling en gelijktijdigheid

Indien het overgedragen callable-object niet bestaat of null is, meldt de functie de overtreding InvalidHandlerViolation ([SWS_CM_11605]). Wanneer de uitvoering van de handler in een gedefinieerde uitvoeringscontext moet plaatsvinden, staat de template-variant met ExecutorT ter beschikking ([SWS_CM_11611]).

Samenspel

Het gedrag komt overeen met de handler-registraties voor events ([SWS_CM_00181]) en triggers ([SWS_CM_00250]). Een opheffing van de registratie zal, in lijn met het interfacepatroon van de proxy-klasse, vermoedelijk via UnsetReceiveHandler() plaatsvinden (EXP_ARAComAPI §5.3.1 “Proxy Class API’s”). Vraag Q-74cd83b99aadec16 (open)

Gebruik en aanroepcontext

De template-functie SetReceiveHandler maakt deel uit van de proxy-klasse class <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11611]; header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h"). Deze dient ertoe om aan de clientzijde een ontvangsthandler voor notificaties bij waardewijzigingen van een veld te registreren (AUTOSAR_AP_EXP_ARAComAPI §4.2 “Means of Communication”, [SWS_CM_11605]). Via de parameters worden een aanroepbaar object handler van het type ara::com::FieldReceiveHandler evenals een uitvoeringscontext executor als universele referentie ExecutorT&& overgedragen ([SWS_CM_11611]). De functie heeft geen retourwaarde (void).

Foutafhandeling en exception-veiligheid

De methode is gedeclareerd als noexcept en gespecificeerd als exceptieveilig (exception safe) ([SWS_CM_11611]). Wanneer het overgedragen callable handler niet bestaat of null is, is er sprake van een InvalidHandlerViolation ([SWS_CM_11611]). Aanroepers moeten er daarom voor zorgen dat er voorafgaand aan de aanroep een valide functie of functie-object ter beschikking wordt gesteld.

Gelijktijdigheid en wisselwerking

In tegenstelling tot de standaardregistratie zonder executor ([SWS_CM_11605]) wordt de callback bij binnenkomst van een veld-notificatie afgehandeld in de door executor beschikbaar gestelde uitvoeringscontext ([SWS_CM_11611]). Interpretatie: Dit zal vermoedelijk een ontkoppeling teweegbrengen, zodat de applicatiespecifieke gegevensverwerking niet in de uitvoeringscontexten van interne middleware-threads plaatsvindt. Vraag Q-cbe1af19bea15a88 (open) De methode behoort tot de proxy-klasse-API's (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”) en volgt hetzelfde patroon als de executor-varianten voor events ([SWS_CM_11356] gebaseerd op [SWS_CM_00181]) en triggers ([SWS_CM_00352] gebaseerd op [SWS_CM_00250]).

De functie SetSubscriptionStateChangeHandler registreert op een proxy-veld (scope <SI-Namespace>::proxy::fields::<Field>) een door de gebruiker gedefinieerde callback, die door Communication Management wordt aangeroepen zodra de abonnementsstatus (ara::com::SubscriptionState) van het veld verandert ([SWS_CM_11607], [SWS_CM_00333]). De aanroep vindt synchroon plaats en levert geen retourwaarde op ([SWS_CM_11607]). Deze behoort tot de centrale proxy-interfaces voor het beheer van event- en veldabonnementen (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”).

Wat betreft de foutafhandeling is de registratiefunctie gespecificeerd als exception safe en gedeclareerd met noexcept ([SWS_CM_11607]). Indien het meegegeven callable-object handler niet bestaat of null is, is er sprake van een specificatieschending in de vorm van een InvalidHandlerViolation ([SWS_CM_11607]).

In samenhang met de verbindingsopbouw dient in acht te worden genomen dat Subscribe() in beginsel als een asynchrone operatie moet worden beschouwd ([SWS_CM_12006]). Toepassingen mogen daarom zelfs na foutloze terugkeer van Subscribe() pas dan uitgaan van een succesvol abonnement wanneer de geregistreerde handler de status kSubscribed heeft gesignaleerd ([SWS_CM_12006]). Bovendien roept Communication Management de handler aan met kSubscriptionPending wanneer de feitelijke binding niet direct kan worden voltooid of wanneer de serverinstantie bijvoorbeeld door een herstart of netwerkfout uitvalt ([SWS_CM_00313]). Als de handler in een specifieke uitvoeringscontext moet worden uitgevoerd, staat hiervoor de overladen template-variant met een ExecutorT gereed ([SWS_CM_11608]).

De template-functie SetSubscriptionStateChangeHandler in de namespace <SI-Namespace>::proxy::fields::<Field> dient voor de registratie van een callback-functie voor het bewaken van toestandsveranderingen van het abonnement van een veld ([SWS_CM_11608]). Deze breidt het basisgedrag uit [SWS_CM_11607] ermee uit dat de geregistreerde handler in een expliciet overgedragen uitvoeringscontext (executor) wordt uitgevoerd ([SWS_CM_11608]).

De methode accepteert twee parameters ([SWS_CM_11608]):

• handler: De aan te roepen callback van het type ara::com::SubscriptionStateChangeHandler ([SWS_CM_11354]), die wordt getriggerd zodra de ara::com::SubscriptionState verandert ([SWS_CM_00333]).
• executor: Een forwarding reference van het type ExecutorT&& ([SWS_CM_11360]), die de context voor de uitvoering van de handler beschikbaar stelt ([SWS_CM_11608]).

De functie retourneert geen retourwaarde (void) en is gedeclareerd als noexcept ([SWS_CM_11608]). Deze is gespecificeerd als exception safe ([SWS_CM_11608]). Als overtreding is InvalidHandlerViolation gedefinieerd voor het geval dat het overgedragen callable niet bestaat of null is ([SWS_CM_11608]).

Interpretatie: Door de overdracht van de executor zal de uitvoering van de handler vermoedelijk vanuit de interne context van Communication Management worden verplaatst naar de thread- of taakcontext van de applicatie. Vraag Q-647f618545799c4e (open) In het samenspel van de proxy-API's sluit de aanroep aan bij methoden zoals Subscribe(), Unsubscribe() en UnsetSubscriptionStateChangeHandler() (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”). Analoge overloaded varianten met uitvoeringscontext bestaan voor proxy-events ([SWS_CM_11354]) evenals proxy-triggers ([SWS_CM_01106]).

Gebruik en aanroepcontext

De lidfunctie SetTransportFaultConditionHandler dient voor de registratie van een foutafhandelingsfunctie voor de notifier van een proxy-veld in de namespace <SI-Namespace>::proxy::fields::<Field> [SWS_CM_00109]. Als parameter wordt een aanroepbaar object (callable) van het type ara::com::e2e::TransportFaultConditionHandler meegegeven. De functie levert geen retourwaarde op en bindt de callback aan de notifiers van afzonderlijke service-instanties om overdrachtsfouten van de communicatie-backend in ontvangst te nemen AUTOSAR_AP_SWS_CommunicationManagement §7.4 “End-to-end communication protection” p. 235.

Foutafhandeling en exception-veiligheid

De methode is gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig (exception safe) [SWS_CM_00109]. Is het meegegeven callable ongeldig of null, dan is er sprake van een schending van de precondition in de vorm van een InvalidHandlerViolation [SWS_CM_00109]. Interpretatie: Aangezien de functie geen excepties mag gooien, leidt een dergelijke overtreding in AUTOSAR Adaptive typisch tot onmiddellijke programmabeëindiging. Vraag Q-74df6934d4ae3c93 (open)

Gelijktijdigheid en wisselwerking

Terwijl deze basisvorm de handler rechtstreeks registreert, bestaat er met [SWS_CM_00110] een overbelaste template-variant die tevens een executor (ExecutorT&& executor) accepteert voor het bepalen van de asynchrone uitvoeringscontext. De functie past binnen de end-to-end-foutafhandeling: terwijl notifiers ([SWS_CM_00109], [SWS_CM_00110]), events ([SWS_CM_00099]) en triggers ([SWS_CM_00106]) overdrachtsfouten asynchroon via dergelijke handlers melden, worden transportfouten bij verzoeken aan methoden, getters en setters in plaats daarvan via ComErrc::kCommunicationFailure in het resulterende ara::core::Future gerapporteerd [SWS_CM_00090].

Gebruik

De template-lidfunctie SetTransportFaultConditionHandler dient binnen de scope van een proxy-field-klasse (<SI-Namespace>::proxy::fields::<Field>) voor de registratie van een handler voor de notifier van het desbetreffende field [SWS_CM_00110]. Deze accepteert twee invoerparameters:

• handler: het te registreren callable van het type ara::com::e2e::TransportFaultConditionHandler [SWS_CM_00110].
• executor: een rvalue-referentie naar een executor-object (ExecutorT&&), in de uitvoeringscontext waarvan eventuele asynchroon gestarte berekeningen worden gestart [SWS_CM_00110].

De functie levert geen retourwaarde op (void) en is gedeclareerd als noexcept [SWS_CM_00110].

Foutafhandeling en uitvoeringsveiligheid

De interface is gespecificeerd als uitzonderingsveilig (exception safe) [SWS_CM_00110]. Indien als handler een niet-bestaand of null-waardig callable wordt meegegeven, leidt dit tot een InvalidHandlerViolation [SWS_CM_00110]. Via deze handler worden specifieke transportfoutcondities gemeld, terwijl methoden en field-getters en -setters eventuele transportfouten via ComErrc::kCommunicationFailure signaleren op hun respectievelijke retour-futures [SWS_CM_00090].

Gelijktijdigheid en wisselwerking

De methode vormt de execution-context-overload van de parameterarmere basisfunctie [SWS_CM_00109]. Door het meegegeven executor-object ontkoppelt de implementatie de handler-uitvoering van de interne ontvangstcontext van het communicatiebeheer [SWS_CM_00110]. Gelijkaardige overloads staan ter beschikking voor proxy-events [SWS_CM_00100], proxy-triggers [SWS_CM_00107] alsook voor skeleton-methoden [SWS_CM_00094] en skeleton-fields [SWS_CM_00097]. Interpretatie: De aanroep vindt redelijkerwijs plaats vóór het binnenkomen van notifier-berichten respectievelijk het abonneren op de notifier, om een continue foutbewaking te garanderen. Vraag Q-bc5c62dd39c09029 (open)

De methode Subscribe dient ertoe om meldingen voor een field van een service-proxy-instantie in de scope proxy::fields::<Field> te abonneren ([SWS_CM_11601]). Via de parameter maxSampleCount legt de toepassing het maximale aantal data-samples vast dat zij gelijktijdig wenst te behouden, en richt daarmee de lokale ontvangstcache in ([SWS_CM_11601], EXP ARAComAPI §5.3 “Proxy Class API’s”). De aanroep is asynchroon: de geretourneerde ara::core::Result<void> signaleert uitsluitend de acceptatie van het abonnement door Communication Management (EXP ARAComAPI §5.3.5.2 “Monitoring Event Subscription”).

Met betrekking tot het statusgedrag en de foutafhandeling gelden de volgende regels:

• Idempotentie: Bevindt het field zich reeds in de status kSubscribed of kSubscriptionPending en komt de overgedragen maxSampleCount overeen met de waarde van de huidige subscriptie, dan keert de methode zonder effect terug ([SWS_CM_11601]).
• Foutcodes: Indien de vereiste cache niet kan worden geleverd, mislukt de operatie met de fout ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_11601], [SWS_CM_10432]).
• Toegangscontrole: Ontbreken de vereiste rechten, dan wordt de aanroep door Grant Enforcement afgewezen met een InsufficientPermissionsViolation ([SWS_CM_11601]).

De methode is gedeclareerd als noexcept en gespecificeerd als exception-safe ([SWS_CM_11601]). Semantisch volgt zij het gedrag van de event-subscriptie ([SWS_CM_00141]); de geconfigureerde cache vormt de basis voor de aansluitende sample-ontvangst via methoden zoals GetNewSamples ([SWS_CM_00701]).

De functie UnsetReceiveHandler() dient op proxy-niveau om een eerder geregistreerde ontvangst-handler voor veld-meldingen te deregistreren ([SWS_CM_11606]). Zij behoort tot de proxy-klasse-API's van ara::com (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”) en bevindt zich in de namespace <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11606]).

Wat betreft aanroepcontext en semantiek accepteert de methode geen parameters en levert geen retourwaarde op ([SWS_CM_11606]). Door de aanroep kan een toepassing op elk moment van een event-gestuurd meldingsmodel overschakelen naar een opvraaggebaseerde polling-werking, door de gebruikersspecifieke callback in te trekken (AUTOSAR_AP_EXP_ARAComAPI §5.3.2 “RadarService Proxy Class Example”).

Voor de foutafhandeling is de functie gespecificeerd als noexcept en exception safe ([SWS_CM_11606]); specifieke foutcodes bestaan volgens de specificatie niet. De aanroep vindt synchroon plaats; na succesvolle intrekking van de handler activeert Communication Management bij nieuw binnenkomende gegevens geen verdere callback-aanroepen meer (interpretatie: lopende of reeds ingeplande uitvoeringen worden vóór de intrekking vermoedelijk nog voltooid respectievelijk geserialiseerd verwerkt, aangezien callback-aanroepen door Communication Management geserialiseerd moeten plaatsvinden; zie AUTOSAR_AP_EXP_ARAComAPI §5.3.2 “RadarService Proxy Class Example”). Vraag Q-fbc65e80b8d8be38 (open)

In de wisselwerking correspondeert de methode met het deactiveren van triggers bij service-events ([SWS_CM_00183]; AUTOSAR_AP_EXP_ARAComAPI §10) en triggers ([SWS_CM_11614]). In de DDS-binding wordt het gedrag via de mapping van UnsetReceiveHandler() op de respectieve DataReader afgebeeld ([SWS_CM_11141]).

Gebruik

De methode UnsetSubscriptionStateChangeHandler dient in het kader van het AUTOSAR Adaptive-platform om een eerder geregistreerde callback voor wijzigingen in de abonnementsstatus (ara::com::SubscriptionState) van een field te verwijderen [SWS_CM_11609]. Deze wordt synchroon aangeroepen op instanties van fields van een service-proxy in de namespace <SI-Namespace>::proxy::fields::<Field> en vereist het invoegen van de gegenereerde header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 “UnsetSubscriptionStateChangeHandler”. De aanroep accepteert geen overdrachtsparameters en levert geen retourwaarde op.

Foutafhandeling en gelijktijdigheid

De interface is gedeclareerd als noexcept en voldoet volgens de specificatie aan de eigenschap exception safe [SWS_CM_11609]. Het optreden van fouten of excepties is daardoor uitgesloten. Aangezien het deregistreren onmiddellijk van kracht wordt, mag worden aangenomen (interpretatie) dat na beëindiging van de methode geen nieuwe meldingen meer aan de voormalige handler worden doorgegeven. Vraag Q-30238329b76b64f4 (open)

Samenspel

De functie behoort tot de fundamentele proxy-klasse-API's voor het beheer van abonnementen in ara::com AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”. Soortgelijke methoden voor het deactiveren van handlers voor statuswijzigingen bestaan voor proxy-events [SWS_CM_00334] en triggers [SWS_CM_01108], evenals spiegelbeeldig aan de skeleton-zijde voor events [SWS_CM_12010] en triggers [SWS_CM_01112].

Gebruik

De functie UnsetTransportFaultConditionHandler dient ertoe een eerder geregistreerde ara::com::e2e::TransportFaultConditionHandler voor de notifier van een specifiek proxy-field weer af te melden [SWS_CM_00126]. Deze is gedefinieerd binnen de scope <SI-Namespace>::proxy::fields::<Field> en wordt ingesloten via het headerbestand <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.1.4 “UnsetTransportFaultConditionHandler”. De aanroep geschiedt parameterloos en levert geen retourwaarde op (void).

Foutafhandeling

De methode is gedeclareerd als noexcept en heeft de uitzonderingsgarantie exception safe [SWS_CM_00126]. Er worden geen foutcodes teruggegeven of excepties geworpen. Indien er eerder geen handler was geregistreerd, blijft een herhaalde aanroep vermoedelijk zonder effect. Vraag Q-85da9a7b00678748 (open)

Gelijktijdigheid en beperkingen

De specificatie definieert geen afzonderlijke eisen voor gelijktijdigheid of thread-safety. Aangezien de interface synchroon werkt en geen asynchrone typen gebruikt, zal het intrekken van de fouthandler vermoedelijk synchroon en direct van kracht worden. Vraag Q-ed4cc712bb55aee5 (open) Aanroepers dienen de aanroep in de applicatielevenscyclus zodanig te coördineren dat notifier-berichten van afzonderlijke service-instanties niet ongecontroleerd zonder handler worden verwerkt AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 “End-to-end communication protection for SOMEIP”.

Samenspel

Het deregistreren volgt een consistent naamgevings- en functiepatroon in AUTOSAR Adaptive:

• Op proxy-niveau staan equivalente functies voor events ([SWS_CM_00105]) en voor triggers ([SWS_CM_00108]) ter beschikking.
• Op skeleton-niveau bestaan overeenkomstige tegenhangers voor field-getters en -setters ([SWS_CM_00098]) en overkoepelend voor alle methoden van de skeleton-interface ([SWS_CM_00095]).