struct ara::diag::DoIPEntityIdentification::EntityId

The structure ara::diag::DoIPEntityIdentification::EntityId serves as a data container for the six-byte entity identification (EID) of a DoIP instance according to ISO 13400-2 ([SWS_DM_01496]). When configured accordingly, the Diagnostic Manager retrieves this identifier from the adaptive application via the method ara::diag::DoIPEntityIdentification::GetEntityId to embed it in DoIP protocol messages such as the vehicle announcement message ([SWS_DM_01361]). Should the interface not yet be available or the retrieval fail, a mandatory constraint is a fallback to the fixed replacement value consisting entirely of bytes with the value 0xFF ([SWS_DM_01528]).

more ›

Context

The data structure ara::diag::DoIPEntityIdentification::EntityId serves to represent the standardized entity identification (EID) for diagnostic communication over Internet Protocol (DoIP) according to ISO 13400-2 ([SWS_DM_01496], AUTOSAR_AP_SWS_Diagnostics §8.33 “Header: ara/diag/doip_entity_identification.h”). Within the AUTOSAR Adaptive Platform, it is defined as a public struct type within the API class ara::diag::DoIPEntityIdentification ([SWS_DM_01362], [SWS_DM_01496]).

Its primary responsibility consists of encapsulating the exactly six-byte identification value of a DoIP entity ([SWS_DM_01496]). In the platform architecture, three main actors interact: First, the adaptive application, which manages the entity identification or reads it from hardware. Second, the interface class ara::diag::DoIPEntityIdentification, which provides the method for providing the identifier ([SWS_DM_01362]). Third, the Diagnostic Manager (DM), which retrieves the EID in the context of vehicle identification for outgoing DoIP messages ([SWS_DM_01361], AUTOSAR_AP_SWS_Diagnostics §8.33 “Providing EID in DoIP protocol messages using Application Interface”).

Context diagram: Integration of EntityId between Diagnostic Manager, interface class, and adaptive application. Sources: [SWS_DM_01361], [SWS_DM_01496].

Lifecycle

As a data structure with the single member entityIdentification of type ara::core::Array<std::uint8_t, 6>, EntityId exhibits the properties of a lightweight C++ value object ([SWS_DM_01496]). Interpretation: Due to the lack of dynamic resource allocation, the structure is likely to support regular copy and move operations by default and not be subject to complex internal state transitions. Question Q-4a6f7d6e7368b436 (open)

Instantiation of EntityId is performed by the adaptive application as soon as the Diagnostic Manager queries the identity data via calling ara::diag::DoIPEntityIdentification::GetEntityId ([SWS_DM_01361]). The lifetime of an instance is typically bound to the return and processing cycle of the method call. While the enclosing service class ara::diag::DoIPEntityIdentification possesses explicit constructors ([SWS_DM_01364], AUTOSAR_AP_SWS_Diagnostics §8.33.1.1.2.1 “DoIPEntityIdentification”) and destructors ([SWS_DM_01365], AUTOSAR_AP_SWS_Diagnostics §8.33.1.1.1.1 “Destructor”), the value object EntityId is automatically deallocated upon leaving the scope after the Diagnostic Manager reads the field data.

Usage Path

The regular usage of EntityId follows a defined sequence in the diagnostic protocol flow:

• Configuration check: The Diagnostic Manager checks the attribute DoIpNetworkConfiguration.eidRetrieval. If DoIpEidRetrievalEnum.eidUseApi is stored there, the DM must mandatorily retrieve the identifier via the API ([SWS_DM_01361]).
• Retrieval via API: The Diagnostic Manager calls the method ara::diag::DoIPEntityIdentification::GetEntityId ([SWS_DM_01361]).
• Data provision: The application creates an instance of EntityId, populates the member entityIdentification with the 6-byte identifier according to ISO 13400-2 ([SWS_DM_01496]), and passes the structure.
• Protocol usage: The Diagnostic Manager extracts the identifier and inserts it into DoIP messages such as the vehicle announcement message ([SWS_DM_01361], AUTOSAR_AP_SWS_Diagnostics §8.33 “Providing EID in DoIP protocol messages using Application Interface”).

Sequence diagram: Flow during retrieval and further processing of EntityId including error fallback. Sources: [SWS_DM_01361], [SWS_DM_01496], [SWS_DM_01528].

Error Scenarios

A central error scenario arises when the interface ara::diag::DoIPEntityIdentification is not yet offered by the adaptive application at the required query time or retrieval via GetEntityId fails ([SWS_DM_01528], AUTOSAR_AP_SWS_Diagnostics §8.33 “Providing EID in DoIP protocol messages using Application Interface”).

In order not to permanently block sending DoIP messages, the specification mandates fallback value behavior in this case: The Diagnostic Manager must transmit a 6-byte EID field with the fixed value 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF instead of the regular application data ([SWS_DM_01528]). At the type level, the fixed array ara::core::Array<std::uint8_t, 6> precludes length errors and buffer overflows at compile time ([SWS_DM_01496]).