android-aidl

name android-aidl description Use when writing, reviewing, or debugging AIDL (Android Interface Definition Language) interface files for IPC between Android processes. Covers .aidl syntax, primitive and Parcelable types, oneway modifier, directional parameters, versioning and stability, and generating Java/C++ binder stubs in Gradle and AOSP Soong builds. argument-hint <interface-name> [write|review|debug] Android AIDL — Interface Definition Language Practices for defining correct, versioned AIDL interfaces for use in Android applications and HAL services targeting Android Automotive OS (AAOS) . Source of truth: Android AIDL Guide and AIDL Backends . When to Use This Skill Defining IPC interfaces between apps or between an app and a bound Service . Defining HAL interfaces (AIDL HAL, Android 11+) in AOSP. Passing custom data types across process boundaries (Parcelable). Controlling one-way (async) vs. two-way (blocking) calls. Basic AIDL Interface // IRemoteCounter.aidl — saved under a package directory package com.example.counter; // Interfaces extend nothing (no extends syntax in AIDL) interface IRemoteCounter { void reset(); int getCount(); void increment(int delta); String getTag(); } Generated stub/proxy: Gradle : Java stubs placed in build/generated/ . AOSP Soong : NDK/CPP/Java stubs generated from a filegroup → aidl_interface . Supported AIDL Types Category Types Primitives boolean , byte , char , int , long , float , double String String (always in direction) Arrays int[] , byte[] , etc. List List (contents must be in the set of AIDL-supported types) Parcelable any parcelable declared in AIDL Interface any interface declared in AIDL (passed as IBinder ) FileDescriptor for passing file descriptors cross-process Parcelable — Custom Data Types // SensorData.aidl package com.example.sensor; parcelable SensorData { int sensorId; float value; long timestampNs; String unit; } Java side: if you generate Java stubs, the parcelable fields are accessible directly. C++ (NDK backend) side: the generated class has Parcel::readFromParcel and writeToParcel . For hand-written Java implementation of a Parcelable, you write a separate .java file implementing android.os.Parcelable — the .aidl file is then just the declaration. Directional Parameters For non-primitive parameters, you must declare the data flow direction: Direction Meaning Usage in Caller → Callee (read-only for callee) Most inputs out Callee fills the buffer (write-only for callee, caller provides pre-allocated object) Output buffers inout Both directions — data sent in, modified, sent back Read-modify-write interface IProcessor { void process(in SensorData input, out ResultData result); void update(inout ConfigData config); } Primitives and String are always in . You may omit the direction keyword for in -only primitives. The oneway Modifier oneway makes a method call asynchronous — the caller does not block and the method cannot return a value or throw. interface IEventListener { oneway void onSensorEvent(in SensorData event); oneway void onError(int code, String message); } Rules: oneway methods cannot have return values (must be void ). oneway methods cannot have out or inout parameters. You can mark the entire interface as oneway : oneway interface IListener { ... } . Calls are queued and delivered in-order per interface. Versioning and Stability ( @VintfStability / frozen versions) For interfaces shared across processes with different update schedules (e.g., HAL services), use versioned aidl_interface in AOSP: // hardware/interfaces/audio/IMyAudioHal.aidl package android.hardware.audio; // use android.hardware.* namespace for HALs @VintfStability interface IMyAudioHal { void start(); void stop(); int getVolume(); } @VintfStability marks the interface as part of the VINTF surface — it must be frozen before shipping. Frozen interfaces can only be extended (new methods), never changed or removed. Versioning uses aidl_interface with versions: in Android.bp . AOSP Soong Build (Android.bp) aidl_interface { name: "my-audio-hal-aidl", srcs: ["hardware/interfaces/audio/*.aidl"], stability: "vintf", backend: { cpp: { enabled: true }, ndk: { enabled: true }, java: { enabled: false }, }, versions: ["1"], // frozen version list } stability: "vintf" → equivalent to @VintfStability on all interfaces. backend.ndk → generates NDK-compatible C++ stubs usable from native code. backend.cpp → generates libbinder-level stubs for system/HAL C++ code. Source library dependency: "my-audio-hal-aidl-ndk" or "my-audio-hal-aidl-cpp" . Gradle Build (Android Studio projects) src/ main/ aidl/ com/example/counter/ IRemoteCounter.aidl java/ com/example/counter/ RemoteCounterService.java In build.gradle (Groovy) or build.gradle.kts (Kotlin DSL): android { buildFeatures { aidl = true } } Stubs are generated automatically and placed in build/generated/aidl_source_output_dir/ . Implementing an AIDL Service (Java) public class RemoteCounterService extends Service { private final IRemoteCounter. Stub mBinder = new IRemoteCounter .Stub() { private int mCount = 0 ; @Override public synchronized void reset () { mCount = 0 ; } @Override public synchronized int getCount () { return mCount; } @Override public synchronized void increment ( int delta) { mCount += delta; } @Override public String getTag () { return "counter" ; } }; @Override public IBinder onBind (Intent intent) { return mBinder; } } Implementing an AIDL Service (C++ / NDK backend) # include <aidl/com/example/counter/BnRemoteCounter.h> // generated Bn stub using aidl::com::example::counter::BnRemoteCounter; class RemoteCounterImpl : public BnRemoteCounter { public : ndk::ScopedAStatus reset () override { std::lock_guard<std::mutex> lock (mutex_) ; count_ = 0 ; return ndk::ScopedAStatus:: ok (); } ndk::ScopedAStatus getCount ( int32_t * _aidl_return) override { std::lock_guard<std::mutex> lock (mutex_) ; *_aidl_return = count_; return ndk::ScopedAStatus:: ok (); } ndk::ScopedAStatus increment ( int32_t delta) override { std::lock_guard<std::mutex> lock (mutex_) ; count_ += delta; return ndk::ScopedAStatus:: ok (); } ndk::ScopedAStatus getTag (std::string* _aidl_return) override { *_aidl_return = "counter" ; return ndk::ScopedAStatus:: ok (); } private : std::mutex mutex_; int32_t count_ = 0 ; }; Prerequisites Android Studio (Flamingo or newer) or AOSP build environment set up. Android SDK Platform-Tools installed ( adb on PATH). Target device or emulator running Android 11+ (API 30+). For AOSP modules: repo tool, AOSP source synced, lunch target configured. Step-by-Step Workflows Step 1: Define the AIDL interface Create the .aidl file with the correct package declaration and method signatures. Follow the Basic AIDL Syntax and Supported AIDL Types sections below. Step 2: Configure the build Add the .aidl file to the Gradle sourceSets or AOSP Android.bp module. Step 3: Implement the Binder stub Generate and implement the Stub class in the service process. Step 4: Bind the service (client side) Implement ServiceConnection and cast the IBinder to the AIDL interface. Step 5: Add versioning (if needed) Define const int VERSION in the AIDL and implement getInterfaceVersion() . Troubleshooting cannot find symbol for AIDL-generated class — clean and rebuild; check sourceSets.main.aidl.srcDirs in Gradle. SecurityException when binding — the client is missing the android.permission.* declared by the service; add the permission to the client manifest. android.os.DeadObjectException — the service process died; implement IBinder.DeathRecipient to reconnect. AIDL version mismatch — ensure both client and server compile against the same AIDL interface version; use getInterfaceVersion() for defensive checks. Pre-Commit Checklist All .aidl files placed under the correct package directory. Directional tags ( in / out / inout ) on all non-primitive parameters. oneway methods are void with no out / inout params. @VintfStability present on interfaces shared across VINTF boundary. HAL interfaces use android.hardware.* package namespace. Frozen versions listed in Android.bp versions: before release. No methods removed or signatures changed in frozen interface versions. References AIDL Overview AIDL for HALs (AOSP) AIDL Backends AIDL Stability