类 ara::per::FileStorage

类 ara::per::FileStorage 的同步方法 DeleteFile 根据文件名（fileName）从文件存储中删除文件 [SWS_PER_00111]。该标识符可以对应于配置的 PersistencyFile.fileName [SWS_PER_00111]。该调用被指定为 noexcept，被视为异常安全且线程安全，并通过 ara::core::Result<void> 报告结果 [SWS_PER_00111]。

在调用之前，必须结束对目标文件的所有活动访问。如果文件当前处于打开状态，则删除操作失败并返回错误 PerErrc::kResourceBusy [SWS_PER_00111]。因此，应用程序必须确保先前通过 OpenFileReadWrite [SWS_PER_00113]、OpenFileReadOnly [SWS_PER_00114] 或 OpenFileWriteOnly [SWS_PER_00115] 创建的 UniqueHandle 实例已离开其作用域，从而关闭文件。同样，针对相同文件名并行执行 RecoverFile [SWS_PER_00337] 或 ResetFile [SWS_PER_00338] 会导致 PerErrc::kResourceBusy [SWS_PER_00111]。

发生错误时，返回的 Result 类型提供具体的错误原因 [SWS_PER_00111]：

• PerErrc::kFileNotFound：指定的文件在文件存储中不存在 [SWS_PER_00111]。
• PerErrc::kIllegalWriteAccess：文件存储被配置为只读 [SWS_PER_00111]。
• PerErrc::kPhysicalStorageFailure：访问物理存储介质失败（无回滚语义） [SWS_PER_00111]。
• PerErrc::kIntegrityCorrupted、PerErrc::kEncryptionFailed 或 PerErrc::kAuthenticationFailed：结构完整性、加密/解密或 MAC 校验错误（各自具有回滚语义）以及制造商特定错误 [SWS_PER_00111]。

类ara::per::FileStorage的同步方法FileExists检查相应文件存储中是否存在某个文件[SWS_PER_00112]。该函数声明为noexcept，并且不抛出 C++ 异常[SWS_PER_00112]。

使用

作为参数，fileName作为ara::core::StringView传递，这可以对应于已配置文件的标识符PersistencyFile.fileName[SWS_PER_00112]。如果能定位到该文件，返回值ara::core::Result<bool>返回true，否则返回false[SWS_PER_00112]。

错误处理

如果检查失败，返回的Result不包含布尔值，而是包含错误代码[SWS_PER_00112]。指定的错误原因为：

• 物理存储访问失败时为PerErrc::kPhysicalStorageFailure[SWS_PER_00112]，
• 数据结构完整性损坏时为PerErrc::kIntegrityCorrupted[SWS_PER_00112]，
• 无法保证已存储数据的有效性时为PerErrc::kValidationFailed[SWS_PER_00112]，
• 解密失败时为PerErrc::kEncryptionFailed[SWS_PER_00112]，
• MAC 检查失败时为PerErrc::kAuthenticationFailed[SWS_PER_00112]，以及可能的厂商特定错误[SWS_PER_00112]。

并发性与限制

该方法被声明为线程安全的[SWS_PER_00112]。然而，只要没有同时在存储中添加或删除文件，所提供的检查结果才是精确的；例如，如果另一个线程在返回true后立即删除了某个文件，则该结果已经不再有效[SWS_PER_00112]。

类 ara::per::FileStorage 的方法 OpenFileReadOnly（在 #include "ara/per/file_storage.h" 中声明）以指定的访问模式只读打开持久化文件 [SWS_PER_00114]。如果未通过参数 mode 另行指定，则读指针位置默认设置为文件开头（kAtTheBeginning）[SWS_PER_00114]。执行同步进行并返回一个 ara::core::Result<UniqueHandle<ReadAccessor>>。该句柄利用 RAII 语义：一旦 UniqueHandle 的实例离开其作用域，文件将自动关闭 [SWS_PER_00114]。

