Бэкэнды AIDL

Серверная часть AIDL является целью для генерации кода-заглушки. При использовании файлов AIDL вы всегда используете их на определенном языке с определенной средой выполнения. В зависимости от контекста вам следует использовать разные серверные части AIDL.

AIDL имеет следующие серверные части:

Бэкэнд	Язык	поверхность API	Системы сборки
Джава	Джава	SDK/SystemApi (стабильная*)	все
НДК	С++	libbinder_ndk (стабильная*)	helpl_interface
CPP	С++	libbinder (нестабильный)	все
Ржавчина	Ржавчина	libbinder_rs (нестабильная)	helpl_interface

• Эти поверхности API стабильны, но многие из API, например для управления службами, зарезервированы для внутреннего использования платформы и недоступны приложениям. Дополнительную информацию о том, как использовать AIDL в приложениях, см. в документации для разработчиков .
• Бэкэнд Rust был представлен в Android 12; Серверная часть NDK доступна начиная с Android 10.
• Крейт Rust построен на основе libbinder_ndk . APEX используют ящик для подшивок так же, как и все остальные на стороне системы. Часть Rust упакована в APEX и поставляется внутри него. Это зависит от libbinder_ndk.so в системном разделе.

Системы сборки

В зависимости от серверной части существует два способа компиляции AIDL в код-заглушку. Более подробную информацию о системах сборки см. в справочнике по модулю Soong .

Основная система сборки

В любом модуле cc_ или java_ Android.bp (или их эквивалентах Android.mk ) файлы .aidl могут быть указаны в качестве исходных файлов. В этом случае используются серверные части AIDL Java/CPP (а не серверные части NDK), а классы для использования соответствующих файлов AIDL добавляются в модуль автоматически. Такие параметры, как local_include_dirs , который сообщает системе сборки корневой путь к файлам AIDL в этом модуле, могут быть указаны в этих модулях в группе aidl: Обратите внимание, что серверная часть Rust предназначена только для использования с Rust. Модули rust_ обрабатываются по-другому: файлы AIDL не указываются в качестве исходных файлов. Вместо этого модуль aidl_interface создает rustlib под названием <aidl_interface name>-rust , с которой можно скомпоноваться. Подробнее см. пример Rust AIDL .

Предупреждение. В версии 13 и ниже бэкэнд NDK компилируется только со слабыми символами и требует установки __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ . В системе сборки платформы Android это определение установлено по умолчанию.

helpl_interface

Типы, используемые в этой системе сборки, должны быть структурированы. Чтобы быть структурированными, посылки должны содержать поля напрямую, а не быть объявлениями типов, определенных непосредственно в целевых языках. О том, как структурированный AIDL сочетается со стабильным AIDL, см. в разделе Структурированный и стабильный AIDL .

Типы

Компилятор aidl можно рассматривать как эталонную реализацию типов. Когда вы создаете интерфейс, вызовите aidl --lang=<backend> ... , чтобы просмотреть полученный файл интерфейса. Когда вы используете модуль aidl_interface , вы можете просмотреть выходные данные в out/soong/.intermediates/<path to module>/ .

Тип Java/AIDL	Тип С++	Тип НДК	Тип ржавчины
логическое значение	логическое значение	логическое значение	логическое значение
байт	int8_t	int8_t	i8
голец	char16_t	char16_t	u16
интервал	int32_t	int32_t	я32
длинный	int64_t	int64_t	я64
плавать	плавать	плавать	ф32
двойной	двойной	двойной	ф64
Нить	андроид::String16	станд::строка	Нить
android.os.Parcelable	Android::Parcelable	Н/Д	Н/Д
IBinder	Android::IBinder	ndk::SpAIBinder	связыватель::SpIBinder
Т[]	std::vector<T>	std::vector<T>	В: &[Т] Вышел: Век<T>
байт[]	std::vector<uint8_t>	std::vector<int8_t> ^1	В: &[u8] Вышел: Век<u8>
Список<T>	std::vector<T> ^2	std::vector<T> ^3	Вышел: &[T] ^4 Вышел: Век<T>
Файловыйдескриптор	Android::base::unique_fd	Н/Д	связыватель::посылка::ParcelFileDescriptor
Дескриптор файла посылки	android::os::ParcelFileDescriptor	ndk::ScopedFileDescriptor	связыватель::посылка::ParcelFileDescriptor
тип интерфейса (Т)	андроид::sp<T>	std::shared_ptr<T>	связующее::Сильный
парцеллируемый тип (Т)	Т	Т	Т
тип соединения (Т) ^5	Т	Т	Т
Т[Н] ^6	std::array<T, N>	std::array<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 массивы фиксированного размера представлены как типы массивов.}

