klasse ara::diag::FileTransferService

De methode DeleteFile van de klasse ara::diag::FileTransferService (SWS Diagnostics §8.18.1.2.3.1 “DeleteFile”, header #include "ara/diag/file_transfer.h") handelt het volledige verwijderproces van een bestand af in het kader van de UDS-dienst RequestFileTransfer (0x38) met de modus DeleteFile [SWS_DM_01335]. De UDS-dienst wordt aan de serverzijde beschikbaar gesteld conform ISO 14229-1 [SWS_DM_01310] SWS Diagnostics §7.3.2.8.20 “Service 0x38 – RequestFileTransfer”.

Bij de aanroep worden drie parameters doorgegeven [SWS_DM_01335]:

• fileName (ara::core::String): Padvermelding en naam van het doelbestand (interpretatie: ondanks de redactionele aanduiding „file to read” in de specificatietekst betreft het het te verwijderen bestand). Vraag Q-cdbe1185bb030e87 (open)
• metaInfo (MetaInfo const &): Metagegevens van het actuele diagnoseverzoek.
• cancellationHandler (CancellationHandler): Maakt de controle van de annuleringsstatus mogelijk via cancellationHandler.IsCanceled() evenals de registratie van een notificatiefunctie via cancellationHandler.SetNotifier(), voor het geval de lopende conversatie wordt afgebroken.

Als asynchroon resultaat retourneert de functie een ara::core::Future<void> [SWS_DM_01335]. Een succesvolle afronding signaleert aan de diagnose-client een positief responsgedrag. In geval van een fout moet een van toepassing zijnde UDS-NRC conform ISO 14229-1 via DiagUdsNrcErrc in de Future beschikbaar worden gesteld [SWS_DM_01335].

De functie is gespecificeerd als noexcept en geldt als uitzonderingsveilig („exception safe”) [SWS_DM_01335]. De eis aan de thread-safety is voorwaardelijk en wordt gestuurd via de aan de constructor meegegeven ConcurrencyType [SWS_DM_01335].

Gebruik

De methode Offer van de klasse ara::diag::FileTransferService registreert de handler bij Diagnostic Management (DM), zodat deze binnenkomende diagnoseverzoeken voor bestandsoverdracht kan doorsturen naar de instantie [SWS_DM_01336]. De aanroep geschiedt zonder parameters en synchroon. Als retourtype dient ara::core::Result<void>, waardoor het succes van de registratie of een opgetreden fout wordt gesignaleerd [SWS_DM_01336].

Foutafhandeling

Treedt er bij het aanbieden een fout op, dan levert de functie een foutieve ara::core::Result op. Indien de dienst voor de desbetreffende instantie al eerder succesvol is aangeboden, wordt de specifieke foutcode DiagOfferErrc::kAlreadyOffered met rollback-semantiek geretourneerd [SWS_DM_01336].

Gelijktijdigheid en beperkingen

De functie is gedeclareerd als uitzonderingsveilig (exception safe) en noexcept, maar geldt als niet thread-safe (not thread-safe) [SWS_DM_01336]. Aanroepen op dezelfde service-instantie mogen daarom niet onbeschermd vanuit meerdere threads parallel worden uitgevoerd.

Samenspel

Het aanbieden via Offer komt overeen met het gestandaardiseerde aanbiedingspatroon voor diagnose-handlers in Adaptive AUTOSAR. Analoge mechanismen voor het doorsturen van verzoeken door de DM bestaan bijvoorbeeld voor het downloaden van bestanden [SWS_DM_00792], het uploaden [SWS_DM_00802] en algemene UDS-diensten [SWS_DM_00619].

De methode ara::diag::FileTransferService::RequestReadDirectory wordt aangeroepen door de Diagnostic Server-instantie wanneer een diagnoseverzoek voor RequestFileTransfer (0x38) met de modeOfOperation ReadDir (0x05) wordt ontvangen [SWS_DM_01315]. De functie accepteert de volgende parameters [SWS_DM_01332]:

• directoryName: Pad inclusief mapnaam van de uit te lezen map.
• metaInfo: Metagegevens van het binnenkomende diagnoseverzoek.
• cancellationHandler: Object voor het opvragen van een afbreking van het gesprek via cancellationHandler.IsCanceled() of voor het registreren van een callback-functie via cancellationHandler.SetNotifier() voor afbreekgebeurtenissen.

Het retourneren gebeurt asynchroon via een ara::core::Future<std::tuple<DataTransferReadSession, std::uint64_t>> [SWS_DM_01332]. In geval van succes bevat het tupel de toegangsstrategie DataTransferReadSession evenals de mapgrootte die aan de UDS-client wordt overgedragen [SWS_DM_01332]. Het DataTransferReadSession-object brengt daarbij de verbinding tot stand tussen de initialisatie via RequestFileTransfer (0x38) en de daaropvolgende bestandsoverdrachten via TransferData (0x36) SWS Diagnostics p. 184 “Realization of modeOfOperation ReadDir (0x05)”.

Mislukt de verwerking, dan levert de Future een negatieve responscode (NRC) conform ISO 14229-1 via DiagUdsNrcErrc [SWS_DM_01332] op. De methode is gespecificeerd als noexcept en uitzonderingsveilig (exception safe) [SWS_DM_01332]. De thread-safety is voorwaardelijk: of de functie thread-safe moet worden geïmplementeerd, wordt bepaald door de in de constructor meegegeven ConcurrencyType [SWS_DM_01332].

Gebruik

De methode RequestReadFile wordt aangeroepen door de Diagnostic Server-instantie zodra een diagnoseverzoek voor RequestFileTransfer (0x38) met de bewerkingsmodus ReadFile (0x04) binnenkomt [SWS_DM_01314]. De functie accepteert het bestandspad inclusief naam (fileName), het gegevensformaat (dataFormatIdentifier), metagegevens van het verzoek (metaInfo) en een cancellationHandler [SWS_DM_01331]. Via de cancellationHandler kan de annuleringsstatus worden opgevraagd (IsCanceled) of kan een notificatiefunctie voor de annulering van de huidige conversatie worden geregistreerd (SetNotifier) [SWS_DM_01331].

De uitvoering verloopt asynchroon en retourneert een ara::core::Future. In geval van succes levert de future een tupel van DataTransferReadSession en FileSizes [SWS_DM_01331] op. In FileSizes geeft een waarde 0 voor uncompressed_size of compressed_size aan dat de respectieve grootte niet naar de UDS-client wordt verzonden; bij ongecomprimeerde bestanden moet compressed_size op nul worden gezet [SWS_DM_01331].

Foutafhandeling

Mislukt de voorbereiding van het leesproces, dan meldt de applicatie een passende UDS-NRC conform ISO 14229-1 via DiagUdsNrcErrc in de geretourneerde future [SWS_DM_01331].

Gelijktijdigheid en wisselwerking

De functie is gedeclareerd als noexcept. De thread-safety is voorwaardelijk (conditional): of de implementatie thread-safe moet worden ontworpen, hangt af van de ConcurrencyType die aan de constructor is meegegeven [SWS_DM_01331]. Het geretourneerde DataTransferReadSession-object vormt de schakel tussen de verwerking van RequestFileTransfer en de daaropvolgende TransferData-diensten (0x36), waarmee de feitelijke bestandsdatastroom wordt overgedragen SWS Diagnostics p. 184.

De methode RequestResumeWriteFile wordt aangeroepen door een instantie van de Diagnostic Server wanneer een UDS-dienstverzoek voor RequestFileTransfer (0x38) met de bedrijfsmodus ResumeFile (0x06) wordt ontvangen ([SWS_DM_01316], SWS Diagnostics §[SWS_DM_01316] “Realization of modeOfOperation ResumeFile (0x06)”). Het doel ervan is het hervatten van een eerder onderbroken schrijfbewerking voor een bestand.

Bij de aanroep worden het bestandspad (fileName), de UDS-gegevensformaatidentificatie (dataFormatIdentifier), de bestandsgroottes (fileSizes), metagegevens van het verzoek (metaInfo) evenals een cancellationHandler doorgegeven ([SWS_DM_01334], SWS Diagnostics §8.18.1.2.3.5 “RequestResumeWriteFile”). Via de cancellationHandler kan de applicatie middels IsCanceled actief controleren of de lopende diagnoseconversatie is geannuleerd, of via SetNotifier een notificatiefunctie voor een annulering registreren ([SWS_DM_01334]).

Het retourneren gebeurt asynchroon via ara::core::Future<std::tuple<DataTransferWriteSession, std::uint64_t>> ([SWS_DM_01334]). In geval van succes stelt de future een tupel beschikbaar dat een instantie van de DataTransferWriteSession evenals de bytepositie bevat vanaf waar de overdracht moet worden voortgezet ([SWS_DM_01334]). Dit session-object koppelt de initialisatie via RequestFileTransfer aan de daaropvolgende TransferData-diensten (0x36) (SWS Diagnostics §[SWS_DM_01316] “Realization of modeOfOperation ResumeFile (0x06)”).

In geval van een fout moet de future worden beëindigd met een passende UDS-NRC conform ISO 14229-1 via DiagUdsNrcErrc ([SWS_DM_01334]). De functie is gedeclareerd als noexcept en uitzonderingsveilig; de thread-safety is voorwaardelijk („conditional”) en wordt vastgelegd door de in de constructor doorgegeven ConcurrencyType ([SWS_DM_01334]).

Gebruik

De methode [SWS_DM_01333] wordt door de diagnoseserver aangeroepen zodra een UDS-dienstverzoek RequestFileTransfer (0x38) met de bedrijfsmodus WriteFile wordt ontvangen ([SWS_DM_01310]). Wordt het verzoek verzonden met de bedrijfsmodus ReplaceFile (0x03), dan roept de diagnoseserver de interface aan met de schrijfmodus kReplace ([SWS_DM_01313]). De aanroep geeft de bestandsnaam (fileName), de identificatie van het gegevensformaat (dataFormatIdentifier), bestandsgroottes (fileSizes), de vervangingsmodus (mode), aanvullende metagegevens (metaInfo) en een cancellationHandler door. De specificatievermelding „file to read” bij parameter fileName is vermoedelijk een redactionele vergissing en duidt op het doelpad van het te schrijven bestand. Vraag Q-f14158fc20fda8af (open)

De verwerking verloopt asynchroon en retourneert een ara::core::Future<DataTransferWriteSession> ([SWS_DM_01333]). De resulterende sessie dient als schakel tussen de initialisatie via de dienst 0x38 en de daaropvolgende gegevensoverdrachten via TransferData (0x36) (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.20 “Service 0x38 – RequestFileTransfer”).

Foutafhandeling en gelijktijdigheid

De methode is gedeclareerd als noexcept. Treedt er een fout op, dan wordt er geen C++-fout gegenereerd, maar wordt een passende UDS-NRC uit DiagUdsNrcErrc conform ISO 14229-1 in de future geretourneerd ([SWS_DM_01333]). Via de doorgegeven cancellationHandler kan met behulp van IsCanceled() de annuleringsstatus worden opgevraagd of kan met SetNotifier() een notificatie worden geregistreerd voor het geval de diagnoseconversatie wordt afgebroken. De thread-safety is voorwaardelijk: of de functie thread-safe moet worden geïmplementeerd, wordt vastgelegd via de ConcurrencyType in de constructor ([SWS_DM_01333]).

Samenspel

De bewerking vormt een aanvulling op het samenspel van de bestandsoverdrachtsdiensten en is complementair aan leesbewerkingen zoals RequestReadFile ([SWS_DM_01314]) of het hervatten van onderbroken schrijfbewerkingen via RequestResumeWriteFile ([SWS_DM_01316]).

De functie StopOffer van de klasse ara::diag::FileTransferService dient voor het afmelden van de dienst bij Diagnostic Management ([SWS_DM_01337]; AUTOSAR_AP_SWS_Diagnostics §8.18.1.2.3.7 “StopOffer”). De aanroep ervan zorgt ervoor dat de DM vanaf dat moment geen binnenkomende diagnoseverzoeken meer doorstuurt naar deze service-instantie. De interface is gedefinieerd in de header #include "ara/diag/file_transfer.h", heeft de signatuur void StopOffer() const noexcept;, verwacht geen parameters en retourneert geen waarde. De aanroep wordt synchroon uitgevoerd.

Voor StopOffer is geen foutmechanisme voorzien. De methode is gedeclareerd als uitzonderingsveilig (exception safe) en met de aanduiding noexcept ([SWS_DM_01337]). Er worden noch uitzonderingen gegenereerd, noch foutcodes aan de applicatie geretourneerd. Het deactiveren van het doorsturen mislukt vanuit het perspectief van de API niet.

Volgens de specificatie is StopOffer geclassificeerd als niet thread-safe (not thread-safe) ([SWS_DM_01337]). Daarom moet parallelle toegang tot dezelfde instantie van ara::diag::FileTransferService aan de zijde van de applicatie worden beschermd tegen concurrency. Interpretatie: De deactivering zal doorgaans plaatsvinden vóór de vernietiging van het object of tijdens een ordelijke afsluiting van de verwerkende applicatie, zodat er geen verzoeken meer binnenkomen in een routine die niet meer operationeel is. Vraag Q-e7bb2a5621c39160 (open)

Het deactiveren via StopOffer volgt het uniforme architectuurpatroon van AUTOSAR Adaptive voor aangeboden diagnosediensten. Het correspondeert met soortgelijke deactiveringsfuncties van verwante klassen zoals ara::diag::DownloadService ([SWS_DM_00793]), ara::diag::UploadService ([SWS_DM_00803]), ara::diag::CommunicationControl ([SWS_DM_00810]) en ara::diag::Monitor ([SWS_DM_01089]; AUTOSAR_AP_SWS_Diagnostics §7.3.4.1.2 “Monitors”).