AIDL 後端

AIDL 後端是輔助程式程式碼產生的目標。請務必使用特定語言和特定執行階段的 AIDL 檔案。請根據情境使用不同的 AIDL 後端。

在下表中，API 途徑的穩定性是指針對此 API 途徑編譯程式碼的能力，以便程式碼可獨立於 system.img libbinder.so 二進位檔提供。

AIDL 有下列後端：

後端 語言 API 介面 建構系統
Java Java SDK 或 SystemApi (穩定版*) 全部
NDK C++ libbinder_ndk (穩定版*) aidl_interface
CPP C++ libbinder (不穩定) 全部
Rust Rust libbinder_rs (穩定版*) aidl_interface
  • 這些 API 途徑穩定可靠，但許多 API (例如服務管理 API) 僅供內部平台使用，無法供應用程式使用。如要進一步瞭解如何在應用程式中使用 AIDL，請參閱「Android 介面定義語言 (AIDL)」。
  • Rust 後端是在 Android 12 中推出；NDK 後端則是在 Android 10 中推出。
  • Rust 套件是建構於 libbinder_ndk 之上，因此可提供穩定且可移植的功能。APEX 會在系統端以標準方式使用繫結器 Crate。Rust 部分會整合至 APEX，並透過 APEX 發布。這部分取決於系統分區的 libbinder_ndk.so。

建構系統

視後端而定，將 AIDL 編譯為 Stub 程式碼的方法有兩種。如要進一步瞭解建構系統，請參閱 Soong 模組參考資料。

核心建構系統

