klasse ara::diag::SovdSwUpdate

De zuiver virtuele functie DeleteUpdatePackage van de klasse ara::diag::SovdSwUpdate wordt conform [SWS_DM_01803] door de instantie van de Diagnostic Server aangeroepen wanneer de SOVD-methode “Delete Update Package from an SOVD Server” moet worden uitgevoerd ([SWS_DM_01922]). Zij brengt het serverzijde verwijderen van een updatepakket op gang.

De aanroep vindt asynchroon plaats en retourneert een ara::core::Future<void>, die de succesvolle voltooiing aangeeft of een foutobject beschikbaar stelt [SWS_DM_01922]. De signatuur vereist de volgende invoerparameters:

• updatePackageId: duidt als ara::core::String de unieke ID van het te wissen updatepakket aan.
• metaInfo: draagt als MetaInfo const& aanvullende contextinformatie van het verzoek over.
• cancellationHandler: verstuurt een object van het type CancellationHandler, dat erover informeert of de huidige conversatie is afgebroken.

Als tijdens de verwerking een fout optreedt, wordt de Future voorzien van een overeenkomstige SOVD-fout. De specificatie schrijft hiervoor het gebruik van passende foutcodes uit ASAM SOVD 1.1 of ISO 17978-3 voor [SWS_DM_01922].

Met betrekking tot gelijktijdigheid is de methode gedefinieerd als voorwaardelijk thread-safe: of de implementatie thread-safe of non-thread-safe moet worden uitgevoerd, wordt vastgelegd via de in de constructor overgedragen ConcurrencyType [SWS_DM_01922]. Bovendien is de functie gedeclareerd als noexcept en uitzonderingsveilig, waardoor er geen uitzonderingen mogen ontsnappen.

Gebruik

De pure-virtual-methode ExecuteUpdatePackage van de interface ara::diag::SovdSwUpdate dient voor het uitvoeren van de SOVD-methode “Execute Installation of an Update” [SWS_DM_01920]. De declaratie bevindt zich in de header ara/diag/sovd_sw_update.h AUTOSAR_AP_SWS_Diagnostics §8.58.2.1.3.2 “ExecuteUpdatePackage”. Als invoerparameters worden de identificator van het updatepakket (updatePackageId) evenals verzoekgegevens (metaInfo) overgedragen [SWS_DM_01920]. Bovendien informeert het object cancellationHandler erover indien de lopende conversatie is afgebroken [SWS_DM_01920]. De aanroep vindt asynchroon plaats en levert een ara::core::Future<void> op, die een positief resultaat beschikbaar stelt of een SOVD-fout meldt [SWS_DM_01920].

Foutafhandeling

De interface is gespecificeerd als noexcept en uitzonderingsveilig (“exception safe”) [SWS_DM_01920]. Fouten tijdens de uitvoering mogen bijgevolg niet via C++-exceptions worden geworpen, maar moeten asynchroon via de ara::core::Future met toepasselijke foutcodes uit ASAM SOVD 1.1 of ISO 17978-3 worden geretourneerd [SWS_DM_01920].

Gelijktijdigheid en randvoorwaarden

Wat betreft de thread-safety bestaat er een voorwaardelijke vereiste (“conditional”): of de functie thread-safe of niet-thread-safe moet worden geïmplementeerd, wordt bepaald via de parameter ConcurrencyType die aan de constructor is overgedragen [SWS_DM_01920]. De implementatie zou de cancellationHandler moeten evalueren om de pakketinstallatie bij een afbreking van de conversatie ordentelijk te beëindigen [SWS_DM_01920]. Vraag Q-8fe6950e8f5a168c (open)

De elementfunctie ara::diag::SovdSwUpdate::Offer registreert de handler voor SOVD-software-updates bij Diagnostic Management (DM) om het doorsturen van binnenkomende verzoekberichten naar de handler mogelijk te maken [SWS_DM_01924]. De aanroep vindt synchroon en parameterloos plaats via de header ara/diag/sovd_sw_update.h en genereert conform noexcept geen C++-exceptions [SWS_DM_01924].

Het resultaat van de bewerking wordt geretourneerd als ara::core::Result<void> [SWS_DM_01924]. Als de beschikbaarstelling mislukt, levert de functie een fout op met rollback-semantiek [SWS_DM_01924]:

