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

Verwendung

Die Funktion SetReceiveHandler dient auf Client-Seite im Scope <SI-Namespace>::proxy::events::<Event> zur Registrierung eines Callback-Handlers für eintreffende Ereignisse [SWS_CM_00181]. Als Parameter wird ein ara::com::EventReceiveHandler übergeben, der als parameterlose Funktion definiert ist und bei Event-Eingang vom Communication Management aufgerufen wird [SWS_CM_00181]. Die Funktion besitzt keinen Rückgabewert (void) [SWS_CM_00181].

Fehlerbehandlung und Ausnahmeverhalten

Die Operation ist als noexcept und ausnahmesicher (exception safe) spezifiziert [SWS_CM_00181]. Falls das übergebene Callable nicht existiert oder null ist, wird dies als InvalidHandlerViolation gewertet [SWS_CM_00181].

Ausführungskontext und Zusammenspiel

Innerhalb der Proxy-Schnittstellen gehört SetReceiveHandler zu den grundlegenden Mechanismen neben Aufrufen wie UnsetReceiveHandler() und GetNewSamples() ARAComAPI §5.3.1 „Proxy Class API’s“. Soll der Handler in einem vorgegebenen Kontext ausgeführt werden, steht die Template-Überladung mit ExecutorT bereit [SWS_CM_11356] (ARAComAPI S. 10).

Derselbe Benachrichtigungsansatz wird auch für Trigger über [SWS_CM_00250] (mit Kontext: [SWS_CM_00352]) sowie für Fields über [SWS_CM_11605] (mit Kontext: [SWS_CM_11611]) verwendet ARAComAPI §4.2 „Means of Communication“.

Die Methode SetSubscriptionStateChangeHandler im Namensraum proxy::events::<Event> registriert eine Callback-Funktion, die das Communication Management aufruft, sobald sich der Zustand ara::com::SubscriptionState des Ereignisses ändert ([SWS_CM_00333]). Die Funktion ist als noexcept deklariert und gilt als exceptionsicher ([SWS_CM_00333]).

Verwendung und asynchrone Semantik

Aufrufe von Subscribe() arbeiten prinzipiell asynchron; ein erfolgreiches Abonnement darf erst als abgeschlossen betrachtet werden, wenn der registrierte Handler oder GetSubscriptionState() den Zustand kSubscribed zurückmeldet ([SWS_CM_12006]). Der Handler wird mit kSubscriptionPending aufgerufen, wenn das Abonnement nicht unmittelbar wirksam wird (beispielsweise infolge von Busprotokoll-Latenzen) oder wenn die Server-Instanz aufgrund von Neustarts oder Netzwerkfehlern nicht erreichbar ist ([SWS_CM_00313]). Das Aufheben der Handler-Registrierung erfolgt über UnsetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 „Proxy Class API’s“).

Fehlerbehandlung und Randbedingungen

Wird kein gültiges Callback-Objekt übergeben oder ist dieses null, liegt der Fehlerfall InvalidHandlerViolation vor ([SWS_CM_00333]). Hinsichtlich der Aufrufreihenfolge dürfte der Handler zweckmäßigerweise vor Subscribe() registriert werden, um frühe Statusübergänge zuverlässig zu erfassen. Frage Q-3b9c25c6aa2d0a0f (offen)

Zusammenspiel und Varianten

Für die Ausführung des Handlers in einem vorgegebenen Thread- oder Arbeitskontext steht die überladene Template-Variante mit Parameter ExecutorT bereit ([SWS_CM_11354]). Parallele Schnittstellen existieren für Proxy-Trigger ([SWS_CM_01107]), Proxy-Fields ([SWS_CM_11607]) sowie auf Skeleton-Ebene ([SWS_CM_12008]).

