Phần phụ trợ AIDL

Phần phụ trợ AIDL là mục tiêu để tạo mã giả lập. Khi sử dụng tệp AIDL, bạn luôn sử dụng các tệp đó bằng một ngôn ngữ cụ thể với thời gian chạy cụ thể. Tuỳ thuộc vào ngữ cảnh, bạn nên sử dụng các phần phụ trợ AIDL khác nhau.

Trong bảng sau, độ ổn định của giao diện API đề cập đến khả năng biên dịch mã dựa trên giao diện API này theo cách mà mã có thể được phân phối độc lập với tệp nhị phân system.img libbinder.so.

AIDL có các phần phụ trợ sau:

Phần phụ trợ Ngôn ngữ Nền tảng API Hệ thống xây dựng
Java Java SDK/SystemApi (bản ổn định*) tất cả
NDK C++ libbinder_ndk (phiên bản ổn định*) aidl_interface
CPP C++ libbinder (không ổn định) tất cả
Rust Rust libbinder_rs (ổn định*) aidl_interface
  • Các giao diện API này rất ổn định, nhưng nhiều API, chẳng hạn như các API để quản lý dịch vụ, được dành riêng cho việc sử dụng nền tảng nội bộ và không dành cho ứng dụng. Để biết thêm thông tin về cách sử dụng AIDL trong ứng dụng, hãy xem tài liệu dành cho nhà phát triển.
  • Phần phụ trợ Rust được giới thiệu trong Android 12; phần phụ trợ NDK đã có từ Android 10.
  • Hộp Rust được xây dựng dựa trên libbinder_ndk, cho phép hộp này hoạt động ổn định và có thể di chuyển. APEX sử dụng vùng chứa liên kết theo cách tương tự như mọi người khác ở phía hệ thống. Phần Rust được đóng gói vào một APEX và được vận chuyển bên trong APEX đó. Điều này phụ thuộc vào libbinder_ndk.so trên phân vùng hệ thống.

Hệ thống xây dựng

Tuỳ thuộc vào phần phụ trợ, có hai cách để biên dịch AIDL thành mã giả lập. Để biết thêm thông tin chi tiết về các hệ thống xây dựng, hãy xem Tài liệu tham khảo về mô-đun Soong.

Hệ thống xây dựng cốt lõi

Trong mọi mô-đun Android.bp cc_ hoặc java_ (hoặc trong các mô-đun tương đương Android.mk), bạn có thể chỉ định tệp .aidl làm tệp nguồn. Trong trường hợp này, phần phụ trợ Java/CPP của AIDL được sử dụng (không phải phần phụ trợ NDK) và các lớp để sử dụng tệp AIDL tương ứng sẽ được tự động thêm vào mô-đun. Các tuỳ chọn như local_include_dirs, cho hệ thống xây dựng biết đường dẫn gốc đến các tệp AIDL trong mô-đun đó có thể được chỉ định trong các mô-đun này trong một nhóm aidl:. Xin lưu ý rằng phần phụ trợ Rust chỉ dùng được với Rust. Các mô-đun rust_ được xử lý theo cách khác vì các tệp AIDL không được chỉ định làm tệp nguồn. Thay vào đó, mô-đun aidl_interface sẽ tạo một rustlib có tên là <aidl_interface name>-rust có thể được liên kết. Để biết thêm thông tin, hãy xem ví dụ về Rust AIDL.

aidl_interface

Các loại được sử dụng với hệ thống xây dựng này phải được định cấu trúc. Để có cấu trúc, các đối tượng có thể phân đoạn phải chứa các trường trực tiếp và không phải là nội dung khai báo của các loại được xác định trực tiếp trong ngôn ngữ mục tiêu. Để biết cách AIDL có cấu trúc phù hợp với AIDL ổn định, hãy xem phần AIDL có cấu trúc so với AIDL ổn định.

Loại