• DiagOfferErrc::kAlreadyOffered: De service is voor deze handler al eerder met succes aangeboden [SWS_DM_01924].
• DiagOfferErrc::kConfigurationMismatch: De monitorconfiguratie komt niet overeen met de DEXT-configuratie [SWS_DM_01924].

Wat betreft de concurrency is de methode gespecificeerd als exception safe, maar uitdrukkelijk als niet thread-safe (not thread-safe) [SWS_DM_01924]. Interpretatie: Bij toegang vanuit meerdere threads zal daarom vermoedelijk een externe, applicatiezijdige synchronisatie vereist zijn. Vraag Q-4636ad27701d59df (open) Het beschikbaarstellingsprincipe via Offer komt overeen met het algemene schema voor diagnose-handlers zoals [SWS_DM_00557] of [SWS_DM_00735], waarbij de DM verzoeken pas kan doorsturen zodra de betreffende interface actief wordt aangeboden [SWS_DM_01525].

De zuiver virtuele methode PrepareUpdatePackage van de interface ara::diag::SovdSwUpdate dient ter voorbereiding van de installatie van een software-updatepakket in het kader van de SOVD-methode “Prepare Installation of an Update” conform [SWS_DM_01919] (AUTOSAR_AP_SWS_Diagnostics §8.58.2.1.3.7 “PrepareUpdatePackage”).

Aanroep en parameters

De functie wordt beschikbaar gesteld via de header ara/diag/sovd_sw_update.h en accepteert de volgende parameters:

• updatePackageId: identificator (ara::core::String) van het voor te bereiden updatepakket.
• metaInfo: metadata (MetaInfo const&) bij het inkomende SOVD-verzoek.
• cancellationHandler: bewakingsobject (CancellationHandler) dat informeert over het afbreken van de huidige conversatie.

De aanroep is gespecificeerd als noexcept en gedraagt zich exception-safe. Het asynchrone resultaat wordt beschikbaar gesteld via een ara::core::Future<void>, die hetzij de succesvolle afronding signaleert hetzij een fout beschikbaar stelt [SWS_DM_01919].

Foutafhandeling en gelijktijdigheid

Als er tijdens de voorbereiding een fout optreedt, moet in de Future een passende foutcode conform ASAM SOVD 1.1 of ISO 17978-3 worden geretourneerd [SWS_DM_01919]. Met betrekking tot de thread-safety geldt een voorwaardelijke vereiste (conditional): of de functie thread-safe moet worden geïmplementeerd, wordt bepaald via de bij de instantiëring in de constructor opgegeven ConcurrencyType [SWS_DM_01919]. Via het object cancellationHandler zou de applicatie langdurige voorbereidingsstappen moeten kunnen afbreken als het verzoek voortijdig wordt beëindigd. Vraag Q-be4c53d9a0427ed5 (open)

Gebruik

De zuiver virtuele methode PutUpdatePackageAutomated wordt aangeroepen in de context van de SOVD-methode “Automated Installation of an Update” [SWS_DM_01918]. Zij is in de header ara/diag/sovd_sw_update.h binnen de klasse ara::diag::SovdSwUpdate gedeclareerd AUTOSAR_AP_SWS_Diagnostics §8.58.2.1.3.8 “PutUpdatePackageAutomated”. De functie dient ertoe om een door zijn identificator gespecificeerd updatepakket geautomatiseerd te installeren.

De interface verwacht de volgende invoerparameters:

• updatePackageId (ara::core::String): identificator van het updatepakket dat aan de geautomatiseerde installatie moet worden overgedragen [SWS_DM_01918].
• metaInfo (MetaInfo const &): meta-informatie van het inkomende serviceverzoek [SWS_DM_01918].
• cancellationHandler (CancellationHandler): informeert de operatie erover of de lopende conversatie is afgebroken [SWS_DM_01918].

De aanroep heeft een asynchrone semantiek. Als retourwaarde dient een ara::core::Future<void>, die na voltooiing hetzij de succesvolle uitvoering aangeeft hetzij een fouttoestand bevat [SWS_DM_01918].

Foutafhandeling en gelijktijdigheid

