Un backend AIDL est une cible pour la génération de code stub. Lorsque vous utilisez des fichiers AIDL, vous les utilisez toujours dans une langue particulière avec un runtime spécifique. Selon le contexte, vous devez utiliser différents backends AIDL.
AIDL a les backends suivants :
Backend | Langue | Surface API | Construire des systèmes |
---|---|---|---|
Java | Java | SDK/SystemApi (stable*) | tout |
NDK | C++ | libbinder_ndk (stable*) | aidl_interface |
RPC | C++ | libbinder (instable) | tout |
Rouiller | Rouiller | libbinder_rs (instable) | aidl_interface |
- Ces surfaces d'API sont stables, mais de nombreuses API, telles que celles pour la gestion des services, sont réservées à une utilisation interne de la plate-forme et ne sont pas disponibles pour les applications. Pour plus d'informations sur l'utilisation d'AIDL dans les applications, consultez la documentation destinée aux développeurs .
- Le backend Rust a été introduit dans Android 12 ; le backend NDK est disponible depuis Android 10.
- La caisse Rust est construite au-dessus de
libbinder_ndk
. Les APEX utilisent la caisse de classeur de la même manière que n'importe qui d'autre du côté système. La partie Rust est regroupée dans un APEX et expédiée à l'intérieur de celui-ci. Cela dépend dulibbinder_ndk.so
sur la partition système.
Construire des systèmes
Selon le backend, il existe deux façons de compiler AIDL en code stub. Pour plus de détails sur les systèmes de construction, consultez la référence du module Soong .
Système de construction de base
Dans n'importe quel module cc_
ou java_
Android.bp (ou dans leurs équivalents Android.mk
), les fichiers .aidl
peuvent être spécifiés comme fichiers source. Dans ce cas, les backends Java/CPP d'AIDL sont utilisés (pas le backend NDK), et les classes pour utiliser les fichiers AIDL correspondants sont automatiquement ajoutées au module. Des options telles que local_include_dirs
, qui indique au système de construction le chemin racine vers les fichiers AIDL dans ce module peuvent être spécifiées dans ces modules sous un groupe aidl:
Notez que le backend Rust est uniquement destiné à être utilisé avec Rust. Les modules rust_
sont gérés différemment dans la mesure où les fichiers AIDL ne sont pas spécifiés comme fichiers source. Au lieu de cela, le module aidl_interface
produit une rustlib
appelée <aidl_interface name>-rust
qui peut être liée. Pour plus de détails, voir l' exemple Rust AIDL .
aidl_interface
Voir AIDL stable . Les types utilisés avec ce système de construction doivent être structurés ; c'est-à-dire exprimé directement en AIDL. Cela signifie que les parcelables personnalisés ne peuvent pas être utilisés.
Les types
Vous pouvez considérer le compilateur aidl
comme une implémentation de référence pour les types. Lorsque vous créez une interface, aidl --lang=<backend> ...
pour voir le fichier d'interface résultant. Lorsque vous utilisez le module aidl_interface
, vous pouvez afficher la sortie dans out/soong/.intermediates/<path to module>/
.
Type Java/AIDL | Type C++ | Type NDK | Type de rouille |
---|---|---|---|
booléen | bourdonner | bourdonner | bourdonner |
octet | int8_t | int8_t | i8 |
carboniser | char16_t | char16_t | u16 |
entier | int32_t | int32_t | i32 |
longue | int64_t | int64_t | i64 |
flotter | flotter | flotter | f32 |
double | double | double | f64 |
Corde | Android :: Chaîne16 | std ::chaîne | Corde |
android.os.Colisable | Android :: Colisable | N / A | N / A |
IBinder | Android :: IBinder | ndk ::SpAIBinder | classeur ::SpIBinder |
T[] | std :: vecteur<T> | std :: vecteur<T> | Dans : &T Sortie : Vec<T> |
octet[] | std :: vecteur<uint8_t> | std::vecteur<int8_t> 1 | Dans : &[u8] Sortie : Vec<u8> |
Liste<T> | std::vecteur<T> 2 | std::vecteur<T> 3 | Dans : &[T] 4 Sortie : Vec<T> |
Descripteur de fichier | android :: base :: unique_fd | N / A | classeur::parcel::ParcelFileDescriptor |
ParcelFileDescriptor | android :: os :: ParcelFileDescriptor | ndk :: ScopedFileDescriptor | classeur::parcel::ParcelFileDescriptor |
type d'interface (T) | Android :: sp<T> | std ::shared_ptr<T> | liant::Fort |
type colisable (T) | J | J | J |
type union (T) 5 | J | J | J |
T[N] 6 | std::array<T, N> | std::array<T, N> | [T ; N] |
1. Dans Android 12 ou supérieur, les tableaux d'octets utilisent uint8_t au lieu de int8_t pour des raisons de compatibilité.
2. Le backend C++ prend en charge List<T>
où T
est l'un de String
, IBinder
, ParcelFileDescriptor
ou parcelable. Dans Android T (AOSP expérimental) ou supérieur, T
peut être n'importe quel type non primitif (y compris les types d'interface) à l'exception des tableaux. AOSP vous recommande d'utiliser des types de tableau comme T[]
, car ils fonctionnent dans tous les backends.
3. Le backend NDK prend en charge List<T>
où T
est l'un des String
, ParcelFileDescriptor
ou parcelable. Dans Android T (AOSP expérimental) ou supérieur, T
peut être n'importe quel type non primitif, à l'exception des tableaux.
4. Les types sont passés différemment pour le code Rust selon qu'ils sont une entrée (un argument) ou une sortie (une valeur renvoyée).
5. Les types d'union sont pris en charge dans Android 12 et supérieur.
6. Dans Android T (AOSP expérimental) ou supérieur, les tableaux de taille fixe sont pris en charge. Les tableaux de taille fixe peuvent avoir plusieurs dimensions (par exemple int[3][4]
). Dans le backend Java, les tableaux de taille fixe sont représentés sous forme de types de tableau.
Directionnalité (entrée/sortie/entrée)
Lorsque vous spécifiez les types des arguments des fonctions, vous pouvez les spécifier comme in
, out
ou inout
. Cela contrôle la direction dans laquelle les informations sont transmises pour un appel IPC. in
est la direction par défaut et indique que les données sont transmises de l'appelant à l'appelé. out
signifie que les données sont transmises de l'appelé à l'appelant. inout
est la combinaison des deux. Cependant, l'équipe Android vous recommande d'éviter d'utiliser le spécificateur d'argument inout
. Si vous utilisez inout
avec une interface versionnée et un ancien appelé, les champs supplémentaires présents uniquement dans l'appelant sont réinitialisés à leurs valeurs par défaut. En ce qui concerne Rust, un type inout
normal reçoit &mut Vec<T>
, et un type inout
liste reçoit &mut Vec<T>
.
UTF8/UTF16
Avec le backend CPP, vous pouvez choisir si les chaînes sont au format utf-8 ou utf-16. Déclarez les chaînes comme @utf8InCpp String
dans AIDL pour les convertir automatiquement en utf-8. Les backends NDK et Rust utilisent toujours des chaînes utf-8. Pour plus d'informations sur l'annotation utf8InCpp
, consultez Annotations dans AIDL .
Nullabilité
Vous pouvez annoter les types qui peuvent être null dans le backend Java avec @nullable
pour exposer les valeurs null aux backends CPP et NDK. Dans le backend Rust, ces types @nullable
sont exposés en tant que Option<T>
. Les serveurs natifs rejettent les valeurs nulles par défaut. Les seules exceptions à cela sont les types d' interface
et IBinder
, qui peuvent toujours être nuls pour les lectures NDK et les écritures CPP/NDK. Pour plus d'informations sur l'annotation nullable
, consultez Annotations dans AIDL .
Colis personnalisés
Dans les backends C++ et Java du système de génération principal, vous pouvez déclarer un parcelable qui est implémenté manuellement dans un backend cible (en C++ ou en Java).
package my.package;
parcelable Foo;
ou avec la déclaration d'en-tête C++ :
package my.package;
parcelable Foo cpp_header "my/package/Foo.h";
Ensuite, vous pouvez utiliser ce parcelable comme type dans les fichiers AIDL, mais il ne sera pas généré par AIDL.
Rust ne prend pas en charge les parcelables personnalisés.
Les valeurs par défaut
Les parcelables structurés peuvent déclarer des valeurs par défaut par champ pour les primitives, les String
et les tableaux de ces types.
parcelable Foo {
int numField = 42;
String stringField = "string value";
char charValue = 'a';
...
}
Dans le backend Java, lorsque les valeurs par défaut sont manquantes, les champs sont initialisés en tant que valeurs nulles pour les types primitifs et null
pour les types non primitifs.
Dans d'autres backends, les champs sont initialisés avec des valeurs initialisées par défaut lorsque les valeurs par défaut ne sont pas définies. Par exemple, dans le backend C++, les champs String
sont initialisés en tant que chaîne vide et les champs List<T>
sont initialisés en tant que vector<T>
vide. Les champs @nullable
sont initialisés en tant que champs de valeur nulle.
La gestion des erreurs
Le système d'exploitation Android fournit des types d'erreurs intégrés pour les services à utiliser lors du signalement d'erreurs. Ceux-ci sont utilisés par binder et peuvent être utilisés par n'importe quel service implémentant une interface binder. Leur utilisation est bien documentée dans la définition AIDL et ils ne nécessitent aucun statut ou type de retour défini par l'utilisateur.
Lorsqu'une fonction AIDL signale une erreur, la fonction peut ne pas initialiser ou modifier les paramètres de sortie. Plus précisément, les paramètres de sortie peuvent être modifiés si l'erreur se produit lors du dégroupage au lieu de se produire lors du traitement de la transaction elle-même. En général, lors de l'obtention d'une erreur d'une fonction AIDL, tous les paramètres inout
et out
ainsi que la valeur de retour (qui agit comme un paramètre out
dans certains backends) doivent être considérés comme étant dans un état indéfini.
Si l'interface AIDL nécessite des valeurs d'erreur supplémentaires qui ne sont pas couvertes par les types d'erreur intégrés, ils peuvent utiliser l'erreur intégrée spécifique au service spécial qui permet l'inclusion d'une valeur d'erreur spécifique au service définie par l'utilisateur. . Ces erreurs spécifiques au service sont généralement définies dans l'interface AIDL sous la forme d'une enum
const int
ou int
et ne sont pas analysées par binder.
En Java, les erreurs correspondent à des exceptions, telles que android.os.RemoteException
. Pour les exceptions spécifiques au service, Java utilise android.os.ServiceSpecificException
avec l'erreur définie par l'utilisateur.
Le code natif d'Android n'utilise pas d'exceptions. Le backend CPP utilise android::binder::Status
. Le backend NDK utilise ndk::ScopedAStatus
. Chaque méthode générée par AIDL en renvoie une, représentant l'état de la méthode. Le backend Rust utilise les mêmes valeurs de code d'exception que le NDK, mais les convertit en erreurs Rust natives ( StatusCode
, ExceptionCode
) avant de les transmettre à l'utilisateur. Pour les erreurs spécifiques au service, le Status
ou ScopedAStatus
utilise EX_SERVICE_SPECIFIC
avec l'erreur définie par l'utilisateur.
Les types d'erreur intégrés se trouvent dans les fichiers suivants :
Backend | Définition |
---|---|
Java | android/os/Parcel.java |
RPC | binder/Status.h |
NDK | android/binder_status.h |
Rouiller | android/binder_status.h |
Utilisation de divers backends
Ces instructions sont spécifiques au code de la plate-forme Android. Ces exemples utilisent un type défini, my.package.IFoo
. Pour obtenir des instructions sur l'utilisation du backend Rust, consultez l' exemple Rust AIDL sur la page Android Rust Patterns .
Importation de types
Que le type défini soit une interface, une parcelle ou une union, vous pouvez l'importer dans Java :
import my.package.IFoo;
Ou dans le backend CPP :
#include <my/package/IFoo.h>
Ou dans le backend NDK (notez l'espace de noms extra aidl
):
#include <aidl/my/package/IFoo.h>
Ou dans le backend Rust :
use my_package::aidl::my::package::IFoo;
Bien que vous puissiez importer un type imbriqué dans Java, dans les backends CPP/NDK, vous devez inclure l'en-tête pour son type racine. Par exemple, lors de l'importation d'un type imbriqué Bar
défini dans my/package/IFoo.aidl
( IFoo
est le type racine du fichier), vous devez inclure <my/package/IFoo.h>
pour le backend CPP (ou <aidl/my/package/IFoo.h>
pour le backend NDK).
Services de mise en œuvre
Pour implémenter un service, vous devez hériter de la classe stub native. Cette classe lit les commandes du pilote de classeur et exécute les méthodes que vous implémentez. Imaginez que vous ayez un fichier AIDL comme celui-ci :
package my.package;
interface IFoo {
int doFoo();
}
En Java, vous devez étendre à partir de cette classe :
import my.package.IFoo;
public class MyFoo extends IFoo.Stub {
@Override
int doFoo() { ... }
}
Dans le backend CPP :
#include <my/package/BnFoo.h>
class MyFoo : public my::package::BnFoo {
android::binder::Status doFoo(int32_t* out) override;
}
Dans le backend NDK (notez l'espace de noms supplémentaire aidl
):
#include <aidl/my/package/BnFoo.h>
class MyFoo : public aidl::my::package::BnFoo {
ndk::ScopedAStatus doFoo(int32_t* out) override;
}
Dans le backend 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(())
}
}
S'inscrire et obtenir des services
Les services de la plate-forme Android sont généralement enregistrés auprès du processus servicemanager
. En plus des API ci-dessous, certaines API vérifient le service (ce qui signifie qu'elles reviennent immédiatement si le service n'est pas disponible). Vérifiez l'interface de servicemanager
correspondante pour les détails exacts. Ces opérations ne peuvent être effectuées que lors de la compilation sur la plate-forme Android.
En Java :
import android.os.ServiceManager;
// registering
ServiceManager.addService("service-name", myService);
// getting
myService = IFoo.Stub.asInterface(ServiceManager.getService("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"));
Dans le backend CPP :
#include <binder/IServiceManager.h>
// registering
defaultServiceManager()->addService(String16("service-name"), myService);
// getting
status_t err = getService<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"));
Dans le backend NDK (notez l'espace de noms supplémentaire aidl
):
#include <android/binder_manager.h>
// registering
status_t err = AServiceManager_addService(myService->asBinder().get(), "service-name");
// getting
myService = IFoo::fromBinder(SpAIBinder(AServiceManager_getService("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")));
Dans le backend 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()
}
Lien avec la mort
Vous pouvez demander à recevoir une notification lorsqu'un service hébergeant un classeur meurt. Cela peut aider à éviter les fuites de proxys de rappel ou à faciliter la récupération des erreurs. Effectuez ces appels sur des objets proxy binder.
- En Java, utilisez
android.os.IBinder::linkToDeath
. - Dans le backend CPP, utilisez
android::IBinder::linkToDeath
. - Dans le backend NDK, utilisez
AIBinder_linkToDeath
. - Dans le backend Rust, créez un objet
DeathRecipient
, puis appelezmy_binder.link_to_death(&mut my_death_recipient)
. Notez que puisque leDeathRecipient
possède le rappel, vous devez garder cet objet actif aussi longtemps que vous souhaitez recevoir des notifications.
Rapports de bogues et API de débogage pour les services
Lorsque les rapports de bogues sont exécutés (par exemple, avec adb bugreport
), ils collectent des informations de tout le système pour aider au débogage de divers problèmes. Pour les services AIDL, les rapports de bogue utilisent les dumpsys
binaires sur tous les services enregistrés auprès du gestionnaire de services pour vider leurs informations dans le rapport de bogue. Vous pouvez également utiliser dumpsys
sur la ligne de commande pour obtenir des informations d'un service avec dumpsys SERVICE [ARGS]
. Dans les backends C++ et Java, vous pouvez contrôler l'ordre dans lequel les services sont vidés en utilisant des arguments supplémentaires pour addService
. Vous pouvez également utiliser dumpsys --pid SERVICE
pour obtenir le PID d'un service lors du débogage.
Pour ajouter une sortie personnalisée à votre service, vous pouvez remplacer la méthode de dump
dans votre objet serveur comme si vous implémentiez toute autre méthode IPC définie dans un fichier AIDL. Ce faisant, vous devez limiter le vidage à l'autorisation d'application android.permission.DUMP
ou restreindre le vidage à des UID spécifiques.
Dans le back-end Java :
@Override
protected void dump(@NonNull FileDescriptor fd, @NonNull PrintWriter fout,
@Nullable String[] args) {...}
Dans le backend CPP :
status_t dump(int, const android::android::Vector<android::String16>&) override;
Dans le back-end NDK :
binder_status_t dump(int fd, const char** args, uint32_t numArgs) override;
Dans le backend Rust, lors de l'implémentation de l'interface, spécifiez ce qui suit (au lieu de l'autoriser par défaut) :
fn dump(&self, mut file: &File, args: &[&CStr]) -> binder::Result<()>
Obtenir dynamiquement le descripteur d'interface
Le descripteur d'interface identifie le type d'une interface. Ceci est utile lors du débogage ou lorsque vous avez un classeur inconnu.
En Java, vous pouvez obtenir le descripteur d'interface avec un code tel que :
service = /* get ahold of service object */
... = service.asBinder().getInterfaceDescriptor();
Dans le backend CPP :
service = /* get ahold of service object */
... = IInterface::asBinder(service)->getInterfaceDescriptor();
Les backends NDK et Rust ne prennent pas en charge cette fonctionnalité.
Obtenir statiquement le descripteur d'interface
Parfois (comme lors de l'enregistrement des services @VintfStability
), vous devez savoir quel est le descripteur d'interface de manière statique. En Java, vous pouvez obtenir le descripteur en ajoutant du code tel que :
import my.package.IFoo;
... IFoo.DESCRIPTOR
Dans le backend CPP :
#include <my/package/BnFoo.h>
... my::package::BnFoo::descriptor
Dans le backend NDK (notez l'espace de noms supplémentaire aidl
):
#include <aidl/my/package/BnFoo.h>
... aidl::my::package::BnFoo::descriptor
Dans le backend Rust :
aidl::my::package::BnFoo::get_descriptor()
Plage d'énumération
Dans les backends natifs, vous pouvez parcourir les valeurs possibles qu'une énumération peut prendre. En raison de considérations de taille de code, cela n'est pas pris en charge en Java actuellement.
Pour une énumération MyEnum
définie dans AIDL, l'itération est fournie comme suit.
Dans le backend CPP :
::android::enum_range<MyEnum>()
Dans le back-end NDK :
::ndk::enum_range<MyEnum>()
Dans le backend Rust :
MyEnum::enum_range()
Gestion des fils
Chaque instance de libbinder
dans un processus gère un pool de threads. Dans la plupart des cas d'utilisation, il doit s'agir d'exactement un pool de threads, partagé entre tous les backends. La seule exception à cela est lorsque le code du fournisseur peut charger une autre copie de libbinder
pour parler à /dev/vndbinder
. Comme il s'agit d'un nœud de classeur séparé, le pool de threads n'est pas partagé.
Pour le backend Java, le pool de threads ne peut qu'augmenter en taille (puisqu'il est déjà démarré) :
BinderInternal.setMaxThreads(<new larger value>);
Pour le backend CPP, les opérations suivantes sont disponibles :
// 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();
De même, dans le backend NDK :
bool success = ABinderProcess_setThreadPoolMaxThreadCount(numThreads);
ABinderProcess_startThreadPool();
ABinderProcess_joinThreadPool();
Dans le backend Rust :
binder::ProcessState::start_thread_pool();
binder::add_service(“myservice”, my_service_binder).expect(“Failed to register service?”);
binder::ProcessState::join_thread_pool();