このページは Cloud Translation API によって翻訳されました。

AIDLバックエンド

AIDL バックエンドは、スタブコード生成のターゲットです。 AIDL ファイルを使用する場合は、常に特定の言語と特定のランタイムで使用します。コンテキストに応じて、異なる AIDL バックエンドを使用する必要があります。

AIDL には次のバックエンドがあります。

バックエンド	言語	API サーフェス	ビルドシステム
ジャワ	ジャワ	SDK/SystemApi (安定版*)	全て
NDK	C++	libbinder_ndk (安定版*)	aidl_interface
CPP	C++	libbinder (不安定)	全て
さび	さび	libbinder_rs (不安定)	aidl_interface

これらの API サーフェスは安定していますが、サービス管理用の API など、多くの API は内部プラットフォーム用に予約されており、アプリでは使用できません。アプリで AIDL を使用する方法の詳細については、開発者向けドキュメントを参照してください。
Rust バックエンドは Android 12 で導入されました。 NDK バックエンドは Android 10 以降で利用可能です。
Rust クレートはlibbinder_ndkの上に構築されています。 APEX は、システム側の他の人と同じようにバインダークレートを使用します。 Rust部分はAPEXに同梱して出荷します。システムパーティションのlibbinder_ndk.soに依存します。

ビルドシステム

バックエンドに応じて、AIDL をスタブコードにコンパイルする方法が 2 つあります。ビルドシステムの詳細については、 Soong モジュールリファレンスを参照してください。

コアビルドシステム

cc_またはjava_ Android.bp モジュール (または同等のAndroid.mk ) では、 .aidlファイルをソースファイルとして指定できます。この場合、AIDL の Java/CPP バックエンドが使用され (NDK バックエンドではありません)、対応する AIDL ファイルを使用するためのクラスがモジュールに自動的に追加されます。そのモジュール内の AIDL ファイルへのルートパスをビルドシステムに伝えるlocal_include_dirsなどのオプションは、これらのモジュールのaidl:グループの下で指定できます。 Rust バックエンドは Rust でのみ使用されることに注意してください。 rust_モジュールは、AIDL ファイルがソースファイルとして指定されていないという点で、異なる方法で処理されます。代わりに、 aidl_interfaceモジュールは、リンク可能な<aidl_interface name>-rust rustlib生成します。詳細については、 Rust AIDL の例を参照してください。

aidl_interface

安定した AIDLを参照してください。このビルドシステムで使用される型は構造化されている必要があります。つまり、AIDL で直接表現されます。これは、カスタム Parcelable を使用できないことを意味します。

タイプ

aidlコンパイラは、型の参照実装と見なすことができます。インターフェイスを作成するときは、 aidl --lang=<backend> ...を呼び出して、結果のインターフェイスファイルを確認します。 aidl_interfaceモジュールを使用すると、 out/soong/.intermediates/<path to module>/で出力を表示できます。

Java/AIDL タイプ	C++ タイプ	NDK タイプ	さびの種類
ブール値	ブール	ブール	ブール
バイト	int8_t	int8_t	i8
チャー	char16_t	char16_t	u16
整数	int32_t	int32_t	i32
長いです	int64_t	int64_t	i64
浮く	浮く	浮く	f32
ダブル	ダブル	ダブル	f64
弦	アンドロイド::文字列16	std::文字列	弦
android.os.Parcelable	android::パーセル可能	なし	なし
IBinder	アンドロイド::IBinder	ndk::SpAIBinder	バインダー::SpIBinder
T[]	std::vector<T>	std::vector<T>	中: &[T] アウト: Vec<T>
バイト[]	std::vector<uint8_t>	std::vector<int8_t> ¹	中: &[u8] Out: Vec<u8>
List<T>	std::vector<T> ²	std::vector<T> ³	中: &[T] ⁴ アウト: Vec<T>
ファイル記述子	android::base::unique_fd	なし	バインダー::パーセル::ParcelFileDescriptor
パーセルファイル記述子	android::os::ParcelFileDescriptor	ndk::ScopedFileDescriptor	バインダー::パーセル::ParcelFileDescriptor
インターフェイスタイプ (T)	アンドロイド::sp<T>	std::shared_ptr<T>	バインダー::強い
パーセルタイプ（T）	T	T	T
ユニオンタイプ(T) ⁵	T	T	T
T[N] ⁶	std::array<T, N>	std::array<T, N>	[T; N]

