將系統屬性實作為 API

系統屬性提供了一種在系統範圍內共享資訊（通常是配置）的便捷方法。每個分區都可以在內部使用自己的系統屬性。跨分區存取屬性時可能會出現問題，例如/vendor存取/system定義的屬性。從 Android 8.0 開始，某些分割區（例如/system ）可以升級，而/vendor保持不變。由於系統屬性只是一個沒有模式的字串鍵/值對的全域字典，因此很難穩定屬性。 /system分區可能會更改或刪除/vendor分區所依賴的屬性，恕不另行通知。

從 Android 10 版本開始，跨分區存取的系統屬性被模式化到 Sysprop 描述檔中，並且存取屬性的 API 會產生為 C++ 和 Rust 的特定函數以及 Java 的類別。這些 API 使用起來更方便，因為存取不需要魔術字串（例如ro.build.date ），而且它們可以靜態類型化。 ABI 穩定性也會在建置時進行檢查，如果發生不相容的更改，建置就會中斷。此檢查充當分區之間明確定義的介面。這些 API 還可以提供 Rust、Java 和 C++ 之間的一致性。

將系統屬性定義為 API

使用 Sysprop 描述檔 ( .sysprop ) 將系統屬性定義為 API，該檔案使用 protobuf 的 TextFormat，具有以下架構：

// File: sysprop.proto

syntax = "proto3";

package sysprop;

enum Access {
  Readonly = 0;
  Writeonce = 1;
  ReadWrite = 2;
}

enum Owner {
  Platform = 0;
  Vendor = 1;
  Odm = 2;
}

enum Scope {
  Public = 0;
  Internal = 2;
}

enum Type {
  Boolean = 0;
  Integer = 1;
  Long = 2;
  Double = 3;
  String = 4;
  Enum = 5;
  UInt = 6;
  ULong = 7;

  BooleanList = 20;
  IntegerList = 21;
  LongList = 22;
  DoubleList = 23;
  StringList = 24;
  EnumList = 25;
  UIntList = 26;
  ULongList = 27;
}

message Property {
  string api_name = 1;
  Type type = 2;
  Access access = 3;
  Scope scope = 4;
  string prop_name = 5;
  string enum_values = 6;
  bool integer_as_bool = 7;
  string legacy_prop_name = 8;
}

message Properties {
  Owner owner = 1;
  string module = 2;
  repeated Property prop = 3;
}

一個 Sysprop 描述檔包含一條屬性訊息，該訊息描述一組屬性。其字段意義如下。

場地意義
owner設定為擁有以下屬性的分割區： Platform 、 Vendor或Odm 。
module用於建立放置產生的 API 的命名空間 (C++) 或靜態最終類別 (Java)。例如， com.android.sysprop.BuildProperties在 C++ 中將是命名空間com::android::sysprop::BuildProperties ，在 Java 中將是com.android.sysprop中包中的BuildProperties類別。
prop屬性列表。

Property訊息欄位的含義如下。

場地意義
api_name產生的 API 的名稱。
type該屬性的類型。
access Readonly ：僅產生 getter API

Writeonce 、 ReadWrite ：產生 getter 和 setter API

注意：帶有前綴ro.不能使用ReadWrite存取。

scope Internal ：只有所有者可以訪問。

Public ：每個人都可以訪問，除了 NDK 模組。

prop_name基礎系統屬性的名稱，例如ro.build.date 。
enum_values （僅限Enum 、 EnumList ）以條 (|) 分隔的字串，由可能的枚舉值組成。例如， value1|value2 。
integer_as_bool （僅限Boolean 、 BooleanList ）讓 setter 使用0和1而不是false和true 。
legacy_prop_name （可選，僅限Readonly屬性）基礎系統屬性的舊名稱。當呼叫 getter 時，getter API 會嘗試讀取prop_name ，如果prop_name不存在，則使用legacy_prop_name 。棄用現有屬性並移至新屬性時，請使用legacy_prop_name 。

每種類型的屬性都會對應到 C++、Java 和 Rust 中的以下類型。

類型C++爪哇鏽
布林值std::optional<bool> Optional<Boolean> bool
整數std::optional<std::int32_t> Optional<Integer> i32
單位std::optional<std::uint32_t> Optional<Integer> u32
長的std::optional<std::int64_t> Optional<Long> i64
烏龍std::optional<std::uint64_t> Optional<Long> u64
雙倍的std::optional<double> Optional<Double> f64
細繩std::optional<std::string> Optional<String> String
列舉std::optional<{api_name}_values> Optional<{api_name}_values> {ApiName}Values
T列表std::vector<std::optional<T>> List<T> Vec<T>

