class ara::diag::FileTransferService

Method DeleteFile of class ara::diag::FileTransferService (SWS Diagnostics §8.18.1.2.3.1 “DeleteFile”, header #include "ara/diag/file_transfer.h") handles the complete deletion process of a file within the UDS service RequestFileTransfer (0x38) with mode DeleteFile [SWS_DM_01335]. The UDS service is provided on the server side according to ISO 14229-1 [SWS_DM_01310] SWS Diagnostics §7.3.2.8.20 “Service 0x38 – RequestFileTransfer”.

Upon invocation, three parameters are passed [SWS_DM_01335]:

• fileName (ara::core::String): Path specification and name of the destination file (interpretation: despite the editorial specification text "file to read", this is the file to be deleted). Question Q-cdbe1185bb030e87 (open)
• metaInfo (MetaInfo const &): Meta-information of the current diagnostic request.
• cancellationHandler (CancellationHandler): Enables checking the cancellation status via cancellationHandler.IsCanceled() and registering a notification function via cancellationHandler.SetNotifier() in case the ongoing conversation is canceled.

As an asynchronous result, the function returns a ara::core::Future<void> [SWS_DM_01335]. Successful completion signals a positive response behavior to the diagnostic client. In case of error, an applicable UDS NRC according to ISO 14229-1 must be provided via DiagUdsNrcErrc in Future [SWS_DM_01335].

The function is specified as noexcept and is considered exception safe ("exception safe") [SWS_DM_01335]. The requirement for thread safety is conditional and is controlled via the ConcurrencyType passed to the constructor [SWS_DM_01335].

use

Method Offer of class ara::diag::FileTransferService registers the handler with Diagnostic Management (DM) so that it can forward incoming file transfer diagnostic requests to the instance [SWS_DM_01336]. The call is parameterless and synchronous. ara::core::Result<void> serves as the return type, indicating the success of the registration or an error that occurred [SWS_DM_01336].

Error handling

If an error occurs during offering, the function returns an erroneous ara::core::Result. If the service was already successfully offered previously for the respective instance, the specific error code DiagOfferErrc::kAlreadyOffered is returned with rollback semantics [SWS_DM_01336].

Concurrency and Limitations

The function is declared as exception safe (exception safe) and noexcept, but is considered not thread-safe (not thread-safe) [SWS_DM_01336]. Calls on the same service instance must therefore not be executed unprotected in parallel from multiple threads.

Interaction

Offering via Offer complies with the standardized offering pattern for diagnostic handlers in Adaptive AUTOSAR. Analogous mechanisms for forwarding requests by the DM exist, for example, for file download [SWS_DM_00792], upload [SWS_DM_00802], and general UDS services [SWS_DM_00619].

Method ara::diag::FileTransferService::RequestReadDirectory is called by the Diagnostic Server instance when a diagnostic request for RequestFileTransfer (0x38) with modeOfOperation ReadDir (0x05) is received [SWS_DM_01315]. The function accepts the following parameters [SWS_DM_01332]:

• directoryName: Path including directory name of the directory to be read.
• metaInfo: Meta-information of the incoming diagnostic request.
• cancellationHandler: Object for querying a conversation cancellation via cancellationHandler.IsCanceled() or registering a callback function via cancellationHandler.SetNotifier() for cancellation events.

The return is asynchronous via a ara::core::Future<std::tuple<DataTransferReadSession, std::uint64_t>> [SWS_DM_01332]. In case of success, the tuple contains the access strategy DataTransferReadSession as well as the directory size transmitted to the UDS client [SWS_DM_01332]. The DataTransferReadSession object establishes the link between the initialization via RequestFileTransfer (0x38) and the subsequent file transfers via TransferData (0x36) SWS Diagnostics p. 184 “Realization of modeOfOperation ReadDir (0x05)”.

If processing fails, the Future returns a negative response code (NRC) according to ISO 14229-1 via DiagUdsNrcErrc [SWS_DM_01332]. The method is specified as noexcept and exception safe (exception safe) [SWS_DM_01332]. Thread safety is conditional: Whether the function must be implemented thread-safe is determined via the ConcurrencyType passed in the constructor [SWS_DM_01332].

use

Method RequestReadFile is called by the Diagnostic Server instance as soon as a diagnostic request for RequestFileTransfer (0x38) with operation mode ReadFile (0x04) is received [SWS_DM_01314]. The function accepts the file path including name (fileName), the data format (dataFormatIdentifier), request metadata (metaInfo), and a cancellationHandler [SWS_DM_01331]. Via the cancellationHandler, the cancellation status can be queried (IsCanceled) or a notification function for the cancellation of the current conversation can be registered (SetNotifier) [SWS_DM_01331].

Execution is asynchronous and returns a ara::core::Future. In case of success, the future returns a tuple of DataTransferReadSession and FileSizes [SWS_DM_01331]. In FileSizes, a value of 0 for uncompressed_size or compressed_size signals that the respective size is not transmitted to the UDS client; for uncompressed files, compressed_size must be set to zero [SWS_DM_01331].

Error handling

If the preparation of the read operation fails, the application reports an appropriate UDS NRC according to ISO 14229-1 via DiagUdsNrcErrc in the returned future [SWS_DM_01331].

Concurrency and Interaction

The function is declared as noexcept. Thread safety is conditional (conditional): The ConcurrencyType passed to the constructor determines whether the implementation must be designed to be thread-safe [SWS_DM_01331]. The returned DataTransferReadSession object forms the link between the processing of RequestFileTransfer and the subsequent TransferData services (0x36), via which the actual file data stream is transmitted SWS Diagnostics p. 184.

Method RequestResumeWriteFile is called by an instance of the Diagnostic Server when a UDS service request for RequestFileTransfer (0x38) with operating mode ResumeFile (0x06) is received ([SWS_DM_01316], SWS Diagnostics §[SWS_DM_01316] “Realization of modeOfOperation ResumeFile (0x06)”). Its purpose is to resume a previously interrupted write operation for a file.

Upon invocation, the file path (fileName), the UDS data format identifier (dataFormatIdentifier), the file sizes (fileSizes), request metadata (metaInfo), and a cancellationHandler are passed ([SWS_DM_01334], SWS Diagnostics §8.18.1.2.3.5 “RequestResumeWriteFile”). Via the cancellationHandler, the application can actively check using IsCanceled whether the ongoing diagnostic conversation was canceled, or register a notification function for a cancellation via SetNotifier ([SWS_DM_01334]).

The return is asynchronous via ara::core::Future<std::tuple<DataTransferWriteSession, std::uint64_t>> ([SWS_DM_01334]). In case of success, the future provides a tuple containing an instance of DataTransferWriteSession as well as the byte position from which the transfer is to be continued ([SWS_DM_01334]). This session object links the initialization via RequestFileTransfer with the subsequent TransferData services (0x36) (SWS Diagnostics §[SWS_DM_01316] “Realization of modeOfOperation ResumeFile (0x06)”).

In case of error, the future must be completed with an appropriate UDS NRC according to ISO 14229-1 via DiagUdsNrcErrc ([SWS_DM_01334]). The function is declared as noexcept and exception safe; thread safety is conditional ("conditional") and is determined by the ConcurrencyType passed in the constructor ([SWS_DM_01334]).

use

Method [SWS_DM_01333] is called by the diagnostic server as soon as a UDS service request RequestFileTransfer (0x38) with the operating mode WriteFile is received ([SWS_DM_01310]). If the request is transmitted with operating mode ReplaceFile (0x03), the diagnostic server invokes the interface with write mode kReplace ([SWS_DM_01313]). The call passes the file name (fileName), the data format identifier (dataFormatIdentifier), file sizes (fileSizes), the replacement mode (mode), additional metadata (metaInfo), and a cancellationHandler. The specification statement "file to read" for parameter fileName is likely an editorial oversight and designates the destination path of the file to be written. Question Q-f14158fc20fda8af (open)

Processing is asynchronous and returns a ara::core::Future<DataTransferWriteSession> ([SWS_DM_01333]). The resulting session serves as a link between the initialization via service 0x38 and the subsequent data transfers via TransferData (0x36) (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.20 “Service 0x38 – RequestFileTransfer”).

Error Handling and Concurrency

The method is declared as noexcept. If an error occurs, no C++ error is thrown, but an appropriate UDS NRC from DiagUdsNrcErrc according to ISO 14229-1 is returned in the future ([SWS_DM_01333]). Via the passed cancellationHandler, the cancellation status can be queried using IsCanceled() or a notification can be registered using SetNotifier() in case the diagnostic conversation terminates. Thread safety is conditional: Whether the function must be implemented thread-safe is determined via the ConcurrencyType in the constructor ([SWS_DM_01333]).

Interaction

The operation complements the interaction of the file transfer services and is complementary to read operations such as RequestReadFile ([SWS_DM_01314]) or the resumption of interrupted write operations via RequestResumeWriteFile ([SWS_DM_01316]).

Function StopOffer of class ara::diag::FileTransferService is used to unregister the service from Diagnostic Management ([SWS_DM_01337]; AUTOSAR_AP_SWS_Diagnostics §8.18.1.2.3.7 “StopOffer”). Its call causes the DM from that point on to no longer forward incoming diagnostic requests to this service instance. The interface is defined in header #include "ara/diag/file_transfer.h", has the signature void StopOffer() const noexcept;, expects no parameters, and returns no return value. The call is executed synchronously.

No error mechanism is provided for StopOffer. The method is declared as exception safe (exception safe) and with the specifier noexcept ([SWS_DM_01337]). Neither are exceptions thrown nor error codes returned to the application. Disabling forwarding does not fail from the API's perspective.

According to the specification, StopOffer is classified as not thread-safe (not thread-safe) ([SWS_DM_01337]). Therefore, concurrent accesses to the same instance of ara::diag::FileTransferService must be protected against concurrency on the application side. Interpretation: Disabling is typically likely to occur before destroying the object or during an orderly shutdown of the processing application, so that no requests run into a routine that is no longer operational. Question Q-e7bb2a5621c39160 (open)

Disabling via StopOffer follows the uniform architectural pattern of AUTOSAR Adaptive for provided diagnostic services. It corresponds to identical disabling functions of related classes such as ara::diag::DownloadService ([SWS_DM_00793]), ara::diag::UploadService ([SWS_DM_00803]), ara::diag::CommunicationControl ([SWS_DM_00810]), and ara::diag::Monitor ([SWS_DM_01089]; AUTOSAR_AP_SWS_Diagnostics §7.3.4.1.2 “Monitors”).