Bạn có thể xem trình biên dịch aidl là một phương thức triển khai tham chiếu cho các loại. Khi bạn tạo một giao diện, hãy gọi aidl --lang=<backend> ... để xem tệp giao diện thu được. Khi sử dụng mô-đun aidl_interface, bạn có thể xem kết quả trong out/soong/.intermediates/<path to module>/.

Loại Java/AIDL Loại C++ Loại NDK Loại gỉ
boolean bool bool bool
byte8 int8_t int8_t i8
ký tự char16_t char16_t u16
int int32_t int32_t i32
long int64_t int64_t i64
số thực dấu phẩy động số thực dấu phẩy động số thực dấu phẩy động f32
gấp đôi gấp đôi gấp đôi f64
Chuỗi android::String16 std::string Trong: &str
Ra: Chuỗi
android.os.Parcelable android::Parcelable Không áp dụng Không áp dụng
IBinder android::IBinder ndk::SpAIBinder binder::SpIBinder
T[] std::vector<T> std::vector<T> Trong: &[T]
Ra: Vec<T>
byte[] std::vector<uint8_t> std::vector<int8_t>1 Trong: &[u8]
Ra: Vec<u8>
List<T> std::vector<T>2 std::vector<T>3 Trong: &[T]4
Ra: Vec<T>
FileDescriptor android::base::unique_fd Không áp dụng binder::parcel::ParcelFileDescriptor
ParcelFileDescriptor android::os::ParcelFileDescriptor ndk::ScopedFileDescriptor binder::parcel::ParcelFileDescriptor
loại giao diện (T) android::sp<T> std::shared_ptr<T>7 binder::Strong
loại có thể phân phối (T) T5 T5 T5
loại hợp nhất (T)5 T5 T5 T5
T[N] 6 std::array<T, N> std::array<T, N> [T; N]

1. Trong Android 12 trở lên, các mảng byte sử dụng uint8_t thay vì int8_t vì lý do tương thích.

2. Phần phụ trợ C++ hỗ trợ List<T>, trong đó T là một trong các loại String, IBinder, ParcelFileDescriptor hoặc có thể phân phối. Trong Android 13 trở lên, T có thể là bất kỳ loại không phải loại gốc nào (bao gồm cả loại giao diện) ngoại trừ mảng. AOSP đề xuất bạn sử dụng các loại mảng như T[] vì chúng hoạt động trong tất cả các phần phụ trợ.

3. Phần phụ trợ NDK hỗ trợ List<T>, trong đó T là một trong các loại String, ParcelFileDescriptor hoặc có thể phân phối. Trong Android 13 trở lên, T có thể là bất kỳ loại không phải loại gốc nào ngoại trừ mảng.

4. Các loại được truyền theo cách khác nhau cho mã Rust tuỳ thuộc vào việc chúng là dữ liệu đầu vào (đối số) hay dữ liệu đầu ra (giá trị trả về).

5. Các loại liên kết được hỗ trợ trong Android 12 trở lên.

6. Trong Android 13 trở lên, các mảng có kích thước cố định được hỗ trợ. Mảng có kích thước cố định có thể có nhiều phương diện (ví dụ: int[3][4]). Trong phần phụ trợ Java, các mảng có kích thước cố định được biểu thị dưới dạng loại mảng.

7. Để tạo thực thể cho đối tượng liên kết SharedRefBase, hãy sử dụng SharedRefBase::make\<My\>(... args ...). Hàm này tạo một đối tượng std::shared_ptr\<T\> cũng được quản lý nội bộ, trong trường hợp liên kết thuộc sở hữu của một quy trình khác. Việc tạo đối tượng theo cách khác sẽ gây ra tình trạng sở hữu kép.

8. Xem thêm loại Java/AIDL byte[].

Hướng (vào/ra/vào ra)