Die Template-Elementfunktion SetSubscriptionStateChangeHandler dient im Scope proxy::events::<Event> dazu, eine Callback-Funktion für Zustandsänderungen des Abonnements (ara::com::SubscriptionState) zu registrieren ([SWS_CM_11354], AP EXP ARAComAPI §5.3.1 „Proxy Class API’s“). Im Gegensatz zur Basisfunktion [SWS_CM_00333] wird der Handler nicht im internen Kontext des Communication Management ausgeführt, sondern über den Template-Parameter ExecutorT an einen bereitgestellten Ausführungskontext executor übergeben ([SWS_CM_11360], AP EXP ARAComAPI §1.0 „SetSubscriptionState with ExecutorT“).

Parameter und Rückgabewerte

• handler: Das aufzurufende Callable, das bei einer Änderung des ara::com::SubscriptionState des Events benachrichtigt wird ([SWS_CM_00333]).
• executor: Der Ausführungskontext gemäß [SWS_CM_11360], in dem der Handler abgearbeitet werden soll.
• Rückgabewert: Die Funktion besitzt keinen Rückgabewert (void).

Fehlerbehandlung und Ausführung

Die Funktion ist als noexcept deklariert und als ausnahmesicher (exception safe) spezifiziert. Falls das übergebene Callable handler nicht existiert oder null ist, wird eine InvalidHandlerViolation ausgelöst ([SWS_CM_11354]).

Zusammenspiel

Das Muster der kontextgebundenen Zustandsüberwachung mit ExecutorT existiert analog für Proxy-Trigger ([SWS_CM_01106]) sowie Proxy-Felder ([SWS_CM_11608]). Wird keine Auslagerung in einen spezifischen Kontext benötigt, steht die Variante [SWS_CM_00333] zur Verfügung.

Die Elementfunktion SetTransportFaultConditionHandler dient an einem Proxy-Event ([SWS_CM_00099]) zur Registrierung einer Callback-Funktion vom Typ ara::com::e2e::TransportFaultConditionHandler. Über diesen Handler werden Übertragungsfehler gemeldet, die auf der Transportebene des Kommunikations-Bindings erkannt werden ([SWS_CM_00211]).

Verwendung und Semantik:

• Aufruf und Parameter: Die Funktion nimmt das aufrufbare Handler-Objekt handler entgegen und liefert keinen Rückgabewert ([SWS_CM_00099]). Die Methodensignatur ist als noexcept deklariert ([SWS_CM_00099]).
• Übertragene Fehlerzustände: Der registrierte Handler meldet im Fehlerfall Werte des Enums ara::com::e2e::TransportFaultCondition, wie beispielsweise kSampleRejected bei verworfenen Samples des zugrunde liegenden Transportkanals ([SWS_CM_00211]).
• Ausführungskontext: Für asynchrone Ausführungen steht eine Template-Überladung mit zusätzlichem Executor-Objekt ExecutorT&& executor bereit ([SWS_CM_00100]).

Fehlerbehandlung und Randbedingungen:

• Ausnahmesicherheit: Die Funktion gilt als ausnahmesicher (exception safe) ([SWS_CM_00099]).
• Verletzungen: Wenn das übergebene Callable nicht existiert oder null ist, liegt eine InvalidHandlerViolation vor ([SWS_CM_00099]).
• Zusammenspiel: Äquivalente Schnittstellen zur Registrierung eines TransportFaultConditionHandler existieren auch für Trigger ([SWS_CM_00106]), Field-Notifier ([SWS_CM_00109]) und Skeleton-Methoden ([SWS_CM_00093]).

Die Template-Funktion SetTransportFaultConditionHandler registriert an einem Proxy-Event einen anwendungsspezifischen Handler vom Typ ara::com::e2e::TransportFaultConditionHandler zusammen mit einem benutzerdefinierten Executor ([SWS_CM_00100]). Sie stellt die Execution-Context-Überladung zur parameterärmeren Basisfunktion dar ([SWS_CM_00099]).

