系統屬性提供了一種在系統範圍內共享資訊(通常是配置)的便捷方法。每個分區都可以在內部使用自己的系統屬性。跨分區存取屬性時可能會出現問題,例如/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 注意:帶有前綴 |
scope | Internal :只有所有者可以訪問。 |
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);
}
…
}
…