Khi chỉ định loại đối số cho hàm, bạn có thể chỉ định các đối số đó là in, out hoặc inout. Phương thức này kiểm soát hướng truyền thông tin cho lệnh gọi IPC. in là hướng mặc định và cho biết dữ liệu được truyền từ phương thức gọi đến phương thức được gọi. out có nghĩa là dữ liệu được truyền từ hàm được gọi đến hàm gọi. inout là sự kết hợp của cả hai loại này. Tuy nhiên, nhóm Android khuyên bạn nên tránh sử dụng chỉ định đối số inout. Nếu bạn sử dụng inout với giao diện có phiên bản và đối tượng được gọi cũ, thì các trường bổ sung chỉ có trong phương thức gọi sẽ được đặt lại về giá trị mặc định. Đối với Rust, loại inout thông thường sẽ nhận được &mut Vec<T> và loại danh sách inout sẽ nhận được &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);
}

UTF8/UTF16

Với phần phụ trợ CPP, bạn có thể chọn chuỗi là utf-8 hay utf-16. Khai báo chuỗi dưới dạng @utf8InCpp String trong AIDL để tự động chuyển đổi chuỗi thành utf-8. Phần phụ trợ NDK và Rust luôn sử dụng chuỗi utf-8. Để biết thêm thông tin về chú thích utf8InCpp, hãy xem phần Chú thích trong AIDL.

Tính chất rỗng

Bạn có thể chú thích các loại có thể rỗng bằng @nullable. Để biết thêm thông tin về chú thích nullable, hãy xem phần Chú thích trong AIDL.

Gói tuỳ chỉnh

Gói tuỳ chỉnh là một gói có thể phân phối được triển khai theo cách thủ công trong phần phụ trợ mục tiêu. Chỉ sử dụng các gói có thể phân phối tuỳ chỉnh khi bạn đang cố gắng thêm tính năng hỗ trợ cho các ngôn ngữ khác cho một gói có thể phân phối tuỳ chỉnh hiện có mà không thể thay đổi.

Để khai báo một gói tuỳ chỉnh để AIDL biết về gói đó, nội dung khai báo gói AIDL sẽ có dạng như sau:

    package my.pack.age;
    parcelable Foo;

Theo mặc định, lệnh này khai báo một gói Java, trong đó my.pack.age.Foo là một lớp Java triển khai giao diện Parcelable.

Để khai báo một phần phụ trợ CPP tuỳ chỉnh có thể phân phối trong AIDL, hãy sử dụng cpp_header:

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

Cách triển khai C++ trong my/pack/age/Foo.h sẽ có dạng như sau:

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

Để khai báo một gói NDK tuỳ chỉnh trong AIDL, hãy sử dụng ndk_header:

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

Cách triển khai NDK trong android/pack/age/Foo.h sẽ có dạng như sau:

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

Trong Android 15, để khai báo một Rust tuỳ chỉnh có thể phân đoạn trong AIDL, hãy sử dụng rust_type:

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

Cách triển khai Rust trong rust_crate/src/lib.rs sẽ có dạng như sau:

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

Sau đó, bạn có thể sử dụng gói này làm loại trong tệp AIDL, nhưng AIDL sẽ không tạo gói này. Cung cấp toán tử < và == cho các gói tuỳ chỉnh phần phụ trợ CPP/NDK để sử dụng các toán tử này trong union.

Giá trị mặc định

Các gói có cấu trúc có thể khai báo giá trị mặc định cho mỗi trường cho các loại dữ liệu gốc, String và mảng của các loại này.

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

Trong phần phụ trợ Java khi thiếu giá trị mặc định, các trường được khởi tạo dưới dạng giá trị 0 cho các loại dữ liệu gốc và null cho các loại dữ liệu không phải gốc.

Trong các phần phụ trợ khác, các trường được khởi tạo bằng giá trị khởi tạo mặc định khi giá trị mặc định không được xác định. Ví dụ: trong phần phụ trợ C++, các trường String được khởi tạo dưới dạng một chuỗi trống và các trường List<T> được khởi tạo dưới dạng một vector<T> trống. Các trường @nullable được khởi tạo dưới dạng trường giá trị rỗng.

Liên minh