关于并发性，该方法被指定为 thread-safe 和 exception safe（带有 noexcept）[SWS_PER_00114]。尽管如此，仍存在功能性调用限制：如果目标文件已打开，或者同时正在对同一文件名执行诸如 DeleteFile、RecoverFile 或 ResetFile 等操作，则调用失败并带有 PerErrc::kResourceBusy [SWS_PER_00114]。

在出错的情况下，ara::core::Result 返回厂商特定错误或来自 PerErrc 或 StorageFailure 的标准化错误码 [SWS_PER_00114]：

• PerErrc::kFileNotFound：指定的文件在文件存储中不存在 [SWS_PER_00114]。
• PerErrc::kInvalidOpenMode：传递的模式包含无效的标志组合 [SWS_PER_00114]。
• StorageFailure：访问物理存储失败 [SWS_PER_00114]。
• PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kAuthenticationFailed 或 PerErrc::kEncryptionFailed：结构完整性损坏、验证不足、MAC 校验出错或解密失败 [SWS_PER_00114]。

在与其他接口的交互中，FileStorage 提供了两个相关的重载：一个是没有模式参数的变体，它始终在文件开头打开 [SWS_PER_00376]；另一个是带有缓冲区（ara::core::Span<ara::core::Byte> buffer）的重载，ReadAccessor 通过该缓冲区实现分块读取，以加速大量小规模访问 [SWS_PER_00430]。

使用

类 ara::per::FileStorage 的方法 OpenFileReadOnly 以只读方式打开持久化文件以供读取 [SWS_PER_00376]。通过头文件 ara/per/file_storage.h 进行调用，并传入文件名 fileName。读取位置在此初始设置为文件开头。作为返回值，提供一个 ara::core::Result，其在成功时提供一个 UniqueHandle<ReadAccessor>。一旦该句柄离开其作用域，打开的文件将自动关闭。

错误处理

如果执行失败，结果将包含错误代码或制造商特定错误 [SWS_PER_00376]：

• PerErrc::kFileNotFound：指定的文件在存储中不存在。
• PerErrc::kResourceBusy：文件已打开，或正在由 DeleteFile、RecoverFile 或 ResetFile 同时处理。
• PerErrc::kPhysicalStorageFailure：访问物理存储介质失败。
• PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed、PerErrc::kAuthenticationFailed：结构完整性、数据验证、解密或 MAC 校验错误。

并发性与交互

该方法被指定为 thread-safe、exception safe 以及 noexcept [SWS_PER_00376]。对于扩展需求，提供了重载：用于显式指定 OpenMode 的变体 [SWS_PER_00114]，以及带有附加用户缓冲区以按块加速较小读取访问的签名 [SWS_PER_00430]。

类 ara::per::FileStorage 的同步方法 OpenFileReadOnly 使用调用方提供的缓冲区打开持久化文件以供读取访问 [SWS_PER_00430]。根据参数 fileName、mode 以及 buffer（作为 ara::core::Span<ara::core::Byte>）初始化文件访问 [SWS_PER_00430]。除非通过 mode 另有规定，否则读取位置默认位于文件开头（kAtTheBeginning） [SWS_PER_00430]。传递的内存区域由生成的 ReadAccessor 使用，以便通过分块读取来加速重复的小读取访问 [SWS_PER_00430]。该资源通过 RAII 得到保护：一旦返回的 UniqueHandle 离开作用域，文件将自动关闭 [SWS_PER_00430]。

关于并发性，该函数被指定为线程安全（thread-safe）、异常安全（exception safe）以及 noexcept [SWS_PER_00430]。如果发生错误，ara::core::Result 会提供来自 PerErrc 的制造商特定错误或标准化错误代码 [SWS_PER_00430]：

