ใช้พร็อพเพอร์ตี้ของระบบเป็น 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

กำหนดพร็อพเพอร์ตี้ของระบบเป็น API ด้วยไฟล์คำอธิบาย Sysprop (.sysprop) ซึ่งใช้ TextFormat ของ 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 1 ไฟล์มีข้อความสำหรับพร็อพเพอร์ตี้ 1 ข้อความ ซึ่งจะอธิบายชุดพร็อพเพอร์ตี้ ช่องต่างๆ มีความหมายดังต่อไปนี้

ฟิลด์	ความหมาย
owner	ตั้งค่าเป็นพาร์ติชันที่เป็นเจ้าของพร็อพเพอร์ตี้: Platform, Vendor หรือ Odm
module	ใช้เพื่อสร้างเนมสเปซ (C++) หรือคลาสสุดท้ายแบบคงที่ (Java) ที่มีการวาง API ที่สร้างขึ้น เช่น com.android.sysprop.BuildProperties จะเป็นเนมสเปซ com::android::sysprop::BuildProperties ใน C++ และคลาส BuildProperties ในแพ็กเกจใน com.android.sysprop ใน Java
prop	รายการที่พัก

ช่องข้อความ Property มีความหมายดังต่อไปนี้

ฟิลด์	ความหมาย
api_name	ชื่อของ API ที่สร้างขึ้น
type	ประเภทของพร็อพเพอร์ตี้นี้
access	Readonly: สร้าง Getter API เท่านั้น Writeonce, ReadWrite: สร้าง API Getter และ Setter หมายเหตุ: พร็อพเพอร์ตี้ที่มีคำนำหน้า ro. อาจไม่มีสิทธิ์เข้าถึง ReadWrite
scope	Internal: เฉพาะเจ้าของเท่านั้นที่เข้าถึงได้ Public: ทุกคนเข้าถึงได้ ยกเว้นโมดูล NDK
prop_name	ชื่อของพร็อพเพอร์ตี้ระบบที่สำคัญ เช่น ro.build.date
enum_values	(Enum, EnumList เท่านั้น) สตริงที่คั่นด้วยแท่ง(|) ซึ่งประกอบด้วยค่า enum ที่เป็นไปได้ เช่น value1|value2
integer_as_bool	(Boolean, BooleanList เท่านั้น) ให้ตัวตั้งค่าใช้ 0 และ 1 แทน false และ true
legacy_prop_name	(ไม่บังคับ และพร็อพเพอร์ตี้ Readonly เท่านั้น) ชื่อเดิมของพร็อพเพอร์ตี้ระบบที่สำคัญ เมื่อเรียก Getter API จะพยายามอ่าน prop_name และใช้ legacy_prop_name หากไม่มี 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
UI	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 ที่กำหนดพร็อพเพอร์ตี้ 3 รายการ

# 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_library โมดูลด้วยไฟล์คำอธิบาย Sysprop ได้แล้ว sysprop_library ทำหน้าที่เป็น API สำหรับ C++, Java และ Rust ระบบบิลด์จะสร้าง rust_library, java_library และ cc_library 1 รายการสำหรับ 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"],
}

โปรดทราบว่าชื่อไลบรารีของ 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);
    }
    …
}
…