以 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 的文字格式，且結構定義如下：

// 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++	Java	Rust
布林值	std::optional<bool>	Optional<Boolean>	bool
整數	std::optional<std::int32_t>	Optional<Integer>	i32
UInt	std::optional<std::uint32_t>	Optional<Integer>	u32
長	std::optional<std::int64_t>	Optional<Long>	i64
ULong	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 的每個例項，在內部產生一個 rust_library、一個 java_library 和一個 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。

在上述範例中，您可以依照下列方式存取定義的屬性。

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);
    }
    …
}
…