Các liên kết AIDL được gắn thẻ và các tính năng của chúng tương tự nhau trong tất cả các phần phụ trợ. Các giá trị này được tạo mặc định thành giá trị mặc định của trường đầu tiên và có cách tương tác riêng theo ngôn ngữ.

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

Ví dụ về Java

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

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

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

Ví dụ về C++ và 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)

Ví dụ về Rust

Trong Rust, các liên kết được triển khai dưới dạng enum và không có phương thức getter và setter rõ ràng.

    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

Xử lý lỗi

Hệ điều hành Android cung cấp các loại lỗi tích hợp sẵn để các dịch vụ sử dụng khi báo cáo lỗi. Các dịch vụ này được trình liên kết sử dụng và có thể được sử dụng bởi bất kỳ dịch vụ nào triển khai giao diện liên kết. Cách sử dụng các phương thức này được ghi nhận rõ ràng trong định nghĩa AIDL và các phương thức này không yêu cầu bất kỳ trạng thái hoặc loại dữ liệu trả về nào do người dùng xác định.

Tham số đầu ra có lỗi

Khi một hàm AIDL báo cáo lỗi, hàm đó có thể không khởi chạy hoặc sửa đổi các tham số đầu ra. Cụ thể, các tham số đầu ra có thể được sửa đổi nếu lỗi xảy ra trong quá trình huỷ gói thay vì xảy ra trong quá trình xử lý giao dịch. Nhìn chung, khi nhận được lỗi từ một hàm AIDL, tất cả tham số inout và out cũng như giá trị trả về (hoạt động như một tham số out trong một số phần phụ trợ) sẽ được coi là ở trạng thái không xác định.

Giá trị lỗi cần sử dụng

Bạn có thể sử dụng nhiều giá trị lỗi tích hợp sẵn trong mọi giao diện AIDL, nhưng một số giá trị được xử lý theo cách đặc biệt. Ví dụ: bạn có thể sử dụng EX_UNSUPPORTED_OPERATION và EX_ILLEGAL_ARGUMENT khi chúng mô tả điều kiện lỗi, nhưng không được sử dụng EX_TRANSACTION_FAILED vì lớp này được cơ sở hạ tầng cơ bản xử lý đặc biệt. Hãy xem các định nghĩa cụ thể về phần phụ trợ để biết thêm thông tin về các giá trị tích hợp sẵn này.

Nếu giao diện AIDL yêu cầu các giá trị lỗi bổ sung không thuộc các loại lỗi tích hợp, thì chúng có thể sử dụng lỗi tích hợp đặc biệt dành riêng cho dịch vụ cho phép đưa vào một giá trị lỗi dành riêng cho dịch vụ do người dùng xác định. Những lỗi dành riêng cho dịch vụ này thường được xác định trong giao diện AIDL dưới dạng enum được hỗ trợ bởi const int hoặc int và không được trình liên kết phân tích cú pháp.

Trong Java, lỗi liên kết với các trường hợp ngoại lệ, chẳng hạn như android.os.RemoteException. Đối với các ngoại lệ dành riêng cho dịch vụ, Java sử dụng android.os.ServiceSpecificException cùng với lỗi do người dùng xác định.

Mã gốc trong Android không sử dụng ngoại lệ. Phần phụ trợ CPP sử dụng android::binder::Status. Phần phụ trợ NDK sử dụng ndk::ScopedAStatus. Mọi phương thức do AIDL tạo ra đều trả về một trong những giá trị này, đại diện cho trạng thái của phương thức. Phần phụ trợ Rust sử dụng các giá trị mã ngoại lệ giống như NDK, nhưng chuyển đổi các giá trị đó thành lỗi Rust gốc (StatusCode, ExceptionCode) trước khi phân phối cho người dùng. Đối với các lỗi dành riêng cho dịch vụ, Status hoặc ScopedAStatus được trả về sẽ sử dụng EX_SERVICE_SPECIFIC cùng với lỗi do người dùng xác định.

Bạn có thể tìm thấy các loại lỗi tích hợp sẵn trong các tệp sau:

Phần phụ trợ Định nghĩa
Java android/os/Parcel.java
CPP binder/Status.h
NDK android/binder_status.h
Rust android/binder_status.h

Sử dụng nhiều phần phụ trợ

Những hướng dẫn này dành riêng cho mã nền tảng Android. Các ví dụ này sử dụng một loại đã xác định, my.package.IFoo. Để biết hướng dẫn về cách sử dụng phần phụ trợ Rust, hãy xem ví dụ về Rust AIDL trên trang Mẫu Rust cho Android.

Loại nhập

Cho dù loại được xác định là giao diện, có thể phân phối hay hợp nhất, bạn đều có thể nhập loại đó trong Java:

import my.package.IFoo;

Hoặc trong phần phụ trợ CPP:

#include <my/package/IFoo.h>

Hoặc trong phần phụ trợ NDK (lưu ý thêm không gian tên aidl):

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

Hoặc trong phần phụ trợ Rust:

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

Mặc dù có thể nhập một loại lồng nhau trong Java, nhưng trong phần phụ trợ CPP/NDK, bạn phải đưa tiêu đề vào loại gốc của loại đó. Ví dụ: khi nhập một loại lồng nhau Bar được xác định trong my/package/IFoo.aidl (IFoo là loại gốc của tệp), bạn phải thêm <my/package/IFoo.h> cho phần phụ trợ CPP (hoặc <aidl/my/package/IFoo.h> cho phần phụ trợ NDK).

Triển khai dịch vụ

Để triển khai một dịch vụ, bạn phải kế thừa từ lớp mô phỏng gốc. Lớp này đọc các lệnh từ trình điều khiển liên kết và thực thi các phương thức mà bạn triển khai. Hãy tưởng tượng bạn có một tệp AIDL như sau:

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

Trong Java, bạn phải mở rộng từ lớp này:

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

Trong phần phụ trợ CPP:

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

Trong phần phụ trợ NDK (lưu ý thêm không gian tên aidl):

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

Trong phần phụ trợ 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(())
        }
    }

Hoặc với Rust không đồng bộ:

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

Đăng ký và sử dụng dịch vụ

Các dịch vụ trong nền tảng Android thường được đăng ký bằng quy trình servicemanager. Ngoài các API bên dưới, một số API sẽ kiểm tra dịch vụ (nghĩa là các API này sẽ trả về ngay lập tức nếu không có dịch vụ). Hãy kiểm tra giao diện servicemanager tương ứng để biết thông tin chi tiết chính xác. Bạn chỉ có thể thực hiện các thao tác này khi biên dịch theo nền tảng Android.

Trong 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"));

Trong phần phụ trợ 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"));

Trong phần phụ trợ NDK (lưu ý thêm không gian tên 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")));

Trong phần phụ trợ 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()
}

Trong phần phụ trợ Rust không đồng bộ, với thời gian chạy một luồng:

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 will run on this thread.
    std::future::pending().await
}

Một điểm khác biệt quan trọng so với các tuỳ chọn khác là chúng ta không gọi join_thread_pool khi sử dụng Rust không đồng bộ và thời gian chạy đơn luồng. Lý do là bạn cần cung cấp cho Tokio một luồng để thực thi các tác vụ được tạo. Trong ví dụ này, luồng chính sẽ phục vụ mục đích đó. Mọi tác vụ được tạo bằng tokio::spawn sẽ thực thi trên luồng chính.

Trong phần phụ trợ Rust không đồng bộ, với thời gian chạy nhiều luồng:

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

Với môi trường thời gian chạy Tokio đa luồng, các tác vụ được tạo không thực thi trên luồng chính. Do đó, bạn nên gọi join_thread_pool trên luồng chính để luồng chính không chỉ ở trạng thái rảnh. Bạn phải gói lệnh gọi trong block_in_place để rời khỏi ngữ cảnh không đồng bộ.