• PerErrc::kResourceBusy：文件已打开，或正在由 DeleteFile、RecoverFile 或 ResetFile 同时处理 [SWS_PER_00430]。
• PerErrc::kFileNotFound：指定的文件在文件存储中不存在 [SWS_PER_00430]。
• PerErrc::kInvalidOpenMode：传入的模式包含无效的选项组合 [SWS_PER_00430]。
• 完整性与安全错误：PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed 或 PerErrc::kAuthenticationFailed（MAC 校验失败），以及在物理存储访问错误时的 StorageFailure [SWS_PER_00430]。

除了这种带缓冲的变体外，对于没有用户定义缓冲区的用例，还提供了重载 [SWS_PER_00114]（带有 mode）和 [SWS_PER_00376]（仅带有 fileName）。

使用

类 ara::per::FileStorage 的同步方法 OpenFileReadWrite 在指定模式下打开文件以进行读写访问 mode [SWS_PER_00113]。若在模式中未另作说明，文件指针默认设置在开头（kAtTheBeginning）。若文件尚不存在，则会自动创建 [SWS_PER_00113]。该函数返回带有 UniqueHandle<ReadWriteAccessor> 的 ara::core::Result，一旦该句柄离开其作用域，就会自动关闭文件 [SWS_PER_00113]。

并发性与限制

该调用是线程安全的（thread-safe）且不抛出异常（noexcept）[SWS_PER_00113]。调用时该文件不得处于已打开状态。此外，不得以相同文件名并发执行 DeleteFile、RecoverFile 或 ResetFile，否则调用将因 PerErrc::kResourceBusy 而失败 [SWS_PER_00113]。

错误处理

在出错时，ara::core::Result 包含特定的错误码 [SWS_PER_00113]：

• PerErrc::kInvalidOpenMode：传入的 mode 中的标志组合无效。
• PerErrc::kResourceBusy：目标文件已打开或被管理性文件操作占用。
• Access：存储被配置为只读，或在键已存在时被配置为仅写一次。
• PerErrc::kOutOfStorageSpace 或 PerErrc::kTooManyFiles：新建时物理存储空间不足或超出 maxNumberOfFiles。
• PerErrc::kPhysicalStorageFailure、PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed、PerErrc::kAuthenticationFailed：硬件访问错误、数据结构损坏或加密校验失败。

相互作用

作为简化变体，提供了一个不带模式参数的重载，该重载默认在开头打开文件 [SWS_PER_00375]。为了在大量微小访问时优化性能，还提供了一个带有自定义缓冲区（buffer）的重载，用于分块读写 [SWS_PER_00429]。

类 ara::per::FileStorage 的同步成员函数 OpenFileReadWrite 用于打开文件以进行读写组合访问 [SWS_PER_00375]。作为参数传递文件名 fileName 作为 ara::core::StringView，其可以对应于已配置文件的建模 PersistencyFile.fileName [SWS_PER_00375]。如果指定的文件尚不存在，则会自动新建 [SWS_PER_00375]。打开时，文件位置立即设置在开头（对应于 kAtTheBeginning）[SWS_PER_00375]。调用方接收到一个 ara::core::Result<UniqueHandle<ReadWriteAccessor>>；一旦返回的 UniqueHandle 离开其作用域，文件将自动关闭 [SWS_PER_00375]。

关于并发和执行上下文，该函数被指定为 thread-safe 和 exception safe [SWS_PER_00375]。但需要注意的是，并发访问受到规则约束：如果文件已打开，或者同时正在对同一文件名执行诸如 DeleteFile、RecoverFile 或 ResetFile 之类的操作，则调用失败并返回错误代码 PerErrc::kResourceBusy [SWS_PER_00375]。

在出错时，返回的 Result 对象封装持久性的具体错误或特定于制造商的错误 [SWS_PER_00375]：

• 配置和访问错误，例如在只读存储或 Write-Once 配置下已存在数据时的 Access [SWS_PER_00375]。
• 存储空间限制，如超出配置的文件上限时的 PerErrc::kOutOfStorageSpace 或 PerErrc::kTooManyFiles [SWS_PER_00375]。
• 完整性和安全错误，例如 PerErrc::kPhysicalStorageFailure、PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed 或 PerErrc::kAuthenticationFailed [SWS_PER_00375]。

