klasse ara::per::FileStorage

De synchrone methode DeleteFile van de klasse ara::per::FileStorage verwijdert een bestand aan de hand van zijn naam (fileName) uit de bestandsopslag [SWS_PER_00111]. De identifier kan overeenkomen met de geconfigureerde PersistencyFile.fileName [SWS_PER_00111]. De aanroep is gespecificeerd als noexcept, geldt als exceptieveilig en thread-safe en meldt het resultaat terug via ara::core::Result<void> [SWS_PER_00111].

Voorafgaand aan de aanroep moeten alle actieve toegangen tot het doelbestand zijn beëindigd. Als het bestand momenteel geopend is, mislukt de verwijderingsoperatie met de fout PerErrc::kResourceBusy [SWS_PER_00111]. Applicaties moeten er daarom voor zorgen dat eerder via OpenFileReadWrite [SWS_PER_00113], OpenFileReadOnly [SWS_PER_00114] of OpenFileWriteOnly [SWS_PER_00115] aangemaakte UniqueHandle-instanties hun geldigheidsbereik hebben verlaten, waardoor het bestand wordt gesloten. Evenzo leidt een parallel lopende uitvoering van RecoverFile [SWS_PER_00337] of ResetFile [SWS_PER_00338] voor dezelfde bestandsnaam tot PerErrc::kResourceBusy [SWS_PER_00111].

In het geval van een fout biedt het geretourneerde Result-type specifieke foutoorzaken [SWS_PER_00111]:

• PerErrc::kFileNotFound: Het aangegeven bestand bestaat niet in de bestandsopslag [SWS_PER_00111].
• PerErrc::kIllegalWriteAccess: De File Storage is geconfigureerd als alleen-lezen [SWS_PER_00111].
• PerErrc::kPhysicalStorageFailure: De toegang tot het fysieke opslagmedium mislukt (zonder rollback-semantiek) [SWS_PER_00111].
• PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed: Fout bij structurele integriteit, ver-/ontsleuteling of MAC-verificatie (telkens met rollback-semantiek) evenals fabrikantspecifieke fouten [SWS_PER_00111].

De synchrone methode FileExists van de klasse ara::per::FileStorage controleert of een bestand aanwezig is in de betreffende bestandsopslag [SWS_PER_00112]. De functie is gedeclareerd als noexcept en werpt geen C++-excepties [SWS_PER_00112].

Gebruik

Als parameter wordt fileName als ara::core::StringView doorgegeven, wat kan overeenkomen met de identifier PersistencyFile.fileName van een geconfigureerd bestand [SWS_PER_00112]. De retourwaarde ara::core::Result<bool> levert true op als het bestand kon worden gelokaliseerd, en anders false [SWS_PER_00112].

Foutafhandeling

Mislukt de controle, dan bevat de geretourneerde Result geen waarheidswaarde, maar een foutcode [SWS_PER_00112]. Gespecificeerde foutoorzaken zijn:

• PerErrc::kPhysicalStorageFailure bij het mislukken van de fysieke opslagtoegang [SWS_PER_00112],
• PerErrc::kIntegrityCorrupted bij beschadigde structurele integriteit van de gegevens [SWS_PER_00112],
• PerErrc::kValidationFailed wanneer de geldigheid van opgeslagen gegevens niet kan worden gewaarborgd [SWS_PER_00112],
• PerErrc::kEncryptionFailed bij mislukte ontsleuteling [SWS_PER_00112],
• PerErrc::kAuthenticationFailed bij mislukte MAC-controle [SWS_PER_00112] evenals mogelijke fabrikantspecifieke fouten [SWS_PER_00112].

Gelijktijdigheid en beperkingen

De methode is gedeclareerd als thread-veilig [SWS_PER_00112]. Het geleverde controleresultaat is echter alleen exact zolang er niet gelijktijdig bestanden in de opslag worden toegevoegd of verwijderd; verwijdert bijvoorbeeld een andere thread een bestand direct na de teruggave van true, dan is het resultaat reeds niet meer geldig [SWS_PER_00112].

