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

Verwendung

Die Funktion SetReceiveHandler wird im Scope der Trigger-Klasse eines Dienst-Proxys (<SI-Namespace>::proxy::triggers::<Trigger>) aufgerufen und über den Header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h eingebunden [SWS_CM_00250]. Triggers bilden neben Events, Methods und Fields einen der vier Kommunikationsmechanismen in ara::com EXP_ARAComAPI §4.2 „Means of Communication“.

Der Parameter handler vom Typ ara::com::TriggerReceiveHandler nimmt ein aufrufbares Objekt entgegen, das vom Communication Management bei Eintreffen eines Triggers aufgerufen wird. Der Handler selbst besitzt keine Parameter; um den aktuellen Trigger-Zählerstand abzufragen, muss innerhalb der Callback-Funktion die Methode GetNewTriggers der spezifischen Trigger-Klasse aufgerufen werden [SWS_CM_00250].

Fehlerbehandlung und Exception-Sicherheit

Die Registrierung liefert keinen Rückgabewert (void) und ist als noexcept sowie exception safe definiert [SWS_CM_00250]. Eine Verletzung der Aufrufkonvention in Form einer InvalidHandlerViolation tritt auf, wenn das übergebene Callable nicht existiert oder null ist [SWS_CM_00250].

Zusammenspiel und Varianten

Für Szenarien, in denen der Trigger-Handler in einem definierten Ausführungskontext abgearbeitet werden soll, existiert die Template-Überladung mit ExecutorT [SWS_CM_00352]. Vergleichbare Registrierungsmethoden für Callbacks stehen auf Proxy-Ebene auch für Events ([SWS_CM_00181], [SWS_CM_11356]) sowie Fields ([SWS_CM_11605], [SWS_CM_11611]) zur Verfügung EXP_ARAComAPI §5.3.1 „Proxy Class API’s“.

Verwendung

Die Template-Funktion SetSubscriptionStateChangeHandler im Gültigkeitsbereich <SI-Namespace>::proxy::triggers::<Trigger> registriert einen Callback zur Benachrichtigung über Änderungen des Abonnementstatus ([SWS_CM_01106]). Sie wird über die Header-Datei <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h deklariert und nimmt zwei Parameter entgegen:

• handler: Die aufrufbare Einheit vom Typ ara::com::SubscriptionStateChangeHandler, die bei einer Statusänderung ausgeführt werden soll ([SWS_CM_01107]).
• executor: Ein Ausführungskontext vom Typ ExecutorT ([SWS_CM_11360]), in dem die Ausführung des Handlers erfolgen muss.

Die Registrierung selbst verhält sich synchron und besitzt keinen Rückgabewert (void). Der registrierte Callback wird bei Statusänderungen im angegebenen Ausführungskontext ausgeführt.

Fehlerbehandlung und Exception-Sicherheit

Die Methode ist als noexcept deklariert und als exception safe spezifiziert ([SWS_CM_01106]). Wenn die übergebene Callable-Instanz nicht existiert oder null ist, liegt eine InvalidHandlerViolation vor ([SWS_CM_01106]). Da keine Ausnahmen geworfen werden, führt ein ungültiger Handler vermutlich zu einem plattformspezifischen Fehlerpfad (Interpretation). Frage Q-cbb90bfbfa10338d (offen)

Nebenläufigkeit und Zusammenspiel

Durch die Übergabe des Executors ([SWS_CM_11360]) steuert die Anwendung den Ausführungskontext für Status-Callbacks selbst. Dies dürfte verhindern, dass langlaufende Handler-Aufrufe die interne Ereignisverarbeitung der Kommunikationsverwaltung blockieren (Interpretation). Frage (offen) Die Funktion erweitert die kontextlose Variante [SWS_CM_01107] und bildet das Trigger-Pendant zu den Executor-basierten Schnittstellen für Proxy-Events ([SWS_CM_11354]), Proxy-Fields ([SWS_CM_11608]) und Skeleton-Trigger ([SWS_CM_11111]).

Mit der Funktion [SWS_CM_01107] wird im Proxy-Bereich eines Triggers (<SI-Namespace>::proxy::triggers::<Trigger>) ein Callback-Handler registriert, den das Communication Management bei jeder Änderung des Abonnementzustands (ara::com::SubscriptionState) aufruft. Die Funktion besitzt keinen Rückgabewert und ist als ausnahmesicher (noexcept) spezifiziert.