^{1. Android 12 以降では、バイト配列は互換性の理由から int8_t ではなく uint8_t を使用します。}

^{2. C++ バックエンドはList<T>をサポートしますTはString 、 IBinder 、 ParcelFileDescriptorまたは parcelable のいずれかです。 Android 13 以降では、 Tは配列を除く任意の非プリミティブ型 (インターフェース型を含む) にすることができます。 AOSP では、すべてのバックエンドで機能するため、 T[]などの配列型を使用することをお勧めします。}

^{3. NDK バックエンドはList<T>をサポートしますTはString 、 ParcelFileDescriptorまたは parcelable のいずれかです。 Android 13 以降では、 Tは配列以外の非プリミティブ型にすることができます。}

^{4. タイプが入力 (引数) であるか出力 (戻り値) であるかによって、型が Rust コードに異なる方法で渡されます。}

^{5. Union 型は、Android 12 以降でサポートされています。}

^{6. Android 13 以降では、固定サイズの配列がサポートされています。固定サイズの配列は複数の次元を持つことができます (例: int[3][4] )。 Java バックエンドでは、固定サイズの配列は配列型として表されます。}

方向性 (in/out/inout)

関数に引数の型を指定する場合、 in 、 out 、またはinoutとして指定できます。これは、IPC 呼び出しで情報が渡される方向を制御します。 inはデフォルトの方向であり、データが呼び出し元から呼び出し先に渡されることを示します。 outは、データが呼び出し先から呼び出し元に渡されることを意味します。 inoutは、これらの両方の組み合わせです。ただし、Android チームは、引数指定子inoutの使用を避けることを推奨しています。バージョン管理されたインターフェースと古い呼び出し先でinoutを使用すると、呼び出し元にのみ存在する追加フィールドがデフォルト値にリセットされます。 Rust に関しては、通常のinout型は&mut Vec<T>を受け取り、リストのinout型は&mut Vec<T>を受け取ります。

UTF8/UTF16

CPP バックエンドでは、文字列が utf-8 か utf-16 かを選択できます。 AIDL で文字列を@utf8InCpp Stringとして宣言し、自動的に utf-8 に変換します。 NDK と Rust バックエンドは常に utf-8 文字列を使用します。 utf8InCpp アノテーションの詳細については、 utf8InCppのアノテーションを参照してください。

Null可能性

Java バックエンドで null になる可能性のある型に@nullableのアノテーションを付けて、null 値を CPP および NDK バックエンドに公開できます。 Rust バックエンドでは、これらの@nullable型はOption<T>として公開されます。デフォルトでは、ネイティブサーバーは null 値を拒否します。これに対する唯一の例外はinterfaceとIBinderの型で、NDK の読み取りと CPP/NDK の書き込みでは常に null になる可能性があります。 nullableアノテーションの詳細については、 AIDLのアノテーションを参照してください。

カスタムパーセルブル

コアビルドシステムの C++ および Java バックエンドでは、ターゲットバックエンド (C++ または Java) で手動で実装されるパーセルブルを宣言できます。

    package my.package;
    parcelable Foo;

または C++ ヘッダー宣言を使用:

    package my.package;
    parcelable Foo cpp_header "my/package/Foo.h";

次に、この parcelable を AIDL ファイルのタイプとして使用できますが、AIDL によって生成されません。

Rust はカスタム Parcelable をサポートしていません。

デフォルト値

構造化されたパーセルブルは、プリミティブ、 String 、およびこれらの型の配列のフィールドごとのデフォルト値を宣言できます。

    parcelable Foo {
      int numField = 42;
      String stringField = "string value";
      char charValue = 'a';
      ...
    }

デフォルト値が欠落している Java バックエンドでは、フィールドはプリミティブ型の場合はゼロ値として初期化され、非プリミティブ型の場合はnullとして初期化されます。