Bạn có thể yêu cầu nhận thông báo khi một dịch vụ lưu trữ liên kết bị lỗi. Điều này có thể giúp tránh rò rỉ proxy lệnh gọi lại hoặc hỗ trợ khôi phục lỗi. Thực hiện các lệnh gọi này trên đối tượng proxy liên kết.

  • Trong Java, hãy sử dụng android.os.IBinder::linkToDeath.
  • Trong phần phụ trợ CPP, hãy sử dụng android::IBinder::linkToDeath.
  • Trong phần phụ trợ NDK, hãy sử dụng AIBinder_linkToDeath.
  • Trong phần phụ trợ Rust, hãy tạo một đối tượng DeathRecipient, sau đó gọi my_binder.link_to_death(&mut my_death_recipient). Xin lưu ý rằng vì DeathRecipient sở hữu lệnh gọi lại, nên bạn phải duy trì đối tượng đó miễn là bạn muốn nhận thông báo.

Thông tin về người gọi

Khi nhận được lệnh gọi liên kết hạt nhân, thông tin về phương thức gọi sẽ có trong một số API. PID (hoặc Mã nhận dạng quy trình) là mã nhận dạng quy trình Linux của quy trình đang gửi giao dịch. UID (hoặc Mã nhận dạng người dùng) đề cập đến mã nhận dạng người dùng Linux. Khi nhận được lệnh gọi một chiều, PID gọi là 0. Khi nằm ngoài ngữ cảnh giao dịch liên kết, các hàm này sẽ trả về PID và UID của quy trình hiện tại.

Trong phần phụ trợ Java:

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

Trong phần phụ trợ CPP:

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

Trong phần phụ trợ NDK:

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

Trong phần phụ trợ Rust, khi triển khai giao diện, hãy chỉ định nội dung sau (thay vì cho phép giao diện mặc định):

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

Báo cáo lỗi và API gỡ lỗi cho các dịch vụ

Khi chạy báo cáo lỗi (ví dụ: với adb bugreport), các báo cáo này sẽ thu thập thông tin từ khắp hệ thống để hỗ trợ gỡ lỗi nhiều vấn đề. Đối với các dịch vụ AIDL, báo cáo lỗi sử dụng tệp nhị phân dumpsys trên tất cả các dịch vụ được đăng ký với trình quản lý dịch vụ để kết xuất thông tin của các dịch vụ đó vào báo cáo lỗi. Bạn cũng có thể sử dụng dumpsys trên dòng lệnh để lấy thông tin từ một dịch vụ có dumpsys SERVICE [ARGS]. Trong phần phụ trợ C++ và Java, bạn có thể kiểm soát thứ tự các dịch vụ được kết xuất bằng cách sử dụng các đối số bổ sung cho addService. Bạn cũng có thể sử dụng dumpsys --pid SERVICE để lấy PID của một dịch vụ trong khi gỡ lỗi.

Để thêm đầu ra tuỳ chỉnh vào dịch vụ, bạn có thể ghi đè phương thức dump trong đối tượng máy chủ như đang triển khai bất kỳ phương thức IPC nào khác được xác định trong tệp AIDL. Khi thực hiện việc này, bạn nên hạn chế việc kết xuất vào quyền ứng dụng android.permission.DUMP hoặc hạn chế việc kết xuất vào các UID cụ thể.

Trong phần phụ trợ Java:

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

Trong phần phụ trợ CPP:

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

Trong phần phụ trợ NDK:

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

Trong phần phụ trợ Rust, khi triển khai giao diện, hãy chỉ định nội dung sau (thay vì cho phép giao diện mặc định):

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

Sử dụng con trỏ yếu

Bạn có thể giữ một tham chiếu yếu đến đối tượng liên kết.

Mặc dù Java hỗ trợ WeakReference, nhưng không hỗ trợ các tệp tham chiếu liên kết yếu ở lớp gốc.

Trong phần phụ trợ CPP, loại yếu là wp<IFoo>.

Trong phần phụ trợ NDK, hãy sử dụng ScopedAIBinder_Weak:

#include <android/binder_auto_utils.h>

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