在与 FileStorage 的其他接口交互中，AUTOSAR 提供了替代重载：OpenFileReadWrite 可以与显式 OpenMode 一起调用 [SWS_PER_00113]，或者与额外的用户端存储区域 buffer (ara::core::Span<ara::core::Byte>) 一起调用，从而允许按块缓冲以加速重复的小规模访问 [SWS_PER_00429]。

使用

类 ara::per::FileStorage 的方法 OpenFileReadWrite 在提供用户定义缓冲区的情况下同步打开文件以进行组合读写 [SWS_PER_00429]。传递的存储区 buffer（作为 ara::core::Span<ara::core::Byte>）由 ReadWriteAccessor 在内部用于分块读写操作，以便高性能地处理一系列小访问。如果指定的文件尚不存在，它将自动新建；除非在传入的 mode 中另有指定，否则文件位置默认位于开头（kAtTheBeginning） [SWS_PER_00429]。一旦在 ara::core::Result 中返回的 UniqueHandle 离开其作用域，文件即被关闭。Interpretation：传入的缓冲区 span 的底层内存大概必须在 UniqueHandle 的整个生命周期内保持有效，因为访问器会引用它来进行分块访问。 问题 Q-e0009b7de17e3597 (未决)

错误处理与并发

该函数被指定为 noexcept、异常安全（exception safe）且线程安全 [SWS_PER_00429]。在发生失败时，Result 提供制造商特定错误或定义的错误代码：

• PerErrc::kResourceBusy：文件已打开，或正在由具有相同名称的 DeleteFile、RecoverFile 或 ResetFile 同时处理 [SWS_PER_00429]。
• Access：存储区被配置为只读，或被设定为只写一次且已被占用 [SWS_PER_00429]。
• PerErrc::kInvalidOpenMode：传入的 mode 包含无效的特征组合 [SWS_PER_00429]。
• PerErrc::kOutOfStorageSpace 或 PerErrc::kTooManyFiles：用于新建文件的物理存储不足，或将超出配置的限制 maxNumberOfFiles [SWS_PER_00429]。
• PerErrc::kPhysicalStorageFailure、PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed 和 PerErrc::kAuthenticationFailed：访问错误，完整性、MAC 或验证检查错误，以及解密错误 [SWS_PER_00429]。

相互作用

该方法代表读/写打开的一种性能优化变体：虽然 [SWS_PER_00113] 仅处理文件名和模式，而 [SWS_PER_00375] 仅处理文件名，但 [SWS_PER_00429] 允许通过显式内存缓冲区有针对性地加速小 I/O 访问。

使用

类 ara::per::FileStorage 的方法 OpenFileWriteOnly 使用定义的访问模式同步打开文件以进行排他性写入 [SWS_PER_00115]。除非通过参数 mode 另有说明，否则文件将被截断（对应于 kTruncate）。如果文件尚不存在，则新建该文件。返回值使用 ara::core::Result<UniqueHandle<WriteAccessor>>；当离开 UniqueHandle 的作用域时，文件将自动再次关闭 [SWS_PER_00115]。

错误处理

在出错时，返回的 Result 包含具体的错误代码 [SWS_PER_00115]：Access 表示存储为只读或已配置为 Write-Once 且键已存在。PerErrc::kInvalidOpenMode 报告无效的模式组合，PerErrc::kOutOfStorageSpace 报告物理存储空间不足。此外，还可能发生 PerErrc::kTooManyFiles、PerErrc::kPhysicalStorageFailure 以及完整性和安全错误，例如 PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed 或 PerErrc::kAuthenticationFailed [SWS_PER_00115]。

并发性与限制

