class ara::diag::DataTransferReadSharedDataHandler

Class ara::diag::DataTransferReadSharedDataHandler serves to handle read diagnostic data transfers for file and directory contents via shared memory ([SWS_DM_01497]). After the session is started, the application implementation provides the entire data as a shared data view via Read() and keeps the allocated buffer available until the release notification by the ReleaseHandler ([SWS_DM_01504]). Prior to destroying the handler-specific object, the transfer session must mandatory be concluded via ExitRead(). The object is exclusively intended for a single transfer session and may therefore be moved, but not copied.

more ›

Context

Class ara::diag::DataTransferReadSharedDataHandler belongs to the diagnostic domain of the AUTOSAR Adaptive Platform in module diag (AUTOSAR_AP_SWS_Diagnostics §8.10.5 “Class: DataTransferReadSharedDataHandler”). Its core task consists in handling data transfers for file and directory contents initiated by UDS requests such as RequestReadFile or RequestReadDirectory ([SWS_DM_01497]). Instead of individual copy steps for each transfer block, this handler allows the application-specific implementation to provide the entire data as a contiguous shared memory region.

In the overall system sequence, three main actors cooperate: the external UDS client sends the read request to the ECU. The diagnostic runtime environment AraDiag receives the request and forwards execution to the concrete implementation of DataTransferReadSharedDataHandler ([SWS_DM_01497], [SWS_DM_01504]). A third partner, the ReleaseHandler, signals to the application as soon as the shared memory resources are no longer required by the platform and may be released ([SWS_DM_01504]).

Context diagram: Interaction between UDS client, AraDiag runtime environment, and the application-side handler implementation. Sources: [SWS_DM_01497], [SWS_DM_01504], [SWS_DM_01505]

Lifecycle

Creation of the handler is performed via the parameterless default constructor ([SWS_DM_01498], AUTOSAR_AP_SWS_Diagnostics §8.10.5.1.1.1 “Default Constructor”). Regarding ownership, the one-way principle applies: handlers must not be copied, as an instance is exclusively bound to a single file transfer session ([SWS_DM_01501], [SWS_DM_01503]). Both the copy constructor (AUTOSAR_AP_SWS_Diagnostics §8.10.5.1.2.1 “DataTransferReadSharedDataHandler”) and the copy assignment operator are therefore marked as delete. A transfer of instances is possible via move operations: move constructor ([SWS_DM_01500], AUTOSAR_AP_SWS_Diagnostics §8.10.5.1.1.2 “Move Constructor”) and move assignment operator ([SWS_DM_01502]) are declared as default and noexcept.

For the destruction of the object, a strict precondition exists: an instance of this class must under no circumstances be destroyed before the transfer session has been formally ended by calling ExitRead() ([SWS_DM_01499], AUTOSAR_AP_SWS_Diagnostics §8.10.5.1.1.3 “Destructor”). Only after completing this termination handling may the virtual destructor execute ([SWS_DM_01499]).

Regarding concurrency, the central methods Read() and ExitRead() are designated as not thread-safe (not thread-safe), while all functions of the interface guarantee exception safety (exception safe) ([SWS_DM_01498], [SWS_DM_01504], [SWS_DM_01505]).

Usage Path

The typical call sequence of a data transfer with shared memory regions comprises several steps:

• Provision of the shared data: AraDiag calls the pure virtual method Read() and passes a ReleaseHandler, MetaInfo, as well as a CancellationHandler ([SWS_DM_01504]). The application allocates the entire file or directory content and returns the shared view thereof as ara::core::Span<ara::core::Byte> via a ara::core::Future to AraDiag ([SWS_DM_01504]).
• Memory reservation and release: The application must strictly keep the allocated memory intact until the ReleaseHandler signals that the memory region can safely be released ([SWS_DM_01504]). For this purpose, the application can register a notifier function on the ReleaseHandler or actively poll its status ([SWS_DM_01504]). Interpretation: The signaling via the ReleaseHandler is presumably performed asynchronously by AraDiag as soon as the data blocks have been successfully transmitted to the UDS client. Question Q-0fbc1c5e667c9a68 (open)
• Session termination: To terminate the transfer, AraDiag calls method ExitRead() ([SWS_DM_01505], AUTOSAR_AP_SWS_Diagnostics §8.10.5.1.3.1 “ExitRead”). In addition to the termination reason (DataTransferExitType), vehicle-manufacturer-specific request parameters are passed, whose lifetime is guaranteed until fulfillment of the result promise ([SWS_DM_01505]). The application returns the response data via a ara::core::Future<ara::core::Vector<ara::core::Byte>> ([SWS_DM_01505]).
• Object destruction: After ExitRead() has been successfully called, the handler instance may be released and destroyed ([SWS_DM_01499]).

Sequence diagram: Step sequence from data provision via Read() to memory release up to termination via ExitRead(). Sources: [SWS_DM_01499], [SWS_DM_01504], [SWS_DM_01505]

Error Scenarios

If errors occur during data provision or transfer termination, they are reported via the respective ara::core::Future with a ara::core::ErrorCode from domain DiagUdsNrcErrc according to ISO 14229-1 ([SWS_DM_01504], [SWS_DM_01505]).

Another scenario is the cancellation of an ongoing diagnostic conversation. Both methods receive a CancellationHandler ([SWS_DM_01504], [SWS_DM_01505]). The application can check the cancellation status synchronously via cancellation_handler.IsCanceled() or configure a notification function via cancellation_handler.SetNotifier() to react immediately to premature cancellation ([SWS_DM_01504], [SWS_DM_01505]).

A violation of the precondition regarding the destructor—if the object is destroyed before ExitRead() was called—contradicts requirement [SWS_DM_01499] and leads to erroneous program states.