Implementacja właściwości systemowych jako interfejsów API

Właściwości systemowe to wygodny sposób udostępniania informacji, zwykle konfiguracji, w całym systemie. Każda partycja może używać własnych właściwości systemowych wewnętrznie. Problem może wystąpić, gdy dostęp do właściwości jest uzyskiwany w różnych partycjach, np. /vendor uzyskuje dostęp do zdefiniowanych w /system właściwości. Od Androida 8.0 niektóre partycje, takie jak /system, można uaktualnić, podczas gdy element /vendor pozostaje bez zmian. Właściwości systemowe to tylko globalny słownik par klucz-wartość z łańcucha znaków bez schematu, więc trudno jest je ustabilizować. Partycja /system może bez powiadomienia zmienić lub usunąć właściwości, od których zależy partycja /vendor.

Począwszy od wersji Androida 10 właściwości systemowe dostępne na partycjach są przedstawiane w formie plików opisu Sysprop, a interfejsy API umożliwiające dostęp do właściwości są generowane jako konkretne funkcje w językach C++ i Rust oraz w klasach dla Javy. Te interfejsy API są wygodniejsze w użyciu, ponieważ dostęp do nich nie wymaga żadnych magicznych ciągów znaków (takich jak ro.build.date) i można je wpisywać statycznie. Stabilność ABI jest również sprawdzana w momencie kompilacji, a kompilacja kończy się niepowodzeniem, jeśli wystąpią niezgodne zmiany. Ta kontrola działa jako jawnie zdefiniowane interfejsy między partycjami. Te interfejsy API mogą też zapewnić spójność między Rustem, Javą i C++.

Zdefiniuj właściwości systemu jako interfejsy API

Określaj właściwości systemowe jako interfejsy API za pomocą plików opisu Sysprop (.sysprop), które używają formatu tekstowego protobuf, zgodnie z tym schematem:

// 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;
}

Jeden plik Sysprop Description zawiera jeden komunikat o właściwościach, który opisuje zbiór właściwości. Znaczenie pól:

Pole	Znaczenie
owner	Ustaw na partycję, która jest właścicielem właściwości: Platform, Vendor lub Odm.
module	Służy do tworzenia przestrzeni nazw (C++) lub statycznej klasy finalnej (Java), w której umieszczane są wygenerowane interfejsy API. Na przykład: com.android.sysprop.BuildProperties będzie przestrzenią nazw com::android::sysprop::BuildProperties w C++, a klasa BuildProperties w pakiecie com.android.sysprop w języku Java.
prop	Lista obiektów.

Oto znaczenie pól wiadomości Property.

Pole	Znaczenie
api_name	Nazwa wygenerowanego interfejsu API.
type	Typ tej usługi.
access	Readonly: generuje tylko interfejs API getter Writeonce, ReadWrite: generuje interfejsy API pobierania i ustawiania Uwaga: usługi z prefiksem ro. nie mogą korzystać z dostępu ReadWrite.
scope	Internal: dostęp ma tylko właściciel. Public: Każdy ma dostęp, z wyjątkiem modułów NDK.
prop_name	Nazwa właściwości systemowej, np. ro.build.date.
enum_values	(tylko Enum, EnumList) Ciąg znaków rozdzielany znakiem kreski pionowej(|), który zawiera możliwe wartości wyliczenia. Na przykład: value1|value2.
integer_as_bool	(tylko Boolean, BooleanList) Ustaw metody 0 i 1 zamiast false i true.
legacy_prop_name	(opcjonalnie, dotyczy tylko właściwości Readonly) starsza nazwa właściwości systemowej. Podczas wywoływania metody getter API próbuje odczytać zasadę prop_name, a jeśli prop_name nie istnieje, używa metody legacy_prop_name. Użyj legacy_prop_name, gdy chcesz wycofać dotychczasową usługę i przenieść się na nową.

Każdy typ właściwości jest mapowany na te typy w C++, Javie i Rust:

Typ	C++	Java	Rust
Wartość logiczna	std::optional<bool>	Optional<Boolean>	bool
Liczba całkowita	std::optional<std::int32_t>	Optional<Integer>	i32
UInt	std::optional<std::uint32_t>	Optional<Integer>	u32
Długie	std::optional<std::int64_t>	Optional<Long>	i64
Ulong	std::optional<std::uint64_t>	Optional<Long>	u64
Podwójny	std::optional<double>	Optional<Double>	f64
Ciąg znaków	std::optional<std::string>	Optional<String>	String
Wyliczenie	std::optional<{api_name}_values>	Optional<{api_name}_values>	{ApiName}Values
T List	std::vector<std::optional<T>>	List<T>	Vec<T>

Oto przykład pliku Sysprop Description, który definiuje 3 właściwości:

# 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
}

Zdefiniuj biblioteki właściwości systemu

Teraz możesz definiować moduły sysprop_library za pomocą plików opisu Sysprop. sysprop_library służy jako interfejs API dla C++, Javy i Rusta. System kompilacji wewnętrznie generuje rust_library, java_library i cc_library dla każdej instancji sysprop_library.

// File: Android.bp
sysprop_library {
    name: "PlatformProperties",
    srcs: ["android/sysprop/PlatformProperties.sysprop"],
    property_owner: "Platform",
    vendor_available: true,
}

W źródle musisz uwzględnić pliki z listami interfejsów API na potrzeby kontroli interfejsu API. Aby to zrobić, utwórz pliki interfejsu API i katalog api. Umieść katalog api w tym samym katalogu co Android.bp. Nazwy plików interfejsu API to <module_name>-current.txt i <module_name>-latest.txt. <module_name>-current.txt zawiera podpisy interfejsów API bieżących kodów źródłowych, a <module_name>-latest.txt zawiera najnowsze zablokowane podpisy interfejsów API. System kompilacji sprawdza, czy interfejsy API nie uległy zmianie, porównując te pliki interfejsu API z wygenerowanymi plikami API w czasie kompilacji i wysyła komunikat o błędzie oraz instrukcje aktualizacji pliku current.txt, jeśli current.txt nie pasuje do kodów źródłowych. Oto przykładowa organizacja katalogów i plików:

├── api
│   ├── PlatformProperties-current.txt
│   └── PlatformProperties-latest.txt
└── Android.bp

Uwaga: starsza wersja interfejsu sysprop_library może mieć inny zestaw plików z podpisami interfejsu API, czyli plików current.txt, removed.txt, system-current.txt, system-removed.txt, test-current.txt i test-removed.txt. W takim przypadku możesz je zaktualizować za pomocą polecenia m update-api.

Moduły klienckie Rust, Java i C++ można łączyć z sysprop_library, aby używać wygenerowanych interfejsów API. System kompilacji tworzy linki od klientów do wygenerowanych bibliotek C++, Java i Rust, zapewniając klientom dostęp do wygenerowanych interfejsów 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"],
}

Pamiętaj, że nazwa biblioteki Rust jest generowana przez konwersję nazwy sysprop_library na małe litery, zastąpienie znaków . i - wartością _, a następnie dodanie lib i _rust na początku nazwy.

W poprzednim przykładzie dostęp do zdefiniowanych właściwości można było uzyskać w ten sposób.

Przykład dotyczący rdzawego koloru:

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

  …
}

Przykład w Javie:

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

Przykład w 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);
    }
    …
}
…