class ara::diag::DoIPPowerMode

Interface class ara::diag::DoIPPowerMode enables applications to provide the current DoIP power mode to Diagnostic Management via callback function GetDoIPPowerMode() [SWS_DM_00734]. After instantiation, the handler must be activated via Offer() and deregistered again via StopOffer() before destruction [SWS_DM_00735], [SWS_DM_00736]. As a unique instance, the class is neither copyable nor movable [SWS_DM_01645].

more ›

Context

Abstract class ara::diag::DoIPPowerMode defines the interface for providing the current DoIP power mode to Diagnostic Management (DM). In vehicle architectures that utilize Diagnostic over Internet Protocol (DoIP), the communication protocol must be informed about the operating state of the vehicle network or power supply. The application software derives a concrete handler class from ara::diag::DoIPPowerMode and implements the power mode query [SWS_DM_00734]. Interaction partners are the providing diagnostic application offering the interface and the DM runtime system delegating incoming requests to this handler [SWS_DM_00735].

Lifecycle

Instances of ara::diag::DoIPPowerMode are created internally by the application and identified via a PortPrototype referenced by a ara::core::InstanceSpecifier [SWS_DM_00732]. When calling the constructor, argument ConcurrencyType specifies whether callback method GetDoIPPowerMode() must be executed thread-safe (kConcurrent) or non-thread-safe (kNotConcurrent) [SWS_DM_00732]. The constructor itself is thread-safe [SWS_DM_00732].

According to the specification, this is a non-copyable and non-movable instance: Both copy constructor [SWS_DM_01645] and move constructor [SWS_DM_01646] as well as the corresponding assignment operators [SWS_DM_01643], [SWS_DM_01644] are explicitly deleted (=delete).

After instantiation, the handler must be activated via Offer() so that the DM can forward requests [SWS_DM_00735]. To terminate the forwarding of requests, StopOffer() is called [SWS_DM_00736]. Virtual destructor ~DoIPPowerMode() [SWS_DM_00733] as well as Offer() and StopOffer() are specified as non-thread-safe. Presumably, StopOffer() should always be executed prior to calling the destructor in order to properly disconnect pending interactions with the DM. Question Q-85ede935aa303c45 (open)

Usage Path

Typical usage of ara::diag::DoIPPowerMode follows a fixed sequence of initialization, service registration, cyclic or event-based mode querying, and deregistration:

1. The application instantiates its derived class with the appropriate InstanceSpecifier and the desired ConcurrencyType [SWS_DM_00732].
2. The application actively registers the handler with Diagnostic Management using Offer() [SWS_DM_00735].
3. As soon as the DoIP protocol requires the status, the DM calls pure virtual function GetDoIPPowerMode() [SWS_DM_00734]. The implementation returns a ara::core::Future<PowerModeType> that is resolved asynchronously [SWS_DM_00734].
4. Upon termination of operation, the application calls StopOffer() to no longer accept any further requests [SWS_DM_00736].
5. The instance is released via the destructor [SWS_DM_00733].

Sequence diagram: Typical sequence of registration, asynchronous status query, and deregistration for DoIPPowerMode. Sources: [SWS_DM_00732], [SWS_DM_00734], [SWS_DM_00735], [SWS_DM_00736], AUTOSAR_AP_SWS_Diagnostics §8.2 “DoIP Power Mode”.

Error Scenarios

When calling the constructor, model and mapping violations can occur that are documented [SWS_DM_00732]:

• InstanceSpecifierMappingIntegrityViolation: The identifier cannot be resolved in the context of the executable or does not reference a PortPrototype element [SWS_DM_00732].
• PortInterfaceMappingViolation: The referenced PortPrototype is not typed by a DiagnosticDoIPPowerModeInterface [SWS_DM_00732].
• ProcessMappingViolation: An instance reference exists, but no matching modeled process for the runtime environment exists [SWS_DM_00732].
• InstanceSpecifierAlreadyInUseViolation: The InstanceSpecifier has already been used for another instance within the same process [SWS_DM_00732].

If Offer() is called while the service is already actively offered, the method returns the error code DiagOfferErrc::kAlreadyOffered via the ara::core::Result [SWS_DM_00735]. In contrast, the GetDoIPPowerMode() method defines no standardized error codes [SWS_DM_00734].