class ara::diag::DoIPEntityIdentification

The class ara::diag::DoIPEntityIdentification enables adaptive applications to dynamically provide the entity identification (EID) for the DoIP diagnostic protocol [SWS_DM_01361]. After instantiation, the application activates forwarding by means of Offer() and answers queries from Diagnostic Management via the pure virtual method GetEntityId() asynchronously by means of a future [SWS_DM_01366], [SWS_DM_01367]. If the interface is not yet provided when a query occurs, Diagnostic Management transmits a standardized 0xFF value as a replacement [SWS_DM_01528].

more ›

Context

The class ara::diag::DoIPEntityIdentification serves to dynamically provide the entity identification (EID) for the DoIP protocol (Diagnostic over IP) [SWS_DM_01361]. In an AUTOSAR Adaptive environment, it forms the functional bridge between an individual adaptive application and Diagnostic Management (DM) AUTOSAR_AP_SWS_Diagnostics, p. 107. If DoIpNetworkConfiguration.eidRetrieval is set to the mode DoIpEidRetrievalEnum.eidUseApi in the configuration, Diagnostic Management requests the EID via this programming interface [SWS_DM_01361]. Binding to the software architecture is established via a ara::core::InstanceSpecifier that references a PortPrototype of an DiagnosticDoIPEntityIdentificationInterface [SWS_DM_01364].

Lifecycle

Creation takes place via the explicit constructor, to which, in addition to InstanceSpecifier, the parameter ConcurrencyType (kConcurrent or kNotConcurrent) is passed [SWS_DM_01364]. The latter specifies whether subsequent invocations of the interface must be handled in a thread-safe manner [SWS_DM_01364], [SWS_DM_01366]. After construction, the object initially remains in an inactive state. Invoking Offer() enables the interface for Diagnostic Management and activates the forwarding of requests to the handler [SWS_DM_01367]. Before the object is destroyed or upon termination of operation, StopOffer() disables forwarding again [SWS_DM_01368]. Finally, destruction takes place via the virtual destructor [SWS_DM_01365]. Neither Offer(), StopOffer() nor the destructor are thread-safe and therefore require coordinated synchronization in the application code [SWS_DM_01365], [SWS_DM_01367], [SWS_DM_01368].

State diagram: Lifecycle and registration phases of DoIP entity identification. Sources: [SWS_DM_01364], [SWS_DM_01365], [SWS_DM_01367], [SWS_DM_01368].

Usage Path

In the typical usage scenario, the adaptive application derives its own implementation class from ara::diag::DoIPEntityIdentification and overrides the pure virtual method GetEntityId() [SWS_DM_01366]. After instantiation with a valid identifier, the application registers the handler using Offer() [SWS_DM_01367]. As soon as Diagnostic Management requires the entity ID to assemble DoIP messages, it invokes GetEntityId() [SWS_DM_01361], [SWS_DM_01366]. The method returns a ara::core::Future<EntityId>, allowing the identification data to be determined and provided asynchronously [SWS_DM_01366]. When functional operation ends, the application revokes the offer via StopOffer() [SWS_DM_01368].

Sequence diagram: Typical call sequence for registration and querying of the EID by Diagnostic Management. Sources: [SWS_DM_01361], [SWS_DM_01364], [SWS_DM_01366], [SWS_DM_01367], [SWS_DM_01368].

Error Scenarios

Erroneous model configurations during construction lead to specific runtime violations: If the InstanceSpecifier cannot be resolved in the model or does not reference a PortPrototype, a InstanceSpecifierMappingIntegrityViolation results [SWS_DM_01364]. If the port mapping does not reference a DiagnosticDoIPEntityIdentificationInterface, a PortInterfaceMappingViolation is present, whereas a missing process matching triggers a ProcessMappingViolation [SWS_DM_01364]. If the same identifier is used multiple times in the process, a InstanceSpecifierAlreadyInUseViolation follows [SWS_DM_01364].

If Offer() is called when the service is already actively offered, the method returns a ara::core::Result with error code DiagOfferErrc::kAlreadyOffered [SWS_DM_01367]. If Diagnostic Management cannot query the EID—for example, because the interface was not yet offered at the time of the request—a defined protocol fallback applies: Diagnostic Management sends a replacement 6-byte EID value of 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF in DoIP messages [SWS_DM_01528].