Направленность (внутрь/наружу/внутри)

При указании типов аргументов функций вы можете указать их как 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. Объявляйте строки как @utf8InCpp String в AIDL, чтобы автоматически преобразовать их в utf-8. Серверные части NDK и Rust всегда используют строки utf-8. Дополнительные сведения об аннотации utf8InCpp см. в разделе Аннотации в AIDL .

Обнуляемость

Вы можете аннотировать типы, которые могут иметь значение NULL в серверной части Java, с помощью @nullable , чтобы предоставлять нулевые значения серверным модулям CPP и NDK. В бэкэнде Rust эти типы @nullable представлены как Option<T> . Собственные серверы по умолчанию отклоняют нулевые значения. Единственными исключениями из этого правила являются типы interface и IBinder , которые всегда могут иметь значение null для чтения NDK и записи CPP/NDK. Дополнительные сведения об аннотации, nullable , см. в разделе Аннотации в AIDL .

Предупреждение: берегитесь непредвиденных значений. Даже если ваш клиент/сервер всегда передает ненулевое значение, ввод должен быть проверен на случай вредоносного клиента или, в некоторых случаях, на наличие значений, которые становятся нулевыми. Например, в серверной части NDK тип интерфейса может отображаться как нулевой, если его хост-процесс завершает работу во время транзакции.

Пользовательские посылки

Пользовательский объект — это объект, который вручную реализуется в целевой серверной части. Используйте пользовательские участки только в том случае, если вы пытаетесь добавить поддержку других языков для существующего пользовательского участка, который нельзя изменить.

Предупреждение. Пользовательские Parcelables подвержены ошибкам. При создании нового участка вам следует использовать структурированные участки AIDL. Пользовательские Parcelables должны быть реализованы в каждом бэкэнде отдельно, и они могут быть не синхронизированы или иметь другие проблемы. В случае сомнений используйте структурированный пакет AIDL.

Чтобы объявить пользовательскую посылку, чтобы AIDL знал о ней, объявление AIDL посылки выглядит следующим образом:

    package my.pack.age;
    parcelable Foo;

По умолчанию здесь объявляется пакетный объект Java, где my.pack.age.Foo — это класс Java, реализующий интерфейс Parcelable .

Для объявления пользовательского бэкэнда CPP, который можно упаковать в AIDL, используйте cpp_header :

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

Реализация C++ в my/pack/age/Foo.h выглядит следующим образом:

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

Для объявления пользовательского NDK, подлежащего пакетированию в AIDL, используйте ndk_header :

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

Реализация NDK в android/pack/age/Foo.h выглядит следующим образом:

    #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 (экспериментальная AOSP) для объявления пользовательского пакета Rust в AIDL используйте rust_type :

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

Реализация Rust в rust_crate/src/lib.rs выглядит следующим образом:

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, чтобы использовать их в union .

Предупреждение: Пользовательские Parcelables должны быть окончательными. Пользовательские Parcelables в Java и C++ должны быть окончательными. Если подкласс посылки отправляется как суперкласс, то базовый формат не соответствует. Родительский класс, который можно разделить, должен будет закодировать, как подклассы записываются в участок. Самое простое решение — избегать создания подклассов посылки. Вместо этого используйте композицию.

Значения по умолчанию

Структурированные посылки могут объявлять значения по умолчанию для каждого поля для примитивов, String и массивов этих типов.

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

В серверной части Java, когда значения по умолчанию отсутствуют, поля инициализируются как нулевые значения для примитивных типов и null для непримитивных типов.

В других бэкэндах поля инициализируются значениями по умолчанию, если значения по умолчанию не определены. Например, в серверной части C++ поля String инициализируются как пустая строка, а поля List<T> инициализируются как пустой vector<T> . Поля @nullable инициализируются как поля с нулевым значением.

Обработка ошибок

ОС Android предоставляет встроенные типы ошибок, которые службы могут использовать при сообщении об ошибках. Они используются связующим и могут использоваться любыми службами, реализующими интерфейс связующего. Их использование хорошо документировано в определении AIDL, и они не требуют какого-либо определяемого пользователем статуса или типа возвращаемого значения.

Выходные параметры с ошибками