他のバックエンドでは、デフォルト値が定義されていない場合、フィールドはデフォルトの初期化値で初期化されます。たとえば、C++ バックエンドでは、 Stringフィールドは空の文字列として初期化され、 List<T>フィールドは空のvector<T>として初期化されます。 @nullableフィールドは、null 値フィールドとして初期化されます。

エラー処理

Android OS には、サービスがエラーを報告するときに使用する組み込みのエラータイプが用意されています。これらはバインダーによって使用され、バインダーインターフェイスを実装する任意のサービスで使用できます。それらの使用法は AIDL 定義で十分に文書化されており、ユーザー定義のステータスや戻り値の型は必要ありません。

エラーのある出力パラメータ

AIDL 関数がエラーを報告すると、関数は出力パラメーターを初期化または変更しない場合があります。具体的には、トランザクション自体の処理中にエラーが発生するのではなく、パーセル解除中にエラーが発生した場合、出力パラメーターが変更される可能性があります。一般に、AIDL 関数からエラーが発生した場合、すべてのinoutおよびoutパラメーターと戻り値 (一部のバックエンドではoutパラメーターのように機能します) は、不定状態にあると見なす必要があります。

どのエラー値を使用するか

組み込みのエラー値の多くは、任意の AIDL インターフェースで使用できますが、一部は特別な方法で処理されます。たとえば、 EX_UNSUPPORTED_OPERATIONとEX_ILLEGAL_ARGUMENTは、エラー状態を説明する場合に使用しても問題ありませんが、 EX_TRANSACTION_FAILEDは、基盤となるインフラストラクチャによって特別に扱われるため、使用してはなりません。これらの組み込み値の詳細については、バックエンド固有の定義を確認してください。

AIDL インターフェースが、組み込みのエラータイプでカバーされない追加のエラー値を必要とする場合、ユーザーが定義したサービス固有のエラー値を含めることができる特別なサービス固有の組み込みエラーを使用できます。 .これらのサービス固有のエラーは通常、AIDL インターフェースでconst intまたはintに基づくenum型として定義され、バインダーによって解析されません。

Java では、エラーはandroid.os.RemoteExceptionなどの例外にマップされます。サービス固有の例外の場合、Java はユーザー定義エラーとともにandroid.os.ServiceSpecificExceptionを使用します。

Android のネイティブコードは例外を使用しません。 CPP バックエンドはandroid::binder::Statusを使用します。 NDK バックエンドはndk::ScopedAStatusを使用します。 AIDL によって生成されたすべてのメソッドは、メソッドのステータスを表すこれらのいずれかを返します。 Rust バックエンドは NDK と同じ例外コード値を使用しますが、それらをユーザーに配信する前にネイティブの Rust エラー ( StatusCode 、 ExceptionCode ) に変換します。サービス固有のエラーの場合、返されたStatusまたはScopedAStatusは、ユーザー定義のエラーと共にEX_SERVICE_SPECIFICを使用します。

組み込みのエラータイプは、次のファイルにあります。

バックエンド	意味
ジャワ	`android/os/Parcel.java`
CPP	`binder/Status.h`
NDK	`android/binder_status.h`
さび	`android/binder_status.h`

さまざまなバックエンドの使用

これらの手順は、Android プラットフォームコードに固有のものです。これらの例では、定義済みの型my.package.IFooを使用しています。 Rust バックエンドの使用方法については、 Android Rust PatternsページのRust AIDL の例を参照してください。

タイプのインポート

定義された型がインターフェース、パーセルブル、ユニオンのいずれであっても、Java にインポートできます。

import my.package.IFoo;

または CPP バックエンドで:

#include <my/package/IFoo.h>

または NDK バックエンドで (追加のaidl名前空間に注意してください):

#include <aidl/my/package/IFoo.h>

または Rust バックエンドで:

use my_package::aidl::my::package::IFoo;

Java ではネストされた型をインポートできますが、CPP/NDK バックエンドでは、そのルート型のヘッダーを含める必要があります。たとえば、 my/package/IFoo.aidl <my/package/IFoo.h>定義されたネストされたタイプBarをインポートする場合 ( IFooはファイルのルートタイプです)、CPP バックエンド (または<aidl/my/package/IFoo.h> NDK バックエンドの場合)。

