系統屬性可讓您輕鬆分享資訊,
設定整個系統每個分區都可以使用自己的系統屬性
內部。跨分區存取屬性時可能會發生問題
例如 /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
|
用於建立命名空間 (C++) 或靜態最終類別 (Java),
這時您會放置 AI 生成的 API例如:
com.android.sysprop.BuildProperties
會是 C++ 中的命名空間 com::android::sysprop::BuildProperties
和 BuildProperties 套件中的
Java 中的 com.android.sysprop 。
|
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 ,且採用 legacy_prop_name 的情況
「prop_name 」不存在。適用情況:legacy_prop_name
淘汰現有資源並移至新資源。
|
每種屬性都會對應至 C++、Java 和 Rust 中的以下型別。
類型 | C++ | Java | 荒漠油廠 |
---|---|---|---|
布林值 | 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
|
烏隆 | 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。建構系統
內部產生一個 rust_library
、一個 java_library
和一個 cc_library
每個 sysprop_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"],
}
請注意,轉換 sysprop_library
會產生 Rust 程式庫名稱
將名稱改為小寫,將 .
和 -
替換為 _
,然後在開頭加上 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);
}
…
}
…