Когда функция AIDL сообщает об ошибке, функция не может инициализировать или изменить выходные параметры. В частности, выходные параметры могут быть изменены, если ошибка возникает во время распаковки, а не во время обработки самой транзакции. В общем, при получении ошибки от функции AIDL все inout и out параметры, а также возвращаемое значение (которое в некоторых бэкэндах действует как out параметр) следует считать находящимися в неопределенном состоянии.

Какие значения ошибок использовать

Многие из встроенных значений ошибок можно использовать в любых интерфейсах AIDL, но некоторые обрабатываются особым образом. Например, EX_UNSUPPORTED_OPERATION и EX_ILLEGAL_ARGUMENT можно использовать, когда они описывают состояние ошибки, но EX_TRANSACTION_FAILED нельзя использовать, поскольку базовая инфраструктура рассматривает его как особый. Дополнительную информацию об этих встроенных значениях см. в определениях серверной части.

Если интерфейс AIDL требует дополнительных значений ошибок, которые не охватываются встроенными типами ошибок, тогда они могут использовать специальную встроенную ошибку для конкретной службы, которая позволяет включать значение ошибки для конкретной службы, определенное пользователем. . Эти ошибки, специфичные для службы, обычно определяются в интерфейсе AIDL как const int или enum с поддержкой int и не анализируются связующим устройством.

В 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
НДК	android/binder_status.h
Ржавчина	android/binder_status.h

Использование различных бэкэндов

Эти инструкции относятся к коду платформы Android. В этих примерах используется определенный тип my.package.IFoo . Инструкции по использованию серверной части Rust см. в примере Rust AIDL на странице шаблонов Android Rust .

Импорт типов

Независимо от того, является ли определенный тип интерфейсом, пакетным объектом или объединением, вы можете импортировать его в 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 необходимо включить заголовок для его корневого типа. Например, при импорте вложенного типа Bar , определенного в my/package/IFoo.aidl ( IFoo — это корневой тип файла), вы должны включить <my/package/IFoo.h> для серверной части 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(())
        }
    }

Или с асинхронным 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.

Предупреждение: AIDL/binder по умолчанию не запускает пул потоков. Если waitForService зависает, возможно, вам придется запустить пул потоков связывателя.

Предупреждение. Метод getService может получать сервисы в Android. В серверной части CPP/NDK/Rust и некоторых частях серверной части Java этот метод опрашивает 5 секунд и возвращает службу, только если она запускается в этом окне. Поскольку getService выполняет опрос и может привести к появлению гонок, рекомендуется избегать этого метода.

На Яве:

    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:

Примечание: здесь myfoo — это имя библиотеки, содержащей ранее определенный интерфейс.

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

Одним из важных отличий от других опций является то, что мы не вызываем join_thread_pool при использовании асинхронного Rust и однопоточной среды выполнения. Это потому, что вам нужно предоставить 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 , чтобы выйти из асинхронного контекста.

Связь со смертью

Вы можете запросить уведомление о прекращении службы, в которой размещается связующее. Это может помочь избежать утечки прокси-серверов обратного вызова или помочь в устранении ошибок. Выполните эти вызовы для прокси-объектов связывателя.

• В 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 (или идентификатор процесса) относится к идентификатору процесса Linux, который отправляет транзакцию. UID (или идентификатор пользователя) относится к идентификатору пользователя Linux. При получении одностороннего вызова PID вызова равен 0. Находясь вне контекста транзакции связывания, эти функции возвращают PID и UID текущего процесса.

Предупреждение: PID может участвовать в гонках. Как только вы получите PID, процесс, содержащий PID, может завершиться, и другой процесс может повторно использовать PID. Никогда не предполагайте, что PID представляет собой живой или конкретный процесс. Обычно PID полезны только для отладки.

В бэкэнде 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 в объекте сервера, как если бы вы реализовали любой другой метод IPC, определенный в файле AIDL. При этом вам следует ограничить выгрузку разрешением приложения 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.

Для перечисления MyEnum , определенного в AIDL, итерация осуществляется следующим образом.

В бэкэнде 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 поле или тип переименовываются с использованием синтаксиса «необработанного идентификатора», доступного по префиксу r# .

Мы рекомендуем вам избегать использования зарезервированных имен в определениях AIDL, чтобы избежать неэргономичных привязок или полного сбоя компиляции.

Если у вас уже есть зарезервированные имена в определениях AIDL, вы можете безопасно переименовывать поля, сохраняя при этом совместимость с протоколом; вам может потребоваться обновить код, чтобы продолжить сборку, но любые уже созданные программы продолжат взаимодействовать.

Имена, которых следует избегать: * Ключевые слова C++ * Ключевые слова Java * Ключевые слова Rust