该函数设计为线程安全以及异常安全 (noexcept) [SWS_PER_00115]。如果文件已打开，或者同时正在对同一文件名执行诸如 DeleteFile、RecoverFile 或 ResetFile 之类的操作，则对同一文件的并行访问将失败并出现错误代码 PerErrc::kResourceBusy [SWS_PER_00115]。

相互作用

除了该函数外，该接口还提供了一个不带模式参数的简化重载（默认使用 kTruncate 运行 [SWS_PER_00377]），以及一个带有用户定义缓冲区的重载，以允许按块写入从而加速多次小规模访问 [SWS_PER_00431]。

使用

类 ara::per::FileStorage 的同步方法 OpenFileWriteOnly 根据 [SWS_PER_00377] 仅以写入方式打开文件。它通过参数 fileName 接收目标文件的名称。如果文件不存在，则会新建该文件；若文件已存在，则会被截断（对应于 kTruncate） [SWS_PER_00377]。作为返回值，提供一个 ara::core::Result，其在成功时封装一个 ara::per::UniqueHandle<WriteAccessor>。根据 RAII 模式，一旦该句柄离开作用域，就会自动关闭文件 [SWS_PER_00377]。

错误处理与并发

该操作被声明为 noexcept，具有异常安全性且是线程安全的 [SWS_PER_00377]。在发生错误时，Result 包含来自 PerErrc 的特定错误代码或制造商特定错误 [SWS_PER_00377]：

• PerErrc::kResourceBusy：文件已打开，或正在由 DeleteFile、RecoverFile 或 ResetFile 同时处理。
• PerErrc::kOutOfStorageSpace 和 PerErrc::kTooManyFiles：物理存储不足，或超出了配置的最大文件数量（maxNumberOfFiles）。
• PerErrc::kPhysicalStorageFailure、PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed 或 PerErrc::kAuthenticationFailed：硬件访问错误，以及完整性校验、验证或解密检查错误。

相互作用

虽然该变体固定指定了截断，但带有参数 OpenMode 的重载允许使用不同的打开方式 [SWS_PER_00115]。针对具有多次小访问的优化分块写入操作，还提供了带有用户定义缓冲区（ara::core::Span<ara::core::Byte>）的另一重载 [SWS_PER_00431]。

类 ara::per::FileStorage 的同步方法 OpenFileWriteOnly 打开文件以进行独占写入，并在成功时返回 ara::core::Result<UniqueHandle<WriteAccessor>> [SWS_PER_00431]。当离开返回的 UniqueHandle 的作用域时，打开的文件会自动关闭 [SWS_PER_00431]。除文件名 fileName 和访问模式 mode 外，该调用还接收用户端缓冲区 buffer（作为 ara::core::Span<ara::core::Byte>），用于分块写入，以加速重复的小写入访问 [SWS_PER_00431]。如果在模式中未作不同配置，则文件在打开时会被截断（对应于 kTruncate）；如果文件尚不存在，则会新建该文件 [SWS_PER_00431]。

在并发性和安全性方面，该方法被指定为thread-safe和exception safe，并声明为noexcept [SWS_PER_00431]。但是，如果文件已被打开，或者同时在同一文件名上执行诸如DeleteFile、RecoverFile或ResetFile等管理操作，则访问将失败[SWS_PER_00431]。

发生错误时，将在结果中返回来自PerErrc的相应错误代码或供应商特定错误[SWS_PER_00431]：

• PerErrc::kResourceBusy：文件已被打开或被其他文件操作占用[SWS_PER_00431]。
• PerErrc::kIllegalWriteAccess：文件存储为只读或配置为 write-only-once，且文件已存在[SWS_PER_00431]。
• PerErrc::kInvalidOpenMode：传入的模式组合无效[SWS_PER_00431]。
• PerErrc::kOutOfStorageSpace或PerErrc::kTooManyFiles：存储空间不足，或超过了配置的最大文件数[SWS_PER_00431]。
• PerErrc::kPhysicalStorageFailure、PerErrc::kIntegrityCorrupted、PerErrc::kValidationFailed、PerErrc::kEncryptionFailed或PerErrc::kAuthenticationFailed：物理访问、完整性、校验、解密或身份验证时发生错误[SWS_PER_00431]。