Verwendung und Parameter: Die Methode wird auf Instanzen von <SI-Namespace>::proxy::events::<Event> aufgerufen und gibt keinen Wert zurück (void) ([SWS_CM_00100]). Sie nimmt den aufzurufenden Handler (handler) entgegen und übernimmt ein Executor-Objekt (executor als universelle Referenz ExecutorT&&), in dessen Kontext jegliche asynchrone Ausführung des Handlers angestoßen wird ([SWS_CM_00100]). Die Funktionssignatur ist mit noexcept deklariert ([SWS_CM_00100]).

Fehlerbehandlung: Die Operation ist als exception safe spezifiziert ([SWS_CM_00100]). Wird ein ungültiges oder nicht existentes Callable übergeben (null), liegt eine Verletzung in Form von InvalidHandlerViolation vor ([SWS_CM_00100]). Über den registrierten Handler werden erkannte Transportfehler gemeldet, wie beispielsweise TransportFaultCondition::kSampleRejected beim Verwerfen eingehender Datenproben durch die zugrundeliegende Transport-Entität ([SWS_CM_00211]).

Zusammenspiel: Während [SWS_CM_00099] die Registrierung ohne expliziten Executor vornimmt, ermöglicht diese Überladung die Ausführung im gewünschten Thread- bzw. Task-Kontext ([SWS_CM_00100]). Analoge Überladungen mit Executor stehen für Skeleton-Methoden ([SWS_CM_00094]) und Skeleton-Felder ([SWS_CM_00097]) sowie auf Proxy-Seite für Trigger ([SWS_CM_00107]) und Feld-Notifier ([SWS_CM_00110]) zur Verfügung.

Verwendung

Die Methode Subscribe registriert das Proxy-Element für den Empfang von Service-Events gemäß [SWS_CM_00141]. Der Aufruf ist asynchroner Natur: Die Rückkehr der Funktion bestätigt lediglich, dass das Communication Management die Registrierungsanforderung akzeptiert hat (AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 „Monitoring Event Subscription“). Mit dem Pflichtparameter maxSampleCount teilt die Anwendung verbindlich mit, wie viele Event-Samples sie maximal gleichzeitig halten wird, und initialisiert dadurch den lokalen Empfangspuffer (AUTOSAR_AP_EXP_ARAComAPI S. 40).

Fehlerbehandlung und Randbedingungen

Ist das Event beim Aufruf bereits im Zustand kSubscribed oder kSubscriptionPending und stimmt der übergebene Wert maxSampleCount mit der aktiven Subskription überein, kehrt die Methode ohne Aktion erfolgreich zurück ([SWS_CM_00141]). Weicht die Cache-Größe bei einer erneuten Subskription hingegen ab, schlägt der Aufruf fehl und liefert im ara::core::Result den Fehlercode ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_00141]). Bei fehlenden Zugriffsberechtigungen wird der Aufruf verweigert (InsufficientPermissionsViolation gemäß [SWS_CM_00141]). Die Signatur ist als noexcept deklariert und gilt als ausnahmesicher.

Zusammenspiel

Die reservierte Cache-Kapazität begrenzt den späteren Datenempfang über GetNewSamples ([SWS_CM_00701]); hält die Anwendung mehr Smartpointer als spezifiziert, wird der Fehler ComErrc::kMaxSamplesExceeded ausgelöst ([SWS_CM_10432]). Während Feld-Events identisch über maxSampleCount abonniert werden ([SWS_CM_11601]), erfordern reine Trigger-Events keine Puffergrößenangabe ([SWS_CM_00723]).

Verwendung

Die Funktion UnsetReceiveHandler ist Teil des Event-Wrappers im Scope <SI-Namespace>::proxy::events::<Event> und wird über die Header-Datei #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" eingebunden ([SWS_CM_00183]). Sie nimmt keine Übergabeparameter entgegen und besitzt keinen Rückgabewert (void). Durch den Aufruf wird ein zuvor mit SetReceiveHandler registrierter anwendungsspezifischer Empfangs-Handler für ein Service-Event wieder entfernt (EXP ARAComAPI §5.3.2 „RadarService Proxy Class Example“). Dadurch kann die empfangende Anwendung jederzeit zwischen einem ereignisgesteuerten Empfang („event-driven“) und einem aktiven Abfragebetrieb („polling style“) mittels GetNewSamples() wechseln (EXP ARAComAPI §5.3.2 „RadarService Proxy Class Example“).