Trong phần phụ trợ Rust, bạn sử dụng WpIBinder hoặc Weak<IFoo>:

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

Tự động lấy chỉ số mô tả giao diện

Chỉ số giao diện xác định loại giao diện. Điều này rất hữu ích khi gỡ lỗi hoặc khi bạn có một liên kết không xác định.

Trong Java, bạn có thể lấy chỉ số mô tả giao diện bằng mã như sau:

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

Trong phần phụ trợ CPP:

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

Phần phụ trợ NDK và Rust không hỗ trợ chức năng này.

Lấy mô tả giao diện một cách tĩnh

Đôi khi (chẳng hạn như khi đăng ký dịch vụ @VintfStability), bạn cần biết mô tả giao diện là gì một cách tĩnh. Trong Java, bạn có thể lấy mô tả bằng cách thêm mã như:

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

Trong phần phụ trợ CPP:

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

Trong phần phụ trợ NDK (lưu ý thêm không gian tên aidl):

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

Trong phần phụ trợ Rust:

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

Dải ô enum

Trong phần phụ trợ gốc, bạn có thể lặp lại các giá trị có thể có của một enum. Do cân nhắc về kích thước mã, tính năng này không được hỗ trợ trong Java.

Đối với một enum MyEnum được xác định trong AIDL, quá trình lặp lại được cung cấp như sau.

Trong phần phụ trợ CPP:

    ::android::enum_range<MyEnum>()

Trong phần phụ trợ NDK:

   ::ndk::enum_range<MyEnum>()

Trong phần phụ trợ Rust:

    MyEnum::enum_values()

Quản lý luồng

Mỗi thực thể của libbinder trong một quy trình duy trì một nhóm luồng. Đối với hầu hết các trường hợp sử dụng, đây phải là một nhóm luồng chính xác, được chia sẻ trên tất cả các phần phụ trợ. Ngoại lệ duy nhất là khi mã của nhà cung cấp có thể tải một bản sao khác của libbinder để giao tiếp với /dev/vndbinder. Vì nằm trên một nút liên kết riêng biệt, nên nhóm luồng không được chia sẻ.

Đối với phần phụ trợ Java, nhóm luồng chỉ có thể tăng kích thước (vì đã bắt đầu):

    BinderInternal.setMaxThreads(<new larger value>);

Đối với phần phụ trợ CPP, bạn có thể thực hiện các thao tác sau:

    // 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();

Tương tự như vậy, trong phần phụ trợ NDK:

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

Trong phần phụ trợ Rust:

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

Với phần phụ trợ Rust không đồng bộ, bạn cần có hai nhóm luồng: liên kết và Tokio. Điều này có nghĩa là các ứng dụng sử dụng Rust không đồng bộ cần được cân nhắc đặc biệt, đặc biệt là khi sử dụng join_thread_pool. Hãy xem phần về việc đăng ký dịch vụ để biết thêm thông tin về vấn đề này.

Tên dành riêng

C++, Java và Rust dành riêng một số tên làm từ khoá hoặc để sử dụng theo ngôn ngữ cụ thể. Mặc dù AIDL không thực thi các quy định hạn chế dựa trên quy tắc ngôn ngữ, nhưng việc sử dụng tên trường hoặc tên loại khớp với tên được đặt trước có thể dẫn đến lỗi biên dịch cho C++ hoặc Java. Đối với Rust, trường hoặc loại được đổi tên bằng cú pháp "giá trị nhận dạng thô", có thể truy cập bằng tiền tố r#.

Bạn nên tránh sử dụng tên được đặt trước trong định nghĩa AIDL nếu có thể để tránh các liên kết không hợp lý hoặc lỗi biên dịch hoàn toàn.

Nếu đã đặt tên riêng trong các định nghĩa AIDL, bạn có thể đổi tên các trường một cách an toàn mà vẫn tương thích với giao thức; bạn có thể cần cập nhật mã để tiếp tục xây dựng, nhưng mọi chương trình đã tạo sẽ tiếp tục tương tác.

Những tên nên tránh: