class ara::diag::DataTransferWriteHandler

Class ara::diag::DataTransferWriteHandler serves in AUTOSAR Adaptive for application-side processing of write file transfers initiated by RequestWriteFile in modes AddFile, ResumeFile, or ReplaceFile [SWS_DM_01539]. Incoming data packets are written asynchronously into memory via Write() and the session is subsequently terminated using ExitWrite(). An instance is strictly bound to a single transfer session and must under no circumstances be destroyed before ExitWrite() is called [SWS_DM_01541].

more ›

Context

In the AUTOSAR Adaptive Platform, the abstract base class ara::diag::DataTransferWriteHandler defines the interface for write file transfers [SWS_DM_01539] (AUTOSAR_AP_SWS_Diagnostics §8.10.6 “Class: DataTransferWriteHandler”). It serves for the application-side processing of data transfers initiated in the context of RequestWriteFile via operating modes AddFile, ResumeFile, or ReplaceFile.

Within the diagnostic architecture, the handler interacts with the external UDS client, the diagnostic middleware, and the application. The client transmits segmented data blocks that are received by a derived implementation of the handler and stored in application memory [SWS_DM_01546]. Presumably, the platform's Diagnostic Management handles the UDS protocol coordination and forwards the payload to the target application via the handler interface. Question Q-484dc9dd80e56af4 (open)

Lifecycle

Instantiation of ara::diag::DataTransferWriteHandler is performed exclusively by specialized subclasses of the application: the parameterless constructor is defined with protected and noexcept=default [SWS_DM_01540], which prevents direct instantiation of the base class. A handler instance is strictly bound to a single file transfer session ("one way usage i.e. per single file transfer session"). For this reason, copy constructor [SWS_DM_01544] (AUTOSAR_AP_SWS_Diagnostics §8.10.6.1.2.1 “DataTransferWriteHandler”) and copy assignment operator [SWS_DM_01545] are deleted (=delete).

Move operations, however, are permissible: both the move constructor [SWS_DM_01542] (AUTOSAR_AP_SWS_Diagnostics §8.10.6.1.1.1 “Move Constructor”) and the move assignment operator [SWS_DM_01543] are implemented with noexcept=default and are considered exception-safe (exception safe).

For tearing down the instance, a binding precondition applies: an instance of this class must under no circumstances be destroyed before method ExitWrite() was called [SWS_DM_01541] (AUTOSAR_AP_SWS_Diagnostics §8.10.6.1.1.2 “Destructor”). Only after ExitWrite() has been fully executed may the virtual destructor ~DataTransferWriteHandler() be called. The member functions and the destructor are specified as not thread-safe (not thread-safe) [SWS_DM_01541], [SWS_DM_01546], [SWS_DM_01547].

State diagram: Lifecycle and call sequence of a DataTransferWriteHandler instance. Sources: [SWS_DM_01541], [SWS_DM_01544].

Usage Path

The regular sequence of a write transfer comprises the step-by-step receipt of data blocks and the subsequent termination of the session:

• For each incoming data segment, the diagnostic system calls the pure virtual method Write() [SWS_DM_01546] (AUTOSAR_AP_SWS_Diagnostics §8.10.6.1.3.2 “Write”). The data is passed as ara::core::Span<ara::core::Byte>. The validity of this memory area persists until the associated Promise is fulfilled or the operation is cancelled. The application appends the data to the internal buffer and returns a ara::core::Future<void>.
• After all segments have been transferred, the platform calls the pure virtual method ExitWrite() [SWS_DM_01547] (AUTOSAR_AP_SWS_Diagnostics §8.10.6.1.3.1 “ExitWrite”). Passed are the termination reason (DataTransferExitType), vehicle-manufacturer-specific parameters (transferRequestParameterRecord), metaInfo, and a CancellationHandler.
• Method ExitWrite() returns a ara::core::Future<ara::core::Vector<ara::core::Byte>>. Upon successful completion, the data contained therein is inserted as transferResponseParameterRecord after the service ID into the positive UDS response message [SWS_DM_01547].

Sequence diagram: Call sequence of Write and ExitWrite operations during a transfer session. Sources: [SWS_DM_01546], [SWS_DM_01547].

Error Scenarios

Errors during data processing and transfer are managed via standardized return values and cancellation mechanisms:

• If writing a data block or terminating the transfer fails, the respective Future is provided with a ara::core::ErrorCode from DiagUdsNrcErrc [SWS_DM_01546], [SWS_DM_01547]. This leads to the generation of a corresponding negative UDS response (NRC according to ISO 14229-1) to the client.
• Both methods provide a CancellationHandler. The application can check via cancellationHandler.IsCanceled() whether the conversation was cancelled, or register a notification function using cancellationHandler.SetNotifier() that is executed upon cancellation of the conversation [SWS_DM_01546], [SWS_DM_01547].
• If the instance is destroyed before calling ExitWrite(), this constitutes a violation of the specified lifecycle rule [SWS_DM_01541], which presumably leads to an undefined system state and incomplete files. Question Q-cc032c11ac89a5b1 (open) In addition, unprotected concurrent access leads to data inconsistencies, as the interface is explicitly not thread-safe.