以下是定義三個屬性的 Sysprop 描述檔的範例：

# File: android/sysprop/PlatformProperties.sysprop

owner: Platform
module: "android.sysprop.PlatformProperties"
prop {
    api_name: "build_date"
    type: String
    prop_name: "ro.build.date"
    scope: Public
    access: Readonly
}
prop {
    api_name: "date_utc"
    type: Integer
    prop_name: "ro.build.date_utc"
    scope: Internal
    access: Readonly
}
prop {
    api_name: "device_status"
    type: Enum
    enum_values: "on|off|unknown"
    prop_name: "device.status"
    scope: Public
    access: ReadWrite
}

定義系統屬性庫

現在您可以使用 Sysprop 描述檔定義sysprop_library模組。 sysprop_library用作 C++、Java 和 Rust 的 API。建置系統在內部為sysprop_library的每個實例產生 1 個rust_library 、1 個java_library和 1 個cc_library 。

// File: Android.bp
sysprop_library {
    name: "PlatformProperties",
    srcs: ["android/sysprop/PlatformProperties.sysprop"],
    property_owner: "Platform",
    vendor_available: true,
}

您必須在來源中包含 API 清單檔案以進行 API 檢查。為此，請建立 API 檔案和api目錄。將api目錄放在與Android.bp相同的目錄中。 API 檔名是<module_name>-current.txt 、 <module_name>-latest.txt 。 <module_name>-current.txt儲存目前原始碼的 API 簽名， <module_name>-latest.txt儲存最新凍結的 API 簽名。建置系統透過將這些 API 檔案與建置時產生的 API 檔案進行比較來檢查 API 是否已更改，如果current.txt與原始程式碼不匹配，則會發出錯誤訊息和更新current.txt檔案的說明。以下是目錄和文件組織的範例：

├── api
│   ├── PlatformProperties-current.txt
│   └── PlatformProperties-latest.txt
└── Android.bp

Rust、Java 和 C++ 用戶端模組可以連結到sysprop_library以使用產生的 API。建置系統創建從客戶端到生成的 C++、Java 和 Rust 庫的鏈接，從而使客戶端能夠存取生成的 API。

java_library {
    name: "JavaClient",
    srcs: ["foo/bar.java"],
    libs: ["PlatformProperties"],
}

cc_binary {
    name: "cc_client",
    srcs: ["baz.cpp"],
    shared_libs: ["PlatformProperties"],
}

rust_binary {
    name: "rust_client",
    srcs: ["src/main.rs"],
    rustlibs: ["libplatformproperties_rust"],
}

請注意，Rust 庫名稱是透過將sysprop_library名稱轉換為小寫並替換.和-帶有_ ，然後在前面加上lib並附加_rust 。

在上面的範例中，您可以如下存取定義的屬性。

生鏽的例子：

use platformproperties::DeviceStatusValues;

fn foo() -> Result<(), Error> {
  // Read "ro.build.date_utc". default value is -1.
  let date_utc = platformproperties::date_utc()?.unwrap_or_else(-1);

  // set "device.status" to "unknown" if "ro.build.date" is not set.
  if platformproperties::build_date()?.is_none() {
    platformproperties::set_device_status(DeviceStatusValues::UNKNOWN);
  }

  …
}

Java 範例：

import android.sysprop.PlatformProperties;

…

static void foo() {
    …
    // read "ro.build.date_utc". default value is -1
    Integer dateUtc = PlatformProperties.date_utc().orElse(-1);

    // set "device.status" to "unknown" if "ro.build.date" is not set
    if (!PlatformProperties.build_date().isPresent()) {
        PlatformProperties.device_status(
            PlatformProperties.device_status_values.UNKNOWN
        );
    }
    …
}
…

C++ 範例：

#include <android/sysprop/PlatformProperties.sysprop.h>
using namespace android::sysprop;

…

void bar() {
    …
    // read "ro.build.date". default value is "(unknown)"
    std::string build_date = PlatformProperties::build_date().value_or("(unknown)");

    // set "device.status" to "on" if it's "unknown" or not set
    using PlatformProperties::device_status_values;
    auto status = PlatformProperties::device_status();
    if (!status.has_value() || status.value() == device_status_values::UNKNOWN) {
        PlatformProperties::device_status(device_status_values::ON);
    }
    …
}
…