在与其他接口的协作中，该函数专门为基本方法[SWS_PER_00377]（仅fileName）和[SWS_PER_00115]（带mode）扩展了针对优化写入操作的缓冲区支持[SWS_PER_00431]。

使用

类 ara::per::FileStorage 的同步方法 RecoverFile 在冗余校验失败时尽力恢复单个文件 [SWS_PER_00337]。受影响文件的标识符通过参数 fileName 作为 ara::core::StringView 传递。恢复后，文件可能呈现过时状态或初始内容，或者在最坏的情况下丢失 [SWS_PER_00337]。

并发性与交互

该操作被指定为线程安全和异常安全 [SWS_PER_00337]。但是，不得在已打开的文件上执行：在调用之前，必须关闭先前通过文件打开方法（如 [SWS_PER_00113]、[SWS_PER_00114] 或 [SWS_PER_00375]）获取的所有 UniqueHandle 实例 [SWS_PER_00337]。否则，调用将失败并返回 PerErrc::kResourceBusy。如果同时针对相同文件名执行 [SWS_PER_00111]（DeleteFile）或 [SWS_PER_00338]（ResetFile），也会报告相同的错误 [SWS_PER_00337]。

错误处理

该函数返回 ara::core::Result<void> [SWS_PER_00337]。除 PerErrc::kResourceBusy 外，还可能发生以下标准化错误：

• PerErrc::kFileNotFound：指定的文件在文件存储中不存在 [SWS_PER_00337]。
• PerErrc::kPhysicalStorageFailure：访问物理存储介质失败 [SWS_PER_00337]。
• PerErrc::kOutOfStorageSpace：可用物理存储空间不足以存放恢复的文件 [SWS_PER_00337]。
• PerErrc::kQuotaExceeded：恢复的文件将超出配置的限制 maximumAllowedSize [SWS_PER_00337]。
• PerErrc::kEncryptionFailed 和 PerErrc::kAuthenticationFailed：所存储数据的加密解密或 MAC 验证失败 [SWS_PER_00337]。

类 ara::per::FileStorage 的同步方法 ResetFile 将单个文件重置为其预配置的初始状态 [SWS_PER_00338]。如果通过 fileName 指定的文件在存储中尚不存在，则会新建该文件 [SWS_PER_00338]。在这两种情况下，文件随后具有与从当前 Target Configuration 全新安装后相同的内容 [SWS_PER_00338]；其修改状态在 FileModificationState 中作为 kModifiedDuringReset 进行管理 [SWS_PER_00436]。

该操作是线程安全且异常安全的，并同步返回 ara::core::Result<void> [SWS_PER_00338]。如果文件当前处于打开状态（例如通过 [SWS_PER_00113]），或者同时正在对相同文件名执行 [SWS_PER_00111] 或 [SWS_PER_00337]，则该操作失败并返回 PerErrc::kResourceBusy [SWS_PER_00338]。

此外，该接口还定义了特定的错误情况 [SWS_PER_00338]：

• PerErrc::kInitValueNotAvailable：在 Application Design 和 Target Configuration 中均未配置初始值 [SWS_PER_00338]。
• PerErrc::kQuotaExceeded 或 PerErrc::kTooManyFiles：恢复的文件将超出限制 AllowedSize 或 maxNumberOfFiles [SWS_PER_00338]。
• PerErrc::kOutOfStorageSpace 或 StorageFailure：物理存储空间不足，或物理访问失败 [SWS_PER_00338]。
• PerErrc::kEncryptionFailed 或 PerErrc::kAuthenticationFailed：存储数据的加密或解密失败，或 MAC 校验失败 [SWS_PER_00338]。