Da das Abonnieren grundsätzlich als asynchroner Vorgang zu behandeln ist, darf die Anwendung erst dann von einem erfolgreichen Abonnement ausgehen, wenn der über [SWS_CM_01107] registrierte Handler oder die Abfragefunktion GetSubscriptionState() den Zustand kSubscribed meldet [SWS_CM_12006]. Bei zeitlichen Verzögerungen oder wenn der Server infolge eines Neustarts bzw. Netzwerkproblems temporär nicht verfügbar ist, aktiviert das Communication Management den Handler mit dem Zustand kSubscriptionPending [SWS_CM_00313].

Für die Fehlerbehandlung und Integration gelten folgende Randbedingungen:

• Fehlerbehandlung: Die Übergabe eines nicht existierenden oder leeren Callables (null) ist unzulässig und führt zu einer InvalidHandlerViolation [SWS_CM_01107].
• Ausführungskontext: Soll der Handler nicht im Standardkontext, sondern innerhalb eines spezifischen Ausführungskontexts ausgeführt werden, steht die Template-Überladung mit ExecutorT&& bereit [SWS_CM_01106].
• Zusammenspiel: Für Service-Ereignisse existiert die analoge Schnittstelle [SWS_CM_00333] im Rahmen der allgemeinen Proxy-Klassen-APIs ARAComAPI §5.3.1 „Proxy Class API’s“.

Die Funktion SetTransportFaultConditionHandler dient an einer Instanz von proxy::triggers::<Trigger> zur Registrierung einer Callback-Funktion vom Typ ara::com::e2e::TransportFaultConditionHandler ([SWS_CM_00106]). Sie nimmt den Parameter handler entgegen, besitzt keinen Rückgabewert und ist als noexcept sowie exception safe spezifiziert ([SWS_CM_00106]).

Über den registrierten Handler signalisiert die Kommunikationsschicht festgestellte Fehler der Übertragungsschicht. Im DDS-Network-Binding meldet der Handler Ereignisse der zugrundeliegenden DataReader-Entität als TransportFaultCondition ([SWS_CM_00212]):

• TransportFaultCondition::kSampleRejected bei verworfenen Samples (etwa durch Speicherknappheit oder Datenkorruption),
• TransportFaultCondition::kDeadlineMissed bei verletzten Empfangs-Deadlines (REQUESTED_DEADLINE_MISSED),
• TransportFaultCondition::kSampleLost beim Verlust erkannter Datensamples ([SWS_CM_00212]).

Wird anstelle eines gültigen Callables ein nicht existierender oder leerer Handler übergeben, meldet die Laufzeitumgebung eine InvalidHandlerViolation ([SWS_CM_00106]). Da die Funktionssignatur noexcept deklariert ist, führt dieser Verstoß vermutlich zu einer plattformseitigen Fehlerbehandlung statt zu einer C++-Exception. Frage Q-ebaf44b8f7b198e8 (offen)

Die Registrierung erfolgt synchron im Kontext des Aufrufers; die Ausführung des Handlers wird bei dieser Überladung nicht an einen spezifischen Dispatcher delegiert. Soll der Callback in einem definierten Ausführungskontext laufen, steht die überladene Template-Variante mit zusätzlichem ExecutorT&& zur Verfügung ([SWS_CM_00107]). Die Anbindung dürfte typischerweise vor der eigentlichen Trigger-Verarbeitung erfolgen, um Fehler von Beginn an zu erfassen. Frage (offen)

Korrespondierende Registrierungsmöglichkeiten für TransportFaultConditionHandler existieren gleichartig für Proxy-Events ([SWS_CM_00099]), Proxy-Fields ([SWS_CM_00109]) sowie Skeleton-Methoden ([SWS_CM_00093]) und Skeleton-Fields ([SWS_CM_00096]).

Die Funktion [SWS_CM_00107] dient der Registrierung einer Callback-Routine für Transportfehler eines Proxy-Triggers im Namensraum <SI-Namespace>::proxy::triggers::<Trigger>. Als Überladung mit Ausführungskontext nimmt sie neben dem Handler vom Typ ara::com::e2e::TransportFaultConditionHandler ein Executor-Objekt executor entgegen, in welchem ausgelöste asynchrone Berechnungen ausgeführt werden.

Zur Verwendung und Fehlerbehandlung gelten folgende Festlegungen:

• Parameter und Rückgabewert: Der Parameter handler übergibt das zu setzende Callable, während executor den Ausführungskontext für asynchrone Aufgaben definiert [SWS_CM_00107]. Die Funktion liefert keinen Rückgabewert zurück und ist als noexcept deklariert (Exception-Sicherheit: exception safe).
• Fehlerfälle und Verletzungen: Wird ein nicht existierender oder ungültiger Handler übergeben (null), meldet die Laufzeit eine InvalidHandlerViolation [SWS_CM_00107].
• Gemeldete Fehlerzustände: Der registrierte Handler empfängt erkannte Transportfehler gemäß [SWS_CM_00212]. Dazu zählen TransportFaultCondition::kSampleRejected (etwa bei Datenbeschädigung oder Ressourcenmangel), TransportFaultCondition::kDeadlineMissed (bei verletzten Fristen) sowie TransportFaultCondition::kSampleLost (bei verloren gegangenen Samples).

