ใช้พร็อพเพอร์ตี้ของระบบเป็น API

พร็อพเพอร์ตี้ของระบบเป็นวิธีที่สะดวกในการแชร์ข้อมูล ซึ่งมักจะเป็นการกำหนดค่าทั่วทั้งระบบ พาร์ติชันแต่ละรายการสามารถใช้พร็อพเพอร์ตี้ของระบบของตัวเองได้ภายใน ปัญหาอาจเกิดขึ้นเมื่อมีการเข้าถึงพร็อพเพอร์ตี้ข้ามพาร์ติชัน เช่น /vendor ที่เข้าถึงพร็อพเพอร์ตี้ที่ /system กำหนด ตั้งแต่ Android 8.0 เป็นต้นไป คุณสามารถอัปเกรดพาร์ติชันบางส่วน เช่น /system ได้ ส่วน /vendor จะไม่เปลี่ยนแปลง เนื่องจากพร็อพเพอร์ตี้ของระบบเป็นเพียงพจนานุกรมส่วนกลางของคู่คีย์-ค่าสตริงที่ไม่มีสคีมา ทำให้พร็อพเพอร์ตี้คงที่จึงเป็นเรื่องยาก พาร์ติชัน /system อาจเปลี่ยนแปลงหรือนำพร็อพเพอร์ตี้ที่พาร์ติชัน /vendor นั้นใช้อยู่ออกโดยไม่มีการแจ้งให้ทราบ

ตั้งแต่รุ่น Android 10 เป็นต้นไป ระบบจะจัดรูปแบบพร็อพเพอร์ตี้ของระบบที่เข้าถึงได้ข้ามพาร์ติชันเป็นไฟล์คำอธิบาย Sysprop และสร้าง API ในการเข้าถึงพร็อพเพอร์ตี้เป็นฟังก์ชันที่เฉพาะเจาะจงสำหรับ C++ และ Rust รวมถึงคลาสสำหรับ Java API เหล่านี้ใช้งานสะดวกกว่าเนื่องจากไม่จำเป็นต้องใช้สตริงพิเศษ (เช่น ro.build.date) ในการเข้าถึง และเนื่องจากเป็น API แบบคงที่ ระบบจะตรวจสอบความเสถียรของ 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: สร้าง API Getter เท่านั้น
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 แล้ว 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
ULong std::optional<std::uint64_t> Optional<Long> u64
ดับเบิล std::optional<double> Optional<Double> f64
สตริง std::optional<std::string> Optional<String> String
Enum 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 1 รายการ, java_library 1 รายการ และ 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 ต่อท้าย

ในตัวอย่างก่อนหน้านี้ คุณสามารถเข้าถึงพร็อพเพอร์ตี้ที่กําหนดดังนี้

ตัวอย่าง 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);
    }
    …
}
…