システムプロパティの API としての実装

システムプロパティを使用すると、通常はシステム全体の構成情報を簡単に共有できます。各パーティションは、内部で独自のシステムプロパティを使用できます。問題が発生するのは /system 定義のプロパティにアクセスする /vendor などのパーティション間でプロパティにアクセスする場合です。Android 8.0 以降、/system など一部のパーティションはアップグレードされましたが、/vendor は変更されていません。システムプロパティはスキーマのない文字列のキーと値のペアのグローバル辞書のため、プロパティを安定させるのは困難です。/system パーティションは、/vendor パーティションが依存しているプロパティを予告なく変更または削除できます。

Android 10 リリース以降、パーティション間でアクセスされるシステムプロパティは Sysprop Description ファイルにスキーマ化され、プロパティにアクセスする API は具体的な C++ の関数と Java のクラスとして生成されます。これらの API は、ro.build.date などアクセスに必要なマジック文字列がなく、静的に入力できるため便利です。ビルド時には ABI の安定性もチェックされ、互換性のない変更が発生した場合はビルドが中断されます。このチェックは、パーティション間の明示的に定義されたインターフェースとして機能します。これらの API は、Java と C++ 間の一貫性も保持できます。

API としてのシステムプロパティの定義

protobuf の TextFormat を使用する Sysprop Description ファイル（.sysprop）でシステムプロパティを API として定義するには、次のスキーマを使用します。

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

1 つの Sysprop Description ファイルには、一連のプロパティを記述するプロパティメッセージが 1 つあります。フィールドの意味は次のとおりです。

項目	意味
`owner`	`Platform`、`Vendor`、`Odm` のいずれかのプロパティを持つパーティションに設定します。
`module`	生成された API が配置される名前空間（C++ の場合）または静的な final クラス（Java の場合）を作成するために使用されます。`com.android.sysprop.BuildProperties` は、C++ では名前空間 `com::android::sysprop::BuildProperties` に、Java では `com.android.sysprop` のパッケージで `BuildProperties` クラスになります。
`prop`	プロパティのリスト。

Property メッセージフィールドの意味は次のとおりです。

項目	意味
`api_name`	生成された API の名前。
`type`	このプロパティの型。
`access`	`Readonly`: ゲッター API のみを生成します `Writeonce`、`ReadWrite`: ゲッター API とセッター API を生成します。注: 接頭辞 `ro.` の付いたプロパティは `ReadWrite` アクセスを使用できません。
`scope`	`Internal`: オーナーのみがアクセスできます。 `Public`: NDK モジュールを除きすべてがアクセスできます。
`prop_name`	`ro.build.date` など、基礎となるシステムプロパティの名前。
`enum_values`	（`Enum`、`EnumList` のみ）可能な列挙値で構成される、バー（\|）で区切られた文字列（例: `value1\|value2`）。
`integer_as_bool`	（`Boolean`、`BooleanList` のみ）セッターが `false` と `true` の代わりに `0` と `1` を使用するようにします。
`legacy_prop_name`	（省略可、`Readonly` プロパティのみ）基礎となるシステムプロパティの以前の名前。ゲッターを呼び出すと、ゲッター API は `prop_name` の読み取りを試み、`prop_name` が存在しない場合は `legacy_prop_name` を使用します。既存のプロパティを廃止し、新しいプロパティに移行する場合は、`legacy_prop_name` を使用します。

プロパティの各タイプは、C ++ と Java では次の型に対応しています。

タイプ	C++	Java
ブール値	`std::optional<bool>`	`Optional<Boolean>`
整数	`std::optional<std::int32_t>`	`Optional<Integer>`
単位	`std::optional<std::uint32_t>`	`Optional<Integer>`
長さ	`std::optional<std::int64_t>`	`Optional<Long>`
ULong	`std::optional<std::uint64_t>`	`Optional<Long>`
ダブル	`std::optional<double>`	`Optional<Double>`
文字列	`std::optional<std::string>`	`Optional<String>`
列挙型	`std::optional<{api_name}_values>`	`Optional<{api_name}_values>`
T リスト	`std::vector<std::optional<T>>`	`List<T>`

以下に、3 つのプロパティを定義する Sysprop Description ファイルの例を示します。

# 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 Description ファイルで定義できるようになりました。 sysprop_library は、C++ と Java の両方の API として機能します。ビルドシステムは、sysprop_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

Java と C++ のどちらのクライアントモジュールも、sysprop_library にリンクして生成された API を使用できます。生成された C++ ライブラリと Java ライブラリに対して、ビルドシステムはクライアントからのリンクを作成し、生成された API にクライアントがアクセスできるようにします。

java_library {
    name: "JavaClient",
    srcs: ["foo/bar.java"],
    libs: ["PlatformProperties"],
}

cc_binary {
    name: "cc_client",
    srcs: ["baz.cpp"],
    shared_libs: ["PlatformProperties"],
}

上記の例では、次のように定義されたプロパティにアクセスできます。

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

システム プロパティの API としての実装

API としてのシステム プロパティの定義

システム プロパティ ライブラリの定義

システムプロパティの API としての実装

API としてのシステムプロパティの定義

システムプロパティライブラリの定義