Fehlerbehandlung

Die Methode ist mit noexcept deklariert und besitzt die Eigenschaft exception safe ([SWS_CM_00183]). Sie wirft zur Laufzeit keine Exceptions und meldet keine spezifischen Fehlercodes zurück.

Nebenläufigkeit und Bindung

Während für den registrierten Callback-Handler gilt, dass dieser nicht reentrant sein muss, weil das Communication Management Aufrufe serialisiert (EXP ARAComAPI §5.3.2 „RadarService Proxy Class Example“), deaktiviert UnsetReceiveHandler den Event-Trigger für den Empfang weiterer Benachrichtigungen ([SWS_CM_00183]). Im Kontext des DDS-Bindings wird die Methode UnsetReceiveHandler() gemäß [SWS_CM_11141] entsprechend der Vorgabe [SWS_CM_11026] auf den zugehörigen DataReader abgebildet.

Zusammenspiel

Die Funktion bildet das direkte Gegenstück zur Registrierung über SetReceiveHandler ([SWS_CM_11140], EXP ARAComAPI §5.3.1 „Proxy Class API’s“). Verwandte Funktionen finden sich in anderen Proxy-Schnittstellen:

• Für Felder existiert eine identisch benannte Funktion UnsetReceiveHandler im Scope <SI-Namespace>::proxy::fields::<Field>, welche ebenfalls als noexcept und exception safe definiert ist ([SWS_CM_11606]).
• Für Trigger steht UnsetReceiveHandler im Scope <SI-Namespace>::proxy::triggers::<Trigger> zur Verfügung, ist jedoch abweichend als not exception safe deklariert ([SWS_CM_11614]).

Verwendung

Die Elementfunktion UnsetSubscriptionStateChangeHandler dient dem Zurücksetzen und Deregistrieren eines zuvor gesetzten Callback-Handlers für Änderungen des Abonnementstatus (ara::com::SubscriptionState) auf Proxy-Seite ([SWS_CM_00334], EXP ARAComAPI §1.0). Die Funktion ist Bestandteil der Ereignisschnittstelle und befindet sich im anwendungsspezifischen Namensraum unter proxy::events ([SWS_CM_00334], SWS CommunicationManagement §8.3.2.2.4.5 „UnsetSubscriptionStateChangeHandler“). Zur Nutzung wird die generierte Proxy-Header-Datei <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h eingebunden ([SWS_CM_00334]). Der Aufruf erfolgt synchron, nimmt keine Parameter entgegen und liefert keinen Rückgabewert ([SWS_CM_00334]).

Fehlerbehandlung

Gemäß Spezifikation ist die Funktion mit dem Bezeichner noexcept deklariert und als ausnahmesicher („exception safe“) eingestuft ([SWS_CM_00334]). Sie löst im Fehlerfall keine C++-Ausnahmen aus und meldet keine Fehlercodes zurück ([SWS_CM_00334]).

Nebenläufigkeit und Zusammenspiel

Die Funktion steht im Verbund mit weiteren Proxy-APIs zur Dienstsuche und Ereignisverwaltung wie Subscribe(), Unsubscribe(), GetSubscriptionState() und SetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 „Proxy Class API’s“). Als Interpretation dürften nach dem Aufruf keine weiteren Benachrichtigungen über den deregistrierten Handler ausgelöst werden. Frage Q-6173c01e6ca93876 (offen) Symmetrische Gegenstücke zum Zurücksetzen von Handlern für Statusänderungen sind in der Spezifikation für Proxy-Fields ([SWS_CM_11609], SWS CommunicationManagement §8.3.3.2.4.5 „UnsetSubscriptionStateChangeHandler“) und Triggers ([SWS_CM_01108]) sowie auf Service-Provider-Seite (Skeleton) für Events ([SWS_CM_12010]) und Triggers ([SWS_CM_01112]) definiert.