サービスの実装

サービスを実装するには、ネイティブスタブクラスから継承する必要があります。このクラスは、バインダードライバーからコマンドを読み取り、実装したメソッドを実行します。次のような AIDL ファイルがあるとします。

    package my.package;
    interface IFoo {
        int doFoo();
    }

Java では、このクラスから拡張する必要があります。

    import my.package.IFoo;
    public class MyFoo extends IFoo.Stub {
        @Override
        int doFoo() { ... }
    }

CPP バックエンドで:

    #include <my/package/BnFoo.h>
    class MyFoo : public my::package::BnFoo {
        android::binder::Status doFoo(int32_t* out) override;
    }

NDK バックエンド (追加のaidl名前空間に注意してください):

    #include <aidl/my/package/BnFoo.h>
    class MyFoo : public aidl::my::package::BnFoo {
        ndk::ScopedAStatus doFoo(int32_t* out) override;
    }

Rust バックエンドでは:

    use aidl_interface_name::aidl::my::package::IFoo::{BnFoo, IFoo};
    use binder;

    /// This struct is defined to implement IRemoteService AIDL interface.
    pub struct MyFoo;

    impl Interface for MyFoo {}

    impl IFoo for MyFoo {
        fn doFoo(&self) -> binder::Result<()> {
           ...
           Ok(())
        }
    }

サービスの登録と取得

プラットフォーム Android のサービスは通常、 servicemanagerプロセスに登録されます。以下の API に加えて、一部の API はサービスをチェックします (つまり、サービスが利用できない場合はすぐに戻ります)。正確な詳細については、対応するservicemanagerインターフェイスを確認してください。これらの操作は、プラットフォーム Android に対してコンパイルする場合にのみ実行できます。

Java の場合:

    import android.os.ServiceManager;
    // registering
    ServiceManager.addService("service-name", myService);
    // return if service is started now
    myService = IFoo.Stub.asInterface(ServiceManager.checkService("service-name"));
    // waiting until service comes up (new in Android 11)
    myService = IFoo.Stub.asInterface(ServiceManager.waitForService("service-name"));
    // waiting for declared (VINTF) service to come up (new in Android 11)
    myService = IFoo.Stub.asInterface(ServiceManager.waitForDeclaredService("service-name"));

CPP バックエンドで:

    #include <binder/IServiceManager.h>
    // registering
    defaultServiceManager()->addService(String16("service-name"), myService);
    // return if service is started now
    status_t err = checkService<IFoo>(String16("service-name"), &myService);
    // waiting until service comes up (new in Android 11)
    myService = waitForService<IFoo>(String16("service-name"));
    // waiting for declared (VINTF) service to come up (new in Android 11)
    myService = waitForDeclaredService<IFoo>(String16("service-name"));

NDK バックエンド (追加のaidl名前空間に注意してください):

    #include <android/binder_manager.h>
    // registering
    status_t err = AServiceManager_addService(myService->asBinder().get(), "service-name");
    // return if service is started now
    myService = IFoo::fromBinder(SpAIBinder(AServiceManager_checkService("service-name")));
    // is a service declared in the VINTF manifest
    // VINTF services have the type in the interface instance name.
    bool isDeclared = AServiceManager_isDeclared("android.hardware.light.ILights/default");
    // wait until a service is available (if isDeclared or you know it's available)
    myService = IFoo::fromBinder(SpAIBinder(AServiceManager_waitForService("service-name")));

Rust バックエンドでは:

use myfoo::MyFoo;
use binder;
use aidl_interface_name::aidl::my::package::IFoo::BnFoo;

fn main() {
    binder::ProcessState::start_thread_pool();
    // [...]
    let my_service = MyFoo;
    let my_service_binder = BnFoo::new_binder(
        my_service,
        BinderFeatures::default(),
    );
    binder::add_service("myservice", my_service_binder).expect("Failed to register service?");
    // Does not return - spawn or perform any work you mean to do before this call.
    binder::ProcessState::join_thread_pool()
}

