class ara::diag::DataTransferReadByPullHandler

Class ara::diag::DataTransferReadByPullHandler serves to provide file or directory data that is actively retrieved from the application by diagnostic layer AraDiag as part of a UDS read operation ([SWS_DM_01506]). The sequence comprises step-by-step data retrieval via Read() up to the final session termination via ExitRead(). As a strict lifecycle condition, a handler instance that is associated with exactly one single transfer session must under no circumstances be destroyed before ExitRead() is called ([SWS_DM_01510]).

more ›

Context

Class ara::diag::DataTransferReadByPullHandler ([SWS_DM_01506], AUTOSAR_AP_SWS_Diagnostics §8.10.2 “Class: DataTransferReadByPullHandler”) handles data transfers initiated by diagnostic requests to read files or directories (such as RequestReadFile or RequestReadDirectory). The architecture is based on a pull method in which diagnostic layer AraDiag actively queries ("pulls") the data to be transferred from the implementation.

Three components participate in the interaction: the external UDS client (diagnostic tester), the diagnostic subsystem AraDiag, and the application-specific handler implementation. The external client sends read requests, whereupon AraDiag calls the methods of the handler to provide data chunks step-by-step and transmit them to the UDS client ([SWS_DM_01513]).

Lifecycle

The lifecycle of a handler instance is exclusively bound to a single file transfer session. The default constructor is declared protected ([SWS_DM_01507]). Interpretation: The concrete application would therefore be expected to implement and instantiate a derived subclass. Question Q-cb78bc4a1d40968b (open)

Copy operations are completely disabled: the copy constructor ([SWS_DM_01509]) and the copy assignment operator ([SWS_DM_01512]) are specified as deleted (=delete), since handlers are intended for one-way use within a session ("only one way usage i.e. per single file transfer session"). Move operations (move constructor and move assignment), on the other hand, are defined as default implementations and declared as noexcept ([SWS_DM_01508], [SWS_DM_01511], AUTOSAR_AP_SWS_Diagnostics §8.10.2.1.1.1 “Move Constructor”).

A strict precondition applies to release: an instance of the class must under no circumstances be destroyed before method ExitRead() has been called ([SWS_DM_01510], AUTOSAR_AP_SWS_Diagnostics §8.10.2.1.1.2 “Destructor”). Regarding concurrency, the interface methods Read() and ExitRead() are defined as not thread-safe ("not thread-safe"), but exception-safe (noexcept) ([SWS_DM_01513], [SWS_DM_01514]).

Usage Path

The regular sequence of data retrieval is divided into the following steps:

1. Initialization: The application instantiates the derived handler class for the upcoming transfer session.
2. Data retrieval: To provide the data blocks, AraDiag calls method Read() ([SWS_DM_01513], AUTOSAR_AP_SWS_Diagnostics §8.10.2.1.3.2 “Read”). The application receives a memory view response_data (of type ara::core::Span<const ara::core::Byte>) of a buffer preallocated by AraDiag, fills it with the next file contents, and completes the ara::core::Future<std::uint32_t> with the number of bytes written. AraDiag inserts this data after the block sequence counter (blockSequenceCounter) as transferResponseParameterRecord into the positive UDS response ([SWS_DM_01513]). This step is repeated for subsequent chunks.
3. Session termination: For the regular termination of the transfer, AraDiag calls ExitRead() ([SWS_DM_01514], AUTOSAR_AP_SWS_Diagnostics §8.10.2.1.3.1 “ExitRead”). The termination reason exit_type, vendor-specific parameters (transfer_request_parameter_record), meta_info, and a cancellation_handler are passed. The implementation acknowledges this via a ara::core::Future<ara::core::Vector<ara::core::Byte>>, whose return values are transmitted after the SID in the positive response ([SWS_DM_01514]).
4. Release: Only after ExitRead() has been called may the handler object be destroyed ([SWS_DM_01510]).

Sequence diagram: Typical sequence of data retrieval via pull method using AraDiag. Sources: [SWS_DM_01513], [SWS_DM_01514]

Error Scenarios

If errors occur during data preparation or termination, the application reports this via the returned Future by providing it with a UDS error code (DiagUdsNrcErrc according to ISO 14229-1) ([SWS_DM_01513], [SWS_DM_01514]). AraDiag then generates the corresponding negative UDS response (NRC) to the tester.

For premature cancellation, a CancellationHandler is passed to both methods ([SWS_DM_01513], [SWS_DM_01514]). The application can check via cancellation_handler.IsCanceled() whether the conversation was cancelled, or register a callback function via cancellation_handler.SetNotifier(). The provided buffers (response_data and transfer_request_parameter_record) remain valid until the promise is fulfilled or cancellation occurs via the handler.

If the instance is destroyed before ExitRead() is called, this constitutes a violation of the specification requirement ([SWS_DM_01510]), which can lead to incomplete transfer sessions and undefined system states.