Im Vergleich zur Basisfunktion ohne Executor [SWS_CM_00106] ermöglicht diese Variante die gezielte Steuerung des Nebenläufigkeitskontexts für die Fehlerverarbeitung des Triggers. Analoge Überladungen mit Ausführungskontext existieren im Kommunikationsmanagement für Proxy-Events [SWS_CM_00100], Proxy-Fields [SWS_CM_00110] sowie auf Skeleton-Ebene für Methoden [SWS_CM_00094] und Fields [SWS_CM_00097].

Die Methode Subscribe dient dem clientseitigen Abonnieren eines Service-Triggers über eine Proxy-Instanz im Namensraum <SI-Namespace>::proxy::triggers::<Trigger> [SWS_CM_00723]. Vor der Verwendung muss die Service-Instanz serverseitig via OfferService() bereitgestellt und vom Client über Service-Discovery-Mechanismen gefunden worden sein AUTOSAR_AP_EXP_ARAComAPI §4.2 „Means of Communication“.

Im Vergleich zu Event- ([SWS_CM_00141]) und Field-Subskriptionen ([SWS_CM_11601]) weist Subscribe für Trigger spezifische Eigenschaften auf:

• Parameter und Cache: Die Funktion nimmt keine Parameter entgegen (void Subscribe() noexcept) [SWS_CM_00723]. Da Trigger reine Benachrichtigungen ohne Datensamples übermitteln, entfällt die bei Events übliche Reservierung eines lokalen Sample-Caches über maxSampleCount [SWS_CM_00141].
• Rückgabewert: Es wird kein ara::core::Result zurückgegeben, sondern void [SWS_CM_00723].
• Asynchronität: Der Aufruf stößt das Abonnement an; die tatsächliche Etablierung der Verbindung zur Service-Instanz dürfte dabei analog zu Event-Subskriptionen asynchron im Kommunikationsmanagement erfolgen AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 „Monitoring Event Subscription“. Frage Q-92ae3f442b45f3cc (offen)

Für den Lebenszyklus und die Fehlerbehandlung gelten folgende Bedingungen:

• Zustandsprüfung und Idempotenz: Befindet sich der Trigger zum Aufrufzeitpunkt bereits im Zustand kSubscribed oder kSubscriptionPending, kehrt die Methode unmittelbar ohne weitere Aktion zurück [SWS_CM_00723].
• Ausnahmesicherheit: Die Funktion ist als noexcept und exception safe spezifiziert [SWS_CM_00723].
• Zugriffskontrolle: Bei unzureichenden Rechten verweigert das Grant-Enforcement die Ausführung mit einer InsufficientPermissionsViolation [SWS_CM_00723].

Verwendung

Die synchrone Funktion UnsetReceiveHandler im Namensraum <SI-Namespace>::proxy::triggers::<Trigger> dient der Deaktivierung des zuvor registrierten Empfangshandlers für einen Service-Trigger auf Proxy-Seite [SWS_CM_11614]. Die Funktion erfordert das Einbinden der Header-Datei #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h", nimmt keine Übergabeparameter entgegen und besitzt keinen Rückgabewert.

Durch den Aufruf wird der anwendungsspezifische Callback deregistriert. Dies erlaubt es der Anwendung, flexibel zwischen einem ereignisgesteuerten Empfang und einem abfragebasierten Modell (Polling) zu wechseln (AUTOSAR_AP_EXP_ARAComAPI S. 46, AUTOSAR_AP_SWS_CommunicationManagement §7.5.18.1).

Fehlerbehandlung und Ausnahmesicherheit

Im Gegensatz zu den analogen Funktionen für Service-Events [SWS_CM_00183] und Service-Fields [SWS_CM_11606], welche explizit als noexcept und ausnahmesicher spezifiziert sind, ist UnsetReceiveHandler für Trigger als nicht ausnahmesicher (not exception safe) deklariert [SWS_CM_11614]. Interpretation: Aufrufende sollten sich darauf einstellen, dass bei internen Fehlern der Kommunikationsinfrastruktur Exceptions geworfen werden dürften, wenngleich spezifische Exception-Typen oder Fehlercodes im Standard nicht aufgeführt sind. Frage Q-92e16243a7ddee35 (offen)