死へのつながり

バインダーをホストしているサービスが終了したときの通知を受け取るように要求できます。これにより、コールバックプロキシのリークを回避したり、エラーの回復を支援したりできます。バインダープロキシオブジェクトでこれらの呼び出しを行います。

Java では、 android.os.IBinder::linkToDeathを使用します。
CPP バックエンドでは、 android::IBinder::linkToDeathを使用します。
NDK バックエンドでは、 AIBinder_linkToDeathを使用します。
Rust バックエンドでDeathRecipientオブジェクトを作成し、 my_binder.link_to_death(&mut my_death_recipient)を呼び出します。 DeathRecipientがコールバックを所有しているため、通知を受け取りたい限り、そのオブジェクトを存続させておく必要があることに注意してください。

発信者情報

カーネルバインダー呼び出しを受信すると、呼び出し元の情報がいくつかの API で利用可能になります。 PID (またはプロセス ID) は、トランザクションを送信しているプロセスの Linux プロセス ID を参照します。 UID (またはユーザー ID) は、Linux ユーザー ID を指します。一方向呼び出しを受信する場合、呼び出し元の PID は 0 です。バインダートランザクションコンテキストの外にある場合、これらの関数は現在のプロセスの PID と UID を返します。

Java バックエンドでは:

    ... = Binder.getCallingPid();
    ... = Binder.getCallingUid();

CPP バックエンドで:

    ... = IPCThreadState::self()->getCallingPid();
    ... = IPCThreadState::self()->getCallingUid();

NDK バックエンドで:

    ... = AIBinder_getCallingPid();
    ... = AIBinder_getCallingUid();

Rust バックエンドでは、インターフェースを実装するときに、(デフォルトにするのではなく) 以下を指定します。

    ... = ThreadState::get_calling_pid();
    ... = ThreadState::get_calling_uid();

サービスのバグレポートとデバッグ API

バグレポートが実行されると (たとえば、 adb bugreportを使用して)、システム全体から情報が収集され、さまざまな問題のデバッグに役立ちます。 AIDL サービスの場合、バグレポートは、サービスマネージャーに登録されているすべてのサービスでバイナリdumpsysを使用して、その情報をバグレポートにダンプします。コマンドラインでdumpsysを使用して、 dumpsys SERVICE [ARGS]でサービスから情報を取得することもできます。 C++ および Java バックエンドでは、 addServiceに追加の引数を使用して、サービスがダンプされる順序を制御できます。また、 dumpsys --pid SERVICEを使用して、デバッグ中にサービスの PID を取得することもできます。

サービスにカスタム出力を追加するには、AIDL ファイルで定義された他の IPC メソッドを実装する場合と同様に、サーバーオブジェクトでdumpメソッドをオーバーライドできます。これを行うときは、アプリの許可android.permission.DUMPへのダンプを制限するか、特定の UID へのダンプを制限する必要があります。

Java バックエンドでは:

    @Override
    protected void dump(@NonNull FileDescriptor fd, @NonNull PrintWriter fout,
        @Nullable String[] args) {...}

CPP バックエンドで:

    status_t dump(int, const android::android::Vector<android::String16>&) override;

NDK バックエンドで:

    binder_status_t dump(int fd, const char** args, uint32_t numArgs) override;

Rust バックエンドでは、インターフェースを実装するときに、(デフォルトにするのではなく) 以下を指定します。

    fn dump(&self, mut file: &File, args: &[&CStr]) -> binder::Result<()>

インターフェイス記述子を動的に取得する

インターフェイス記述子は、インターフェイスのタイプを識別します。これは、デバッグ時や不明なバインダーがある場合に役立ちます。

Java では、次のようなコードでインターフェイス記述子を取得できます。

    service = /* get ahold of service object */
    ... = service.asBinder().getInterfaceDescriptor();

CPP バックエンドで:

    service = /* get ahold of service object */
    ... = IInterface::asBinder(service)->getInterfaceDescriptor();

NDK および Rust バックエンドは、この機能をサポートしていません。

インターフェイス記述子を静的に取得しています