In het geval van een fout moet via de future een toepasselijke foutcode uit ASAM SOVD 1.1 of ISO 17978-3 worden geretourneerd [SWS_DM_01918]. De methode is gespecificeerd als uitzonderingsveilig (exception safe) en gooit als noexcept-functie geen C++-uitzonderingen op AUTOSAR_AP_SWS_Diagnostics §8.58.2.1.3.8 “PutUpdatePackageAutomated”.

De thread-safety van de methode is voorwaardelijk (conditional): of de implementatie thread-safe of non-thread-safe moet worden uitgevoerd, wordt vastgelegd via de bij de constructoraanroep overgedragen ConcurrencyType [SWS_DM_01918].

De zuiver virtuele functie RequestUpdatePackageRegistration van de klasse ara::diag::SovdSwUpdate bedient de SOVD-methode “Register an Update at the SOVD Server” [SWS_DM_01923]. Zij leidt de registratie van een updatepakket op de server in en initieert de bijbehorende overdrachtsessie AUTOSAR_AP_SWS_Diagnostics §8.58.2.1.3.9 “RequestUpdatePackageRegistration”.

De aanroep vindt asynchroon plaats en levert een ara::core::Future op, die bij succes een tuple bestaande uit een DataTransferWriteSession en een ara::core::String met de updatepakket-ID bevat [SWS_DM_01923]. Bij de aanroep worden de volgende parameters overgedragen:

• metaInfo: meta-informatie van het inkomende verzoek.
• expectedSize: optionele verwachte totale omvang van het pakket (ara::core::Optional<uint64_t>), voor zover in het verzoek gedeclareerd.
• cancellationHandler: signaleert indien de huidige conversatie wordt afgebroken.

De methode is gedefinieerd als noexcept en uitzonderingsveilig [SWS_DM_01923]. Fouten worden bijgevolg niet via C++-exceptions gemeld, maar asynchroon via de future beschikbaar gesteld; hiervoor moeten de overeenkomstige foutcodes uit ASAM SOVD 1.1 respectievelijk ISO 17978-3 worden gebruikt [SWS_DM_01923].

De thread-safety is voorwaardelijk (“conditional”): Of de methode thread-safe moet worden geïmplementeerd, wordt bepaald via de in de constructor opgegeven ConcurrencyType [SWS_DM_01923]. De concrete implementatie zal daarom afhankelijk van de instantiëring vermoedelijk eigen synchronisatiemechanismen vereisen. Vraag Q-7e80e557bdd7627a (open)

Gebruik

De methode ara::diag::SovdSwUpdate::StopOffer beëindigt het aanbieden van de service en deactiveert het doorsturen van binnenkomende verzoekberichten van Diagnostic Management (DM) naar de software-updatecomponent [SWS_DM_01925]. De aanroep vindt plaats via de interface uit ara/diag/sovd_sw_update.h, is parameterloos en levert geen retourwaarde op [SWS_DM_01925]. Het beëindigen van de servicebeschikbaarstelling geschiedt synchroon en komt overeen met de conceptuele deactivering van diagnosefunctionaliteiten in AUTOSAR Adaptive AUTOSAR_AP_SWS_Diagnostics §7.3.4.1.2 “Monitors”.

Foutafhandeling en gelijktijdigheid

De functie heeft de specificatie noexcept en is daarmee uitzonderingsveilig; fouttoestanden via exceptions of foutcodes zijn niet voorzien [SWS_DM_01925]. Voor de aanroepcontext geldt dat de functie gedefinieerd is als niet thread-safe (“not thread-safe”) [SWS_DM_01925]. Parallelle aanroepen op dezelfde instantie moeten applicatiezijdig worden gesynchroniseerd. Interpretatie: Een herhaalde aanroep van StopOffer in reeds inactieve toestand zal vermoedelijk zonder foutgevolgen blijven, aangezien er geen foutafhandeling bestaat. Vraag Q-efaccde5507eb444 (open)

Samenspel

In het totale systeem past de functie binnen het uniforme schema van de DM-servicelifecycle. Zij vormt de functionele tegenhanger van het aanbieden van de service en gedraagt zich analoog aan de deactiveringsbewerkingen van andere diagnoseservices zoals ara::diag::DownloadService [SWS_DM_00793], ara::diag::GenericUDSService [SWS_DM_00620] en ara::diag::EcuResetRequest [SWS_DM_01017].