Zusammenspiel und Bindings

Die Methode ist Bestandteil der Trigger-Klassen im Proxy-Namensraum (AUTOSAR_AP_EXP_ARAComAPI §5.3.1). Bei Einsatz eines DDS-Bindings wird der Methodenaufruf gemäß [SWS_CM_11141] über den zugeordneten DataReader nach den in [SWS_CM_11026] festgelegten Vorschriften abgebildet.

Die Funktion UnsetSubscriptionStateChangeHandler dient auf Client-Seite dazu, einen zuvor registrierten Callback für Zustandsänderungen des Abonnements (ara::com::SubscriptionState) eines Triggers zu entfernen [SWS_CM_01108]. Sie ist im Gültigkeitsbereich <SI-Namespace>::proxy::triggers::<Trigger> deklariert und über den Header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" einzubinden [SWS_CM_01108].

Verwendung und Aufrufkontext

Die Methode besitzt die Signatur void UnsetSubscriptionStateChangeHandler () noexcept;, nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert zurück [SWS_CM_01108]. Sie wird synchron auf der Instanz des jeweiligen Triggers einer Proxy-Klasse aufgerufen, um Benachrichtigungen bei Änderungen des Abonnementstatus wieder abzubestellen AUTOSAR_AP_EXP_ARAComAPI §5.3.1 „Proxy Class API’s“. Interpretation: Nach Ausführung des Aufrufs dürften keine weiteren Statusänderungen mehr an den bisherigen Handler zugestellt werden. Frage Q-d08dc975aacba85c (offen)

Fehlerbehandlung und Nebenläufigkeit

Die Schnittstelle ist als noexcept deklariert und explizit als ausnahmesicher (exception safe) spezifiziert [SWS_CM_01108]. Ein Scheitern des Aufrufs oder das Werfen von Exceptions ist daher ausgeschlossen, und es existieren keine Fehlerrückgabewerte.

Zusammenspiel

Die Funktion fügt sich in das einheitliche Schema der Proxy-Schnittstellen ein. Analoge Deregistrierungsmethoden stehen im Proxy-Kontext für Events gemäß [SWS_CM_00334] AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.4.5 „UnsetSubscriptionStateChangeHandler“ sowie für Fields gemäß [SWS_CM_11609] AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 „UnsetSubscriptionStateChangeHandler“ zur Verfügung. Auf Server- bzw. Skeleton-Seite existieren korrespondierende Pendants für Trigger [SWS_CM_01112] und Events [SWS_CM_12010].

Die Funktion UnsetTransportFaultConditionHandler dient dazu, einen zuvor registrierten ara::com::e2e::TransportFaultConditionHandler für einen bestimmten Proxy-Trigger wieder abzumelden ([SWS_CM_00108], dokumentiert in AUTOSAR_AP_SWS_CommunicationManagement §8.3.7.1.1.3 „UnsetTransportFaultConditionHandler“). Sie ist im Namensraum <SI-Namespace>::proxy::triggers::<Trigger> verortet und über die Header-Datei #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" einzubinden ([SWS_CM_00108]).

Die Signatur lautet void UnsetTransportFaultConditionHandler() noexcept;. Der Aufruf nimmt keine Parameter entgegen und liefert keinen Rückgabewert zurück ([SWS_CM_00108]). Durch die noexcept-Deklaration und die Klassifikation als exception safe wirft die Funktion im regulären Betrieb keine Ausnahmen ([SWS_CM_00108]). Spezifische Fehlercodes, Fehlerkanäle oder Rückfallwerte sind in der Spezifikation nicht vorgesehen.

Hinsichtlich des Ablaufs hebt die Funktion die Verknüpfung mit der Fehlerbehandlungsroutine synchron auf; folglich dürften nach erfolgreicher Ausführung keine weiteren Benachrichtigungen über E2E-Transportfehler für den betroffenen Trigger an den bisherigen Handler zugestellt werden (Interpretation). Frage Q-ae8477bc6530e352 (offen)

Im Rahmen des Gesamtsystems bildet das Element das Gegenstück zu analogen Abmeldefunktionen für andere Kommunikationsmuster in AUTOSAR_AP_SWS_CommunicationManagement §8.3/8.4:

• Proxy-Events: UnsetTransportFaultConditionHandler auf Event-Ebene ([SWS_CM_00105]).
• Proxy-Fields: Abmeldung für Field-Notifier ([SWS_CM_00126]).
• Skeleton-Ebene: Abmeldung für Field-Get/Set ([SWS_CM_00098]) sowie für sämtliche Methoden eines Skeletons ([SWS_CM_00095]).