在任何 cc_ 或 java_ Android.bp module (或其 Android.mk 等同物) 中，您可以將 AIDL (.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_interface 建構系統使用的類型必須有結構。為了符合結構化規定，Parcelable 必須直接包含欄位，而非在目標語言中直接定義的型別宣告。如要瞭解結構化 AIDL 如何與穩定版 AIDL 搭配，請參閱「結構化 AIDL 與穩定版 AIDL」。

類型

請將 aidl 編譯器視為類型的參考實作項目。建立介面時，請叫用 aidl --lang=<backend> ... 來查看產生的介面檔案。使用 aidl_interface 模組時，您可以在 out/soong/.intermediates/<path to module>/ 中查看輸出內容。

Java 或 AIDL 類型 C++ 類型 NDK 類型 Rust 類型
boolean bool bool bool
byte8 int8_t int8_t i8
char char16_t char16_t u16
int int32_t int32_t i32
long int64_t int64_t i64
float float float f32
double double double f64
String android::String16 std::string 進：&str
出：String
android.os.Parcelable android::Parcelable 無 無
IBinder android::IBinder ndk::SpAIBinder binder::SpIBinder
T[] std::vector<T> std::vector<T> 進：&[T]
出：Vec<T>
byte[] std::vector std::vector1 進：&[u8]
出：Vec<u8>
List<T> std::vector<T>2 std::vector<T>3 輸入：In: &[T]4
輸出：Vec<T>
FileDescriptor android::base::unique_fd 無 無
ParcelFileDescriptor android::os::ParcelFileDescriptor ndk::ScopedFileDescriptor binder::parcel::ParcelFileDescriptor
介面類型 (T) android::sp<T> std::shared_ptr<T>7 binder::Strong
Parcelable 類型 (T) T T T
聯集類型 (T)5 T T T
T[N]6 std::array<T, N> std::array<T, N> [T; N]

1. 基於相容性考量，在 Android 12 以上版本中，位元組陣列會使用 uint8_t 而非 int8_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. Android 12 以上版本支援聯集類型。

6. 在 Android 13 以上版本中，系統支援固定大小的陣列。固定大小陣列可包含多個維度 (例如 int[3][4])。在 Java 後端中，固定大小陣列會以陣列類型表示。

7. 如要將繫結器 SharedRefBase 物件例項化，請使用 SharedRefBase::make\<My\>(... args ...)。此函式會建立 std::shared_ptr\<T\> 物件，並在繫結器由其他程序擁有時，在內部管理該物件。透過其他方式建立物件會導致雙重擁有權。

8. 另請參閱 Java 或 AIDL 類型 byte[]。

方向性 (in、out 和 inout)

指定函式引數類型時，您可以將其指定為 in、out 或 inout。這項屬性可控管 IPC 呼叫傳遞資訊的方向。

  • in 引數指定符表示資料是從呼叫端傳遞至被呼叫端。in 指定符是預設方向，但如果資料類型也可能是 out，則必須指定方向。

  • out 引數指定符表示資料會從呼叫端傳遞至呼叫端。

  • inout 引數指定符是這兩者的組合。不過，我們建議您避免使用引數指定符 inout。如果您將 inout 與版本化介面和較舊的 callee 搭配使用，則只有在呼叫端中顯示的其他欄位會重設為預設值。就 Rust 而言，一般 inout 類型會接收 &mut T，清單 inout 類型則會接收 &mut Vec<T>。

interface IRepeatExamples {
    MyParcelable RepeatParcelable(MyParcelable token); // implicitly 'in'
    MyParcelable RepeatParcelableWithIn(in MyParcelable token);
    void RepeatParcelableWithInAndOut(in MyParcelable param, out MyParcelable result);
    void RepeatParcelableWithInOut(inout MyParcelable param);
}

UTF-8 和 UTF-16

使用 CPP 後端時，您可以選擇字串為 UTF-8 或 UTF-16。在 AIDL 中將字串宣告為 @utf8InCpp String，即可自動將字串轉換為 UTF-8。NDK 和 Rust 後端一律使用 UTF-8 字串。如要進一步瞭解 utf8InCpp 註解，請參閱 utf8InCpp。

是否可為空值

您可以使用 @nullable 為可為空值的類型加上註解。如要進一步瞭解 nullable 註解，請參閱「nullable」。

自訂 Parcelable

自訂 parcelable 是指在目標後端手動實作的 parcelable。只有在您嘗試為無法變更的現有自訂可封裝物新增其他語言支援時，才使用自訂可封裝物。

以下是 AIDL 可分割宣告的範例：

    package my.pack.age;
    parcelable Foo;

根據預設，這會宣告 Java 可分割的類別，其中 my.pack.age.Foo 是實作 Parcelable 介面的 Java 類別。

如要在 AIDL 中宣告可分割的自訂 CPP 後端，請使用 cpp_header：

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

my/pack/age/Foo.h 中的 C++ 實作方式如下所示：

    #include <binder/Parcelable.h>

    class MyCustomParcelable : public android::Parcelable {
    public:
        status_t writeToParcel(Parcel* parcel) const override;
        status_t readFromParcel(const Parcel* parcel) override;

        std::string toString() const;
        friend bool operator==(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
        friend bool operator!=(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
    };

如要在 AIDL 中宣告自訂 NDK 可分割的項目，請使用 ndk_header：

    package my.pack.age;
    parcelable Foo ndk_header "android/pack/age/Foo.h";

android/pack/age/Foo.h 中的 NDK 實作方式如下所示：

    #include <android/binder_parcel.h>

    class MyCustomParcelable {
    public:

        binder_status_t writeToParcel(AParcel* _Nonnull parcel) const;
        binder_status_t readFromParcel(const AParcel* _Nonnull parcel);

        std::string toString() const;

        friend bool operator==(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
        friend bool operator!=(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
    };

在 Android 15 中，如要在 AIDL 中宣告自訂 Rust 可分割項目，請使用 rust_type：

package my.pack.age;
@RustOnlyStableParcelable parcelable Foo rust_type "rust_crate::Foo";

rust_crate/src/lib.rs 中的 Rust 實作內容如下所示：

use binder::{
    binder_impl::{BorrowedParcel, UnstructuredParcelable},
    impl_deserialize_for_unstructured_parcelable, impl_serialize_for_unstructured_parcelable,
    StatusCode,
};

#[derive(Clone, Debug, Eq, PartialEq)]
struct Foo {
    pub bar: String,
}

impl UnstructuredParcelable for Foo {
    fn write_to_parcel(&self, parcel: &mut BorrowedParcel) -> Result<(), StatusCode> {
        parcel.write(&self.bar)?;
        Ok(())
    }

    fn from_parcel(parcel: &BorrowedParcel) -> Result<Self, StatusCode> {
        let bar = parcel.read()?;
        Ok(Self { bar })
    }
}

impl_deserialize_for_unstructured_parcelable!(Foo);
impl_serialize_for_unstructured_parcelable!(Foo);

接著，您可以將這個可分割的類型用於 AIDL 檔案，但 AIDL 不會產生這個類型。為 CPP 和 NDK 後端自訂 parcelable 提供 < 和 == 運算子，以便在 union 中使用。

預設值

結構化 parcelable 可為原始值、String 欄位和這些類型的陣列宣告每個欄位的預設值。

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

在 Java 後端，如果缺少預設值，欄位會初始化為原始類型的零值，非原始類型則為 null。

在其他後端中，如果未定義預設值，系統會使用預設初始化值初始化欄位。舉例來說，在 C++ 後端中，String 欄位會初始化為空字串，而 List<T> 欄位會初始化為空白 vector<T>。@nullable 欄位會初始化為空值欄位。

聯合體

AIDL 聯集會加上標記，且在所有後端的功能都類似。這些值會根據第一個欄位的預設值建構，並提供特定語言的互動方式：

    union Foo {
      int intField;
      long longField;
      String stringField;
      MyParcelable parcelableField;
      ...
    }

Java 範例

    Foo u = Foo.intField(42);              // construct

    if (u.getTag() == Foo.intField) {      // tag query
      // use u.getIntField()               // getter
    }

    u.setSringField("abc");                // setter

C++ 和 NDK 範例

    Foo u;                                            // default constructor

    assert (u.getTag() == Foo::intField);             // tag query
    assert (u.get<Foo::intField>() == 0);             // getter

    u.set<Foo::stringField>("abc");                   // setter

    assert (u == Foo::make<Foo::stringField>("abc")); // make<tag>(value)

Rust 範例

在 Rust 中，union 會以列舉的形式實作，且沒有明確的 getter 和 setter。

    let mut u = Foo::Default();              // default constructor
    match u {                                // tag match + get
      Foo::IntField(x) => assert!(x == 0);
      Foo::LongField(x) => panic!("Default constructed to first field");
      Foo::StringField(x) => panic!("Default constructed to first field");
      Foo::ParcelableField(x) => panic!("Default constructed to first field");
      ...
    }
    u = Foo::StringField("abc".to_string()); // set

處理錯誤

Android 作業系統提供內建錯誤類型，供服務在回報錯誤時使用。這些類別由 Binder 使用，且可供實作 Binder 介面的任何服務使用。這些元素的用途已在 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 和使用者定義的錯誤。

您可以在下列檔案中找到內建錯誤類型：

後端 定義
Java android/os/Parcel.java
CPP binder/Status.h
NDK android/binder_status.h
Rust android/binder_status.h

使用各種後端

以下操作說明適用於 Android 平台程式碼。這些範例使用已定義的類型 my.package.IFoo。如需使用 Rust 後端的操作說明，請參閱「Android Rust 模式」中的 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 中定義的巢狀型別 Bar (IFoo 是檔案的根型別) 時，您必須為 CPP 後端加入 <my/package/IFoo.h> (或 NDK 後端的 <aidl/my/package/IFoo.h>)。

實作介面

如要實作介面，您必須繼承原生存根節點類別。當介面實作項目註冊至服務管理員或 android.app.ActivityManager 時，通常會稱為「服務」；如果是由服務的用戶端註冊，則會稱為「回呼」。不過，視實際用途而定，您可以使用各種名稱來描述介面實作方式。輔助程式類別會讀取繫結器驅動程式的指令，並執行您實作的程式。假設您有以下 AIDL 檔案：

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

在 Java 中，您必須從產生的 Stub 類別擴充：

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

或使用非同步 Rust：

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

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

    impl Interface for MyFoo {}

    #[async_trait]
    impl IFooAsyncServer for MyFoo {
        async 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
    binder_exception_t err = AServiceManager_addService(myService->asBinder().get(), "service-name");
    // return if service is started now
    myService = IFoo::fromBinder(ndk::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(ndk::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()
}

在非同步 Rust 後端中，使用單執行緒的執行階段：

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

#[tokio::main(flavor = "current_thread")]
async fn main() {
    binder::ProcessState::start_thread_pool();
    // [...]
    let my_service = MyFoo;
    let my_service_binder = BnFoo::new_async_binder(
        my_service,
        TokioRuntime(Handle::current()),
        BinderFeatures::default(),
    );

    binder::add_service("myservice", my_service_binder).expect("Failed to register service?");

    // Sleeps forever, but does not join the binder threadpool.
    // Spawned tasks run on this thread.
    std::future::pending().await
}

與其他選項的一個重要差異是，使用非同步 Rust 和單執行緒執行階段時，您不呼叫 join_thread_pool。這是因為您需要為 Tokio 提供執行緒，讓其執行產生的任務。在以下範例中，主執行緒可用於此用途。使用 tokio::spawn 衍生的任何工作都會在主執行緒上執行。

在非同步 Rust 後端中，使用多執行緒執行階段：

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

#[tokio::main(flavor = "multi_thread", worker_threads = 2)]
async fn main() {
    binder::ProcessState::start_thread_pool();
    // [...]
    let my_service = MyFoo;
    let my_service_binder = BnFoo::new_async_binder(
        my_service,
        TokioRuntime(Handle::current()),
        BinderFeatures::default(),
    );

    binder::add_service("myservice", my_service_binder).expect("Failed to register service?");

    // Sleep forever.
    tokio::task::block_in_place(|| {
        binder::ProcessState::join_thread_pool();
    });
}

使用多執行緒 Tokio 執行階段時，產生的作業不會在主執行緒上執行。因此，在主執行緒上呼叫 join_thread_pool 會更有意義，這樣主執行緒就不會閒置。您必須在 block_in_place 中包裝呼叫，才能離開非同步內容。

您可以要求在代管繫結器的服務終止時收到通知。這有助於避免回呼 Proxy 外洩，或協助復原錯誤。對繫結器代理程式物件發出這些呼叫。

  • 在 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 中取得呼叫端資訊。程序 ID (PID) 是指傳送交易的程序的 Linux 程序 ID。使用者 ID (UI) 是指 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。

如要為服務新增自訂輸出內容，請在伺服器物件中覆寫 dump 方法，就像實作 AIDL 檔案中定義的任何其他 IPC 方法一樣。執行此操作時，請將傾印作業限制在應用程式權限 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<()>

使用弱指標

您可以保留對 Binder 物件的弱參照。

雖然 Java 支援 WeakReference，但不支援原生層級的弱式繫結器參照。

在 CPP 後端中，弱型別為 wp<IFoo>。

在 NDK 後端中，請使用 ScopedAIBinder_Weak：

#include <android/binder_auto_utils.h>

AIBinder* binder = ...;
ScopedAIBinder_Weak myWeakReference = ScopedAIBinder_Weak(AIBinder_Weak_new(binder));

在 Rust 後端中，請使用 WpIBinder 或 Weak<IFoo>：

let weak_interface = myIface.downgrade();
let weak_binder = myIface.as_binder().downgrade();

動態取得介面描述元

介面描述項可識別介面類型。這在偵錯或使用不明繫結器時特別實用。

在 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_values()

執行緒管理

程序中的每個 libbinder 例項都會維護一個執行緒集區。對於大多數用途而言，這應該是單一執行緒集區，並在所有後端共用。唯一的例外狀況是，供應商程式碼會載入另一個 libbinder 副本，以便與 /dev/vndbinder 通訊。這會在獨立的繫結器節點上執行，因此不會共用執行緒集區。

對於 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();

使用非同步 Rust 後端時，您需要兩個執行緒集區：Binder 和 Tokio。這表示使用非同步 Rust 的應用程式需要特別考量，尤其是在使用 join_thread_pool 時。詳情請參閱註冊服務相關章節。

保留名稱

C++、Java 和 Rust 會將某些名稱保留為關鍵字，或供特定語言使用。雖然 AIDL 不會根據語言規則強制執行限制，但如果使用與保留名稱相符的欄位或類型名稱，可能會導致 C++ 或 Java 的編譯失敗。針對 Rust，欄位或類型的重新命名會使用原始 ID 語法，可透過 r# 前置字串存取。

建議您盡量避免在 AIDL 定義中使用保留名稱，以免產生不符合人體工學的繫結或完全編譯失敗。

如果 AIDL 定義中已有保留名稱，您可以放心重新命名欄位，同時保持與通訊協定相容。您可能需要更新程式碼才能繼續建構，但任何已建構的程式都會繼續互通。

應避免使用的名稱：