De methode OpenFileReadOnly van de klasse ara::per::FileStorage (gedeclareerd in #include "ara/per/file_storage.h") opent een gepersisteerd bestand alleen-lezen met een gespecificeerde toegangsmodus [SWS_PER_00114]. Tenzij via de parameter mode anders is aangegeven, wordt de leeswijzerpositie standaard op het begin van het bestand (kAtTheBeginning) geplaatst [SWS_PER_00114]. De uitvoering vindt synchroon plaats en retourneert een ara::core::Result<UniqueHandle<ReadAccessor>>. De handle gebruikt RAII-semantiek: Zodra de instantie van UniqueHandle haar geldigheidsbereik verlaat, wordt het bestand automatisch gesloten [SWS_PER_00114].

Wat betreft de gelijktijdigheid is de methode als thread-safe en exception safe (met noexcept) gespecificeerd [SWS_PER_00114]. Desondanks bestaan er functionele aanroepbeperkingen: Is het doelbestand al geopend of worden gelijktijdig bewerkingen zoals DeleteFile, RecoverFile of ResetFile met dezelfde bestandsnaam uitgevoerd, dan mislukt de aanroep met PerErrc::kResourceBusy [SWS_PER_00114].

In het geval van een fout levert het ara::core::Result fabrikantspecifieke fouten of gestandaardiseerde foutcodes uit PerErrc resp. StorageFailure terug [SWS_PER_00114]:

• PerErrc::kFileNotFound: Het aangegeven bestand bestaat niet in de bestandsopslag [SWS_PER_00114].
• PerErrc::kInvalidOpenMode: De meegegeven modus bevat een ongeldige combinatie van vlaggen [SWS_PER_00114].
• StorageFailure: De toegang tot het fysieke geheugen is mislukt [SWS_PER_00114].
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kAuthenticationFailed of PerErrc::kEncryptionFailed: Structurele integriteit beschadigd, validatie ontoereikend, MAC-verificatie foutief of ontsleuteling mislukt [SWS_PER_00114].

In samenspel met andere interfaces biedt FileStorage twee verwante overbelastingen: Een variant zonder modusparameter, die altijd aan het begin van het bestand opent [SWS_PER_00376], evenals een overbelasting met buffer (ara::core::Span<ara::core::Byte> buffer), waarmee de ReadAccessor bloksgewijs lezen implementeert om veel kleine toegangen te versnellen [SWS_PER_00430].

Gebruik

De methode OpenFileReadOnly van de klasse ara::per::FileStorage opent een gepersisteerd bestand als alleen-lezen om te lezen [SWS_PER_00376]. De aanroep geschiedt via het headerbestand ara/per/file_storage.h onder doorgifte van de bestandsnaam fileName. De leespositie wordt daarbij initieel op het begin van het bestand geplaatst. Als retourwaarde dient een ara::core::Result, die bij succes een UniqueHandle<ReadAccessor> verschaft. Het geopende bestand wordt automatisch gesloten zodra deze handle zijn geldigheidsbereik verlaat.

Foutafhandeling

Mislukt de uitvoering, dan bevat het resultaat een foutcode of een fabrikantspecifieke fout [SWS_PER_00376]:

• PerErrc::kFileNotFound: Het opgegeven bestand bestaat niet in de opslag.
• PerErrc::kResourceBusy: Het bestand is al geopend of wordt gelijktijdig verwerkt door DeleteFile, RecoverFile of ResetFile.
• PerErrc::kPhysicalStorageFailure: De toegang tot het fysieke opslagmedium is mislukt.
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed: Fout bij structuurintegriteit, datavalidatie, ontsleuteling of MAC-controle.

Gelijktijdigheid en wisselwerking

De methode is gespecificeerd als thread-safe, exception safe en noexcept [SWS_PER_00376]. Voor uitgebreide vereisten staan er overbelastingen ter beschikking: een variant voor de expliciete opgave van een OpenMode [SWS_PER_00114] evenals een signatuur met een extra gebruikersbuffer voor de bloksgewijze versnelling van kleinere leestoegangen [SWS_PER_00430].

De synchrone methode OpenFileReadOnly van de klasse ara::per::FileStorage opent een gepersisteerd bestand voor leestoegang met gebruikmaking van een door de aanroeper ter beschikking gestelde buffer [SWS_PER_00430]. Aan de hand van de parameters fileName, mode en buffer (als ara::core::Span<ara::core::Byte>) wordt de bestandstoegang geïnitialiseerd [SWS_PER_00430]. Voor zover via mode niets anders wordt aangegeven, staat de leespositie standaard aan het begin van het bestand (kAtTheBeginning) [SWS_PER_00430]. Het meegegeven geheugengebied wordt door de resulterende ReadAccessor gebruikt om via bloksgewijs inlezen herhaalde kleine leestoegangen te versnellen [SWS_PER_00430]. De resource is beschermd via RAII: zodra de geretourneerde UniqueHandle het geldigheidsbereik verlaat, wordt het bestand automatisch gesloten [SWS_PER_00430].

Wat betreft gelijktijdigheid is de functie gespecificeerd als thread-safe (thread-safe), exceptieveilig (exception safe) en noexcept [SWS_PER_00430]. Treedt er een fout op, dan levert de ara::core::Result fabrikantspecifieke fouten of gestandaardiseerde foutcodes uit PerErrc op [SWS_PER_00430]:

• PerErrc::kResourceBusy: Het bestand is al geopend of wordt gelijktijdig verwerkt door DeleteFile, RecoverFile resp. ResetFile [SWS_PER_00430].
• PerErrc::kFileNotFound: Het aangegeven bestand bestaat niet in de bestandsopslag [SWS_PER_00430].
• PerErrc::kInvalidOpenMode: De meegegeven modus bevat een ongeldige combinatie van opties [SWS_PER_00430].
• Integriteits- en beveiligingsfouten: PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed (mislukken van de MAC-controle) evenals StorageFailure bij fysieke opslagtoegangsfouten [SWS_PER_00430].

Naast deze gebufferde variant staan voor use cases zonder door de gebruiker gedefinieerde buffer de overbelastingen [SWS_PER_00114] (met mode) en [SWS_PER_00376] (alleen met fileName) ter beschikking.

Gebruik

De synchrone methode OpenFileReadWrite van de klasse ara::per::FileStorage opent een bestand voor lees- en schrijftoegang in de opgegeven modus mode [SWS_PER_00113]. Indien in de modus niet anders gespecificeerd, wordt de bestandspointer standaard aan het begin geplaatst (kAtTheBeginning). Als het bestand nog niet bestaat, wordt het automatisch aangemaakt [SWS_PER_00113]. De functie retourneert een ara::core::Result met een UniqueHandle<ReadWriteAccessor>, die het bestand automatisch sluit zodra de handle zijn geldigheidsbereik verlaat [SWS_PER_00113].

Gelijktijdigheid en beperkingen

De aanroep is thread-veilig (thread-safe) en genereert geen excepties (noexcept) [SWS_PER_00113]. Het bestand mag bij de aanroep niet reeds geopend zijn. Bovendien mag er geen gelijktijdige uitvoering van DeleteFile, RecoverFile of ResetFile met dezelfde bestandsnaam plaatsvinden, omdat de aanroep anders mislukt met PerErrc::kResourceBusy [SWS_PER_00113].

Foutafhandeling

In geval van een fout bevat het ara::core::Result specifieke foutcodes [SWS_PER_00113]:

• PerErrc::kInvalidOpenMode: Ongeldige combinatie van vlaggen in de doorgegeven mode.
• PerErrc::kResourceBusy: Het doelbestand is reeds geopend of is bezet door administratieve bestandsbewerkingen.
• Access: De storage is geconfigureerd als read-only of als write-only-once bij een reeds bestaande sleutel.
• PerErrc::kOutOfStorageSpace respectievelijk PerErrc::kTooManyFiles: Onvoldoende fysieke opslagruimte of overschrijding van maxNumberOfFiles bij nieuwe aanmaak.
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed: Hardwaretoegangsfouten, gecorrumpeerde datastructuren of mislukte cryptografische validaties.

Samenspel

Als vereenvoudigde variant is een overbelasting zonder modusparameter beschikbaar, die bestanden standaard aan het begin opent [SWS_PER_00375]. Voor prestatieoptimalisatie bij talrijke kleine benaderingen bestaat er voorts een overbelasting met door de gebruiker gedefinieerde buffer (buffer) voor bloksgewijs lezen en schrijven [SWS_PER_00429].

De synchrone memberfunctie OpenFileReadWrite van de klasse ara::per::FileStorage dient voor het openen van een bestand voor gecombineerde lees- en schrijftoegang [SWS_PER_00375]. Als parameter wordt de bestandsnaam fileName als ara::core::StringView doorgegeven, die kan overeenkomen met de modellering PersistencyFile.fileName van een geconfigureerd bestand [SWS_PER_00375]. Als het opgegeven bestand nog niet bestaat, wordt het automatisch nieuw aangemaakt [SWS_PER_00375]. Bij het openen wordt de bestandspositie direct aan het begin geplaatst (overeenkomstig kAtTheBeginning) [SWS_PER_00375]. De aanroeper ontvangt een ara::core::Result<UniqueHandle<ReadWriteAccessor>>; het bestand wordt automatisch gesloten zodra de geretourneerde UniqueHandle buiten zijn geldigheidsbereik raakt [SWS_PER_00375].

Wat betreft concurrency en uitvoeringscontext is de functie gespecificeerd als thread-safe en exception safe [SWS_PER_00375]. Er moet echter rekening mee worden gehouden dat gelijktijdige toegangen gereglementeerd zijn: als het bestand al geopend is of er gelijktijdig een operatie zoals DeleteFile, RecoverFile of ResetFile op dezelfde bestandsnaam wordt uitgevoerd, mislukt de aanroep en levert deze de foutcode PerErrc::kResourceBusy [SWS_PER_00375] op.

In geval van een fout kapselt het geretourneerde Result-object specifieke persistentiefouten of fabrikantspecifieke fouten in [SWS_PER_00375]:

• Configuratie- en toegangsfouten zoals Access bij schrijfbeveiligde opslag of reeds bestaande gegevens bij write-once-configuratie [SWS_PER_00375].
• Opslagruimtelimieten door PerErrc::kOutOfStorageSpace of PerErrc::kTooManyFiles bij overschrijding van de geconfigureerde bestandsbovengrens [SWS_PER_00375].
• Integriteits- en beveiligingsfouten zoals PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed [SWS_PER_00375].

In samenhang met andere interfaces van FileStorage biedt AUTOSAR alternatieve overloads: OpenFileReadWrite kan met expliciete OpenMode worden aangeroepen [SWS_PER_00113] of met extra geheugenbereik aan gebruikerszijde buffer (ara::core::Span<ara::core::Byte>), wat bloksgewijs bufferen mogelijk maakt om herhaalde kleine toegangen te versnellen [SWS_PER_00429].

Gebruik

De methode OpenFileReadWrite van de klasse ara::per::FileStorage opent een bestand synchroon voor gecombineerd lezen en schrijven onder het ter beschikking stellen van een door de gebruiker gedefinieerde buffer [SWS_PER_00429]. Het doorgegeven geheugengebied buffer (als ara::core::Span<ara::core::Byte>) wordt intern gebruikt door de ReadWriteAccessor voor bloksgewijze lees- en schrijfoperaties om reeksen van kleine toegangen performant af te handelen. Als het opgegeven bestand nog niet bestaat, wordt het automatisch nieuw aangemaakt; de bestandspositie bevindt zich standaard aan het begin (kAtTheBeginning), tenzij anders aangegeven in de meegegeven mode [SWS_PER_00429]. Het bestand wordt gesloten zodra de in ara::core::Result geretourneerde UniqueHandle zijn geldigheidsbereik verlaat. Interpretatie: Het onderliggende geheugen van de meegegeven buffer-span moet vermoedelijk gedurende de gehele levensduur van de UniqueHandle geldig blijven, aangezien de accessor hiernaar refereert voor bloktoegangen. Vraag Q-e0009b7de17e3597 (open)

Foutafhandeling en gelijktijdigheid

De functie is gespecificeerd als noexcept, exceptieveilig (exception safe) en thread-safe [SWS_PER_00429]. Bij mislukkingen levert de Result fabrikantspecifieke fouten of gedefinieerde foutcodes op:

• PerErrc::kResourceBusy: Het bestand is al geopend of wordt gelijktijdig verwerkt door DeleteFile, RecoverFile resp. ResetFile met dezelfde naam [SWS_PER_00429].
• Access: Het geheugengebied is geconfigureerd als alleen-lezen of vastgelegd als write-only-once en al bezet [SWS_PER_00429].
• PerErrc::kInvalidOpenMode: De meegegeven mode bevat een ongeldige combinatie van kenmerken [SWS_PER_00429].
• PerErrc::kOutOfStorageSpace resp. PerErrc::kTooManyFiles: De fysieke opslagruimte is niet toereikend voor een nieuwe aanmaak of de geconfigureerde limiet maxNumberOfFiles zou worden overschreden [SWS_PER_00429].
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed en PerErrc::kAuthenticationFailed: Fout bij toegang, bij de integriteits-, MAC- of validatiecontrole evenals bij de ontsleuteling [SWS_PER_00429].

Samenspel

De methode vormt een prestatie-geoptimaliseerde variant van het openen voor lezen/schrijven: terwijl [SWS_PER_00113] alleen de bestandsnaam en modus en [SWS_PER_00375] uitsluitend de bestandsnaam verwerkt, maakt [SWS_PER_00429] de gerichte versnelling van kleine I/O-toegangen via een expliciete geheugenbuffer mogelijk.

Gebruik

De methode OpenFileWriteOnly van de klasse ara::per::FileStorage opent een bestand synchroon voor exclusief schrijven met een gedefinieerde toegangsmodus [SWS_PER_00115]. Voor zover via de parameter mode niet anders aangegeven, wordt het bestand daarbij afgekapt (overeenkomstig kTruncate). Bestaat het bestand nog niet, dan wordt het nieuw aangemaakt. Als retourwaarde dient een ara::core::Result<UniqueHandle<WriteAccessor>>; bij het verlaten van de scope van de UniqueHandle wordt het bestand automatisch weer gesloten [SWS_PER_00115].

Foutafhandeling

In geval van een fout bevat de geretourneerde Result specifieke foutcodes [SWS_PER_00115]: Access geeft aan dat de opslag tegen schrijven is beveiligd of is geconfigureerd als Write-Once en de sleutel al bestaat. PerErrc::kInvalidOpenMode meldt ongeldige moduscombinaties en PerErrc::kOutOfStorageSpace onvoldoende fysieke opslagruimte. Verder kunnen PerErrc::kTooManyFiles, PerErrc::kPhysicalStorageFailure alsmede integriteits- en beveiligingsfouten zoals PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed optreden [SWS_PER_00115].

Gelijktijdigheid en beperkingen

De functie is ontworpen als thread-veilig en uitzonderingsveilig (noexcept) [SWS_PER_00115]. Parallelle toegangen tot hetzelfde bestand mislukken met de foutcode PerErrc::kResourceBusy indien het bestand al is geopend of gelijktijdig bewerkingen zoals DeleteFile, RecoverFile of ResetFile met dezelfde bestandsnaam worden uitgevoerd [SWS_PER_00115].

Samenspel

Naast deze functie biedt de interface een vereenvoudigde overbelasting zonder modusparameter, die standaard met kTruncate werkt [SWS_PER_00377], evenals een overbelasting met door de gebruiker gedefinieerde buffer om bloksgewijs schrijven mogelijk te maken ter versnelling van vele kleine toegangen [SWS_PER_00431].

Gebruik

De synchrone methode OpenFileWriteOnly van de klasse ara::per::FileStorage opent een bestand uitsluitend om te schrijven conform [SWS_PER_00377]. Deze neemt via de parameter fileName de naam van het doelbestand over. Als het bestand niet bestaat, wordt het nieuw aangemaakt; een reeds aanwezig bestand wordt afgekapt (overeenkomstig kTruncate) [SWS_PER_00377]. Als retourwaarde dient een ara::core::Result, die bij succes een ara::per::UniqueHandle<WriteAccessor> inkapselt. Deze handle sluit het bestand automatisch volgens het RAII-patroon zodra deze het geldigheidsbereik verlaat [SWS_PER_00377].

Foutafhandeling en gelijktijdigheid

De operatie is gedeclareerd als noexcept, exceptieveilig en thread-safe [SWS_PER_00377]. In het geval van een fout bevat de Result een specifieke foutcode uit PerErrc of een fabrikantspecifieke fout [SWS_PER_00377]:

• PerErrc::kResourceBusy: Het bestand is al geopend of wordt gelijktijdig bewerkt door DeleteFile, RecoverFile of ResetFile.
• PerErrc::kOutOfStorageSpace en PerErrc::kTooManyFiles: De fysieke opslagruimte is niet toereikend of het maximale aantal geconfigureerde bestanden (maxNumberOfFiles) wordt overschreden.
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed: Fout bij hardwaretoegang evenals bij integriteits-, validatie- of ontsleutelingscontroles.

Samenspel

Terwijl deze variant het afkappen vast voorschrijft, staat de overbelasting met de parameter OpenMode een afwijkende openingsmodus toe [SWS_PER_00115]. Voor geoptimaliseerde, bloksgewijze schrijfoperaties met meerdere kleine toegangen is een verdere overbelasting met een door de gebruiker gedefinieerde buffer (ara::core::Span<ara::core::Byte>) beschikbaar [SWS_PER_00431].

De synchrone methode OpenFileWriteOnly van de klasse ara::per::FileStorage opent een bestand om uitsluitend te schrijven en levert bij succes een ara::core::Result<UniqueHandle<WriteAccessor>> op [SWS_PER_00431]. Bij het verlaten van het geldigheidsbereik van de geretourneerde UniqueHandle wordt het geopende bestand automatisch gesloten [SWS_PER_00431]. De aanroep accepteert naast de bestandsnaam fileName en de toegangsmodus mode een buffer aan de gebruikerszijde buffer (als ara::core::Span<ara::core::Byte>), die wordt gebruikt voor bloksgewijs schrijven om herhaalde kleine schrijftoegangen te versnellen [SWS_PER_00431]. Indien in de modus niet anders geconfigureerd, wordt het bestand bij het openen afgekapt (overeenkomstig kTruncate); als het nog niet bestaat, wordt het nieuw aangemaakt [SWS_PER_00431].

Wat betreft gelijktijdigheid en veiligheid is de methode gespecificeerd als thread-safe en exception safe, en gedeclareerd als noexcept [SWS_PER_00431]. De toegang mislukt echter als het bestand al geopend is of als er gelijktijdig beheeroperaties zoals DeleteFile, RecoverFile of ResetFile op dezelfde bestandsnaam worden uitgevoerd [SWS_PER_00431].

In het geval van een fout wordt een overeenkomstige foutcode uit PerErrc of een fabrikantspecifieke fout in het resultaat geretourneerd [SWS_PER_00431]:

• PerErrc::kResourceBusy: Het bestand is al geopend of wordt bezet gehouden door een andere bestandsoperatie [SWS_PER_00431].
• PerErrc::kIllegalWriteAccess: De File Storage is alleen-lezen of geconfigureerd als write-only-once en het bestand bestaat al [SWS_PER_00431].
• PerErrc::kInvalidOpenMode: De meegegeven moduscombinatie is ongeldig [SWS_PER_00431].
• PerErrc::kOutOfStorageSpace of PerErrc::kTooManyFiles: De opslagruimte is niet toereikend of het maximale aantal geconfigureerde bestanden wordt overschreden [SWS_PER_00431].
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed: Fout bij fysieke toegang, integriteit, validatie, ontsleuteling of authenticatie [SWS_PER_00431].

In samenhang met andere interfaces breidt de functie de basismethoden [SWS_PER_00377] (alleen fileName) en [SWS_PER_00115] (met mode) gericht uit met bufferondersteuning voor geoptimaliseerde schrijfprocessen [SWS_PER_00431].

Gebruik

De synchrone methode RecoverFile van de klasse ara::per::FileStorage voert een best-effort-herstel van een afzonderlijk bestand uit wanneer redundantiecontroles mislukken [SWS_PER_00337]. De identifier van het desbetreffende bestand wordt via de parameter fileName als ara::core::StringView doorgegeven. Na het herstel kan het bestand verouderde versies of de initiële inhoud bevatten, of in het ongunstigste geval verloren zijn gegaan [SWS_PER_00337].

Gelijktijdigheid en wisselwerking

De operatie is gespecificeerd als thread-safe en exceptieveilig [SWS_PER_00337]. Deze mag echter niet worden uitgevoerd op geopende bestanden: voorafgaand aan de aanroep moeten alle eerder via bestandsopeningsmethoden zoals [SWS_PER_00113], [SWS_PER_00114] of [SWS_PER_00375] verkregen UniqueHandle-instanties zijn gesloten [SWS_PER_00337]. Anders mislukt de aanroep met PerErrc::kResourceBusy. Dezelfde fout wordt gemeld wanneer gelijktijdig [SWS_PER_00111] (DeleteFile) of [SWS_PER_00338] (ResetFile) voor dezelfde bestandsnaam wordt uitgevoerd [SWS_PER_00337].

Foutafhandeling

De functie retourneert een ara::core::Result<void> [SWS_PER_00337]. Naast PerErrc::kResourceBusy kunnen de volgende gestandaardiseerde fouten optreden:

• PerErrc::kFileNotFound: Het aangegeven bestand bestaat niet in de bestandsopslag [SWS_PER_00337].
• PerErrc::kPhysicalStorageFailure: De toegang tot het fysieke opslagmedium mislukt [SWS_PER_00337].
• PerErrc::kOutOfStorageSpace: De beschikbare fysieke opslagruimte is niet toereikend voor het herstelde bestand [SWS_PER_00337].
• PerErrc::kQuotaExceeded: Het herstelde bestand zou de geconfigureerde limiet maximumAllowedSize overschrijden [SWS_PER_00337].
• PerErrc::kEncryptionFailed en PerErrc::kAuthenticationFailed: De cryptografische ontsleuteling of de MAC-validatie van de opgeslagen gegevens is mislukt [SWS_PER_00337].

De synchrone methode ResetFile van de klasse ara::per::FileStorage zet een afzonderlijk bestand terug naar zijn vooraf geconfigureerde begintoestand [SWS_PER_00338]. Als het via fileName gespecificeerde bestand nog niet in de opslag aanwezig is, wordt het nieuw aangemaakt [SWS_PER_00338]. In beide gevallen heeft het bestand daarna dezelfde inhoud als na een herinstallatie vanuit de actuele Target Configuration [SWS_PER_00338]; de wijzigingsstatus ervan wordt in FileModificationState bijgehouden als kModifiedDuringReset [SWS_PER_00436].

De operatie is thread-safe en exceptieveilig en levert synchroon een ara::core::Result<void> op [SWS_PER_00338]. Deze mislukt met PerErrc::kResourceBusy als het bestand momenteel geopend is – bijvoorbeeld via [SWS_PER_00113] – of als er gelijktijdig een uitvoering van [SWS_PER_00111] of [SWS_PER_00337] met dezelfde bestandsnaam plaatsvindt [SWS_PER_00338].

Bovendien definieert de interface specifieke foutgevallen [SWS_PER_00338]:

• PerErrc::kInitValueNotAvailable: Er is noch in het Application Design noch in de Target Configuration een beginwaarde geconfigureerd [SWS_PER_00338].
• PerErrc::kQuotaExceeded of PerErrc::kTooManyFiles: Het herstelde bestand zou de limiet AllowedSize of maxNumberOfFiles overschrijden [SWS_PER_00338].
• PerErrc::kOutOfStorageSpace of StorageFailure: De fysieke opslagruimte is niet toereikend of de fysieke toegang mislukt [SWS_PER_00338].
• PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed: De ver- resp. ontsleuteling of de MAC-controle van de opgeslagen gegevens mislukt [SWS_PER_00338].