場合によっては ( @VintfStabilityサービスを登録する場合など)、インターフェイス記述子が静的に何であるかを知る必要があります。 Java では、次のようなコードを追加して記述子を取得できます。

    import my.package.IFoo;
    ... IFoo.DESCRIPTOR

CPP バックエンドで:

    #include <my/package/BnFoo.h>
    ... my::package::BnFoo::descriptor

NDK バックエンド (追加のaidl名前空間に注意してください):

    #include <aidl/my/package/BnFoo.h>
    ... aidl::my::package::BnFoo::descriptor

Rust バックエンドでは:

    aidl::my::package::BnFoo::get_descriptor()

列挙範囲

ネイティブバックエンドでは、列挙型が取り得る値を反復処理できます。コードサイズの考慮事項により、これは現在 Java ではサポートされていません。

AIDL で定義された列挙MyEnumの場合、反復は次のように提供されます。

CPP バックエンドで:

    ::android::enum_range<MyEnum>()

NDK バックエンドで:

   ::ndk::enum_range<MyEnum>()

Rust バックエンドでは:

    MyEnum::enum_range()

スレッド管理

プロセス内のlibbinderの各インスタンスは、1 つのスレッドプールを維持します。ほとんどのユースケースでは、これは正確に 1 つのスレッドプールであり、すべてのバックエンドで共有されます。これに対する唯一の例外は、ベンダーコードが libbinder の別のコピーをロードして/dev/vndbinder libbinder対話する場合です。これは別のバインダーノード上にあるため、スレッドプールは共有されません。

Java バックエンドの場合、スレッドプールはサイズを増やすことしかできません (既に開始されているため)。

    BinderInternal.setMaxThreads(<new larger value>);

CPP バックエンドでは、次の操作を利用できます。

    // set max threadpool count (default is 15)
    status_t err = ProcessState::self()->setThreadPoolMaxThreadCount(numThreads);
    // create threadpool
    ProcessState::self()->startThreadPool();
    // add current thread to threadpool (adds thread to max thread count)
    IPCThreadState::self()->joinThreadPool();

同様に、NDK バックエンドでは次のようになります。

    bool success = ABinderProcess_setThreadPoolMaxThreadCount(numThreads);
    ABinderProcess_startThreadPool();
    ABinderProcess_joinThreadPool();

Rust バックエンドでは:

    binder::ProcessState::start_thread_pool();
    binder::add_service(“myservice”, my_service_binder).expect(“Failed to register service?”);
    binder::ProcessState::join_thread_pool();

予約名

C++、Java、および Rust では、キーワードとして、または言語固有の使用のためにいくつかの名前が予約されています。 AIDL は言語規則に基づく制限を適用しませんが、予約名と一致するフィールド名または型名を使用すると、C++ または Java のコンパイルが失敗する可能性があります。 Rust の場合、フィールドまたは型は「生の識別子」構文を使用して名前が変更され、 r#プレフィックスを使用してアクセスできます。

非人間工学的なバインディングや完全なコンパイルの失敗を回避するために、可能であれば AIDL 定義で予約済みの名前を使用しないことをお勧めします。

AIDL 定義に予約済みの名前がある場合は、プロトコルの互換性を保ちながらフィールドの名前を安全に変更できます。ビルドを続行するにはコードを更新する必要があるかもしれませんが、既にビルドされたプログラムは引き続き相互運用できます。

避けるべき名前: * C++ キーワード* Java キーワード* Rust キーワード

AIDLバックエンド

ビルドシステム

コアビルドシステム

aidl_interface

タイプ

方向性 (in/out/inout)

UTF8/UTF16

Null可能性

カスタムパーセルブル

デフォルト値

エラー処理

エラーのある出力パラメータ

どのエラー値を使用するか

さまざまなバックエンドの使用

タイプのインポート

サービスの実装

サービスの登録と取得

死へのつながり

発信者情報

サービスのバグ レポートとデバッグ API

インターフェイス記述子を動的に取得する

インターフェイス記述子を静的に取得しています

列挙範囲

スレッド管理

予約名

サービスのバグレポートとデバッグ API