Verwendung

Die Funktion UnsetTransportFaultConditionHandler im Namensbereich <SI-Namespace>::proxy::events::<Event> dient dazu, einen zuvor registrierten ara::com::e2e::TransportFaultConditionHandler für ein konkretes Proxy-Event zu deregistrieren [SWS_CM_00105]. Die Funktionsdeklaration wird über die Header-Datei <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h bereitgestellt AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.1.3 „UnsetTransportFaultConditionHandler“. Der Aufruf nimmt keine Parameter entgegen und liefert keinen Rückgabewert (void).

Fehlerbehandlung und Ausnahme-Sicherheit

Die Funktion ist mit dem Bezeichner noexcept deklariert und als ausnahmesicher (exception safe) spezifiziert [SWS_CM_00105]. Weder spezifische Fehlercodes noch Benachrichtigungen an Fehler- oder Diagnose-Subsysteme sind im Standard definiert.

Ablauf und Randbedingungen

Der Aufruf dürfte synchron ausgeführt werden, um die E2E-Fehlerbehandlung auf Event-Ebene unmittelbar abzustellen, beispielsweise wenn das Ereignis nicht mehr überwacht werden soll oder bevor das zugehörige Proxy-Objekt freigegeben wird (Interpretation). Frage Q-ff00695fff5407fe (offen) Nach Ausführung verarbeitet die Kommunikationsschicht keine E2E-Transportfehler mehr über den zuvor hinterlegten Callback dieses Events.

Zusammenspiel

Das Deregistrieren von Handlern für Transportfehler folgt einem einheitlichen Muster über verschiedene Kommunikations-Elemente hinweg:

• Für Notifier von Feldern auf Proxy-Ebene dient die Funktion [SWS_CM_00126].
• Für Proxy-Trigger wird der Handler über [SWS_CM_00108] abgemeldet.
• Auf Skeleton-Seite stehen analoge Schnittstellen für sämtliche Methoden eines Service-Interfaces ([SWS_CM_00095]) sowie für Getter/Setter von Feldern ([SWS_CM_00098]) zur Verfügung.

Verwendung

Die Methode Unsubscribe() beendet das aktive Abonnement eines Service-Events auf Proxy-Seite ([SWS_CM_00151], EXP_ARAComAPI §5.5). Sie ist im Gültigkeitsbereich <SI-Namespace>::proxy::events::<Event> definiert und wird über die Header-Datei #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" eingebunden ([SWS_CM_00151]). Die Funktion nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert (void). War das Event zum Zeitpunkt des Aufrufs nicht abonniert, kehrt die Methode ohne Ausführung einer Aktion zurück ([SWS_CM_00151]).

Fehlerbehandlung und Exception-Sicherheit

Die Operation ist mit dem Bezeichner noexcept deklariert und als exceptionsicher spezifiziert ([SWS_CM_00151]). Als Verletzung (Violation) ist eine DanglingSamplesViolation vorgesehen, falls vor dem Methodenaufruf die Vorbedingung nach [SWS_CM_00085] verletzt wurde ([SWS_CM_00151]).

Zusammenspiel und verwandte Schnittstellen

Auf Netzwerkebene stößt das Beenden des Abonnements das Senden von SOME/IP-Nachrichten des Typs StopSubscribeEventgroup an ([SWS_CM_10378], SWS_CommunicationManagement §7.2.1.2.6). Innerhalb der Proxy-Schnittstellen gehört Unsubscribe() zur Gruppe der Methoden zur Subskriptionsverwaltung (EXP_ARAComAPI §5.3.1). Eine identische Abmeldesemantik steht auch für Service-Trigger ([SWS_CM_00810], EXP_ARAComAPI §4) sowie für Field-Benachrichtigungen ([SWS_CM_11602]) zur Verfügung.