Android 接口定义语言 (AIDL)

Android 接口定义语言 (AIDL) 与其他 IDL 类似:它可以让您定义客户端与服务都认可的编程接口,以便二者使用进程间通信 (IPC) 进行相互通信。

在 Android 上,一个进程通常无法访问另一个进程的内存。为了进行通信,它们需要将对象分解为操作系统可以理解的原语,并为您跨越该边界对对象进行编组。执行该编组的代码编写起来非常繁琐,因此 Android 会使用 AIDL 为您处理。

注意:只有在您需要让不同应用的客户端访问您的服务以实现 IPC,并且您想在服务中处理多线程问题时,才需要使用 AIDL。如果您不需要跨不同应用执行并发 IPC,请通过实现 Binder 来创建接口。如果您想执行 IPC,但不需要处理多线程,请使用 Messenger 实现接口。无论如何,在实现 AIDL 之前,请务必先了解绑定服务。

在开始设计 AIDL 接口之前,请注意,对 AIDL 接口的调用是直接函数调用。不要对发生调用的线程做出假设。具体情况取决于调用是来自本地进程中的线程还是远程进程中的线程:

  • 从本地进程发出的调用在发出调用的同一线程中执行。如果这是您的主界面线程,该线程会继续在 AIDL 接口中执行。如果是其他线程,则该线程就是在服务中执行代码的线程。因此,如果只有本地线程访问该服务,您可以完全控制哪些线程在其中执行。但如果是这种情况,请完全不要使用 AIDL,而是通过实现 Binder 来创建接口。
  • 来自远程进程的调用会从平台在您自己的进程内维护的线程池中分派。做好准备,应对来自未知线程的来电,同时可能会有多个来电。换言之,AIDL 接口的实现必须是完全线程安全的。从同一远程对象上的一个线程发出的调用会按顺序到达接收端。
  • oneway 关键字会修改远程调用的行为。使用时,远程调用不会阻塞。它会发送交易数据并立即返回。 接口的实现最终会将其作为来自 Binder 线程池的常规调用(作为正常的远程调用)接收。如果 oneway 与本地调用一起使用,则不会产生任何影响,并且调用仍是同步的。

定义 AIDL 接口

使用 Java 编程语言语法在 .aidl 文件中定义 AIDL 接口,然后将其保存在托管服务的应用以及绑定到该服务的任何其他应用的源代码(位于 src/ 目录中)内。

当您构建每个包含 .aidl 文件的应用时,Android SDK 工具会根据 .aidl 文件生成一个 IBinder 接口,并将其保存到项目的 gen/ 目录中。服务必须酌情实现 IBinder 接口。然后,客户端应用可以绑定到该服务,并从 IBinder 调用方法以执行 IPC。

如需使用 AIDL 创建绑定服务,请执行以下步骤(后续部分有详细说明):

  1. 创建 .aidl 文件

    此文件使用方法签名定义编程接口。

  2. 实现接口

    Android SDK 工具会根据您的 .aidl 文件生成 Java 编程语言接口。此接口有一个名为 Stub 的内部抽象类,用于扩展 Binder 并实现 AIDL 接口中的方法。您必须扩展 Stub 类并实现这些方法。

  3. 向客户端公开接口

    实现 Service 并替换 onBind(),以返回 Stub 类的实现。

注意:在首次发布后,您对 AIDL 接口所做的任何更改都必须保持向后兼容,以免破坏使用您的服务的其他应用。也就是说,由于您的 .aidl 文件必须复制到其他应用,以便这些应用可以访问您服务的接口,因此您必须保持对原始接口的支持。

创建 .aidl 文件

AIDL 使用简单语法,让您可以通过一个或多个可接收参数以及返回值的方法来声明接口。参数和返回值可以是任何类型,甚至可以是其他 AIDL 生成的接口。

您必须使用 Java 编程语言构建 .aidl 文件。每个 .aidl 文件都必须定义一个接口,并且只需要接口声明和方法签名。

默认情况下,AIDL 支持以下数据类型:

  • Java 编程语言中的所有基元类型(short 除外),例如 int、long、char、boolean 等
  • 任何类型的数组,例如 int[] 或 MyParcelable[]
  • String
  • CharSequence
  • List

    List 中的所有元素都必须是此列表中受支持的数据类型之一,或者您声明的其他 AIDL 生成的接口或 Parcelable 之一。List 可以选择用作参数化类型类,例如 List<String>。另一端收到的实际具体类始终是 ArrayList,尽管该方法是使用 List 接口生成的。

  • Map

    Map 中的所有元素都必须是此列表中支持的数据类型之一,或者您声明的其他 AIDL 生成的接口或 Parcelable 之一。不支持形如 Map<String,Integer> 的参数化类型映射。另一端接收的实际具体类始终是 HashMap,尽管生成的方法使用的是 Map 接口。考虑使用 Bundle 作为 Map 的替代方案。

您必须为之前未列出的每个其他类型添加 import 语句,即使这些类型与您的接口在同一个软件包中定义也是如此。

定义服务接口时,请注意以下几点:

  • 方法可以接受零个或多个参数,并且可以返回值或 void。
  • 所有非基元参数都需要一个方向标记,用于指示数据的流向:in、out 或 inout(请参阅以下示例)。

    基元、String、IBinder 和 AIDL 生成的接口默认情况下为 in,且不能更改。

    注意:请将方向限制为真正需要的方向,因为编组参数的开销很大。

  • .aidl 文件中包含的所有代码注释都会包含在生成的 IBinder 接口中,但 import 和 package 语句之前的注释除外。
  • 字符串和 int 常量可以在 AIDL 接口中定义,例如 const int VERSION = 1;。
  • 方法调用由 transact() 代码分派,该代码通常基于接口中的方法索引。由于这会使版本控制变得困难,因此您可以手动将事务代码分配给方法:void method() = 10;。
  • 必须使用 @nullable 为可为 null 的实参和返回值类型添加注解。

下面是一个示例 .aidl 文件:

// IRemoteService.aidl
package com.example.android;

// Declare any non-default types here with import statements.

/** Example service interface. */
interface IRemoteService {
    /** Request the process ID of this service. */
    int getPid();

    /** Demonstrates some basic types that you can use as parameters
     * and return values in AIDL.
     */
    void basicTypes(int anInt, long aLong, boolean aBoolean, float aFloat,
            double aDouble, String aString);
}

将 .aidl 文件保存在项目的 src/ 目录中。当您构建应用时,SDK 工具会在项目的 gen/ 目录中生成 IBinder 接口文件。生成的文件名称与 .aidl 文件名称一致,但扩展名为 .java。例如,IRemoteService.aidl 的结果为 IRemoteService.java。

如果您使用 Android Studio,增量 build 几乎会立即生成 binder 类。 如果您不使用 Android Studio,Gradle 工具会在您下次构建应用时生成 binder 类。编写完 .aidl 文件后,立即使用 gradle assembleDebug 或 gradle assembleRelease 构建项目,以便您的代码可以链接到生成的类。

实现接口

当您构建应用时,Android SDK 工具会生成一个以 .aidl 文件命名的 .java 接口文件。生成的接口包含一个名为 Stub 的子类,该子类是其父接口(例如 YourInterface.Stub)的抽象实现,并且会声明 .aidl 文件中的所有方法。

注意:Stub 还定义了一些辅助方法,最值得注意的是 asInterface(),它采用 IBinder(通常是传递给客户端的 onServiceConnected() 回调方法的一个),并返回桩接口的实例。如需详细了解如何进行此转换,请参阅调用 IPC 方法部分。

如需实现通过 .aidl 生成的接口,请扩展生成的 Binder 接口(例如 YourInterface.Stub),并实现从 .aidl 文件继承的方法。

以下示例使用匿名实例实现了名为 IRemoteService 的接口(由前面的 IRemoteService.aidl 示例定义):

private val binder = object : IRemoteService.Stub() {

    override fun getPid(): Int =
        Process.myPid()

    override fun basicTypes(
        anInt: Int,
        aLong: Long,
        aBoolean: Boolean,
        aFloat: Float,
        aDouble: Double,
        aString: String
    ) {
        // Does nothing.
    }
}

现在,binder 是 Stub 类(Binder)的实例,用于定义服务的 IPC 接口。在下一步中,此实例将向客户端公开,以便客户端可以与服务进行交互。

实现 AIDL 接口时,请注意以下几条规则:

  • 传入调用不一定在主线程上执行,因此您需要从一开始就考虑多线程,并正确构建服务以确保线程安全。
  • 默认情况下,IPC 调用是同步的。如果您知道服务需要超过几毫秒的时间才能完成请求,请勿从 activity 的主线程调用该服务。这可能会导致应用挂起,从而导致 Android 显示“应用无响应”对话框。从客户端中的单独线程调用它。
  • 只有 Parcel.writeException() 的参考文档中列出的异常类型才会发送回调用方。

向客户端公开接口

为服务实现接口后,您需要向客户端公开该接口,以便客户端可以绑定到该接口。如需公开服务的接口,请扩展 Service 并实现 onBind(),以返回实现生成的 Stub 的类实例,如上一部分中所述。以下是一个示例服务,它向客户端公开 IRemoteService 示例接口。

class RemoteService : Service() {

    override fun onCreate() {
        super.onCreate()
    }

    override fun onBind(intent: Intent): IBinder {
        // Return the interface.
        return binder
    }

    private val binder = object : IRemoteService.Stub() {
        override fun getPid(): Int {
            return Process.myPid()
        }

        override fun basicTypes(
            anInt: Int,
            aLong: Long,
            aBoolean: Boolean,
            aFloat: Float,
            aDouble: Double,
            aString: String
        ) {
            // Does nothing.
        }
    }
}

现在,当客户端(例如 activity)调用 bindService() 连接到此服务时,客户端的 onServiceConnected() 回调会收到服务的 onBind() 方法返回的 binder 实例。

客户端还必须有权访问接口类。因此,如果客户端和服务位于不同的应用中,则客户端的应用必须在其 src/ 目录中包含 .aidl 文件的副本,该副本会生成 android.os.Binder 接口,从而为客户端提供对 AIDL 方法的访问权限。

当客户端在 onServiceConnected() 回调中收到 IBinder 时,必须调用 YourServiceInterface.Stub.asInterface(service) 将返回的参数转换为 YourServiceInterface 类型:

var iRemoteService: IRemoteService? = null

val mConnection = object : ServiceConnection {

    // Called when the connection with the service is established.
    override fun onServiceConnected(className: ComponentName, service: IBinder) {
        // Following the preceding example for an AIDL interface,
        // this gets an instance of the IRemoteInterface, which we can use to call on the service.
        iRemoteService = IRemoteService.Stub.asInterface(service)
    }

    // Called when the connection with the service disconnects unexpectedly.
    override fun onServiceDisconnected(className: ComponentName) {
        Log.e(TAG, "Service has unexpectedly disconnected")
        iRemoteService = null
    }
}

如需查看更多示例代码,请参阅 ApiDemos 中的 RemoteService.java 类。

通过 IPC 传递对象

在 Android 10(API 级别 29 或更高级别)中,您可以直接在 AIDL 中定义 Parcelable 对象。此处也支持作为 AIDL 接口参数和其他 Parcelable 支持的类型。这样可以避免手动编写编组代码和自定义类的额外工作。不过,这也会创建一个裸结构体。如果需要自定义访问函数或其他功能,请改为实现 Parcelable。

package android.graphics;

// Declare Rect so AIDL can find it and knows that it implements
// the parcelable protocol.
parcelable Rect {
    int left;
    int top;
    int right;
    int bottom;
}

上述代码示例会自动生成一个包含整数字段 left、top、right 和 bottom 的 Java 类。所有相关的编组代码都会自动实现,并且可以直接使用该对象,而无需添加任何实现。

您还可以通过 IPC 接口将自定义类从一个进程发送到另一个进程。不过,请确保 IPC 通道的另一端可以访问您的类的代码,并且您的类必须支持 Parcelable 接口。支持 Parcelable 非常重要,因为这样 Android 系统就可以将对象分解为可跨进程编组的基元。

如需创建支持 Parcelable 的自定义类,请执行以下操作:

  1. 让您的类实现 Parcelable 接口。
  2. 实现 writeToParcel,它会获取对象的当前状态并将其写入 Parcel。
  3. 向类中添加一个名为 CREATOR 的静态字段,该字段是实现 Parcelable.Creator 接口的对象。
  4. 最后,创建一个用于声明 Parcelable 类的 .aidl 文件,如以下 Rect.aidl 文件所示。

    如果您使用的是自定义构建流程,请勿将 .aidl 文件添加到 build 中。与 C 语言中的头文件类似,此 .aidl 文件不会被编译。

AIDL 会在其生成的代码中使用这些方法和字段,以对您的对象进行编组和解组。

例如,以下是一个 Rect.aidl 文件,用于创建可打包的 Rect 类:

package android.graphics;

// Declare Rect so AIDL can find it and knows that it implements
// the parcelable protocol.
parcelable Rect;

以下示例展示了 Rect 类如何实现 Parcelable 协议。

// import android.os.Parcel
// import android.os.Parcelable

class Rect() : Parcelable {
    var left: Int = 0
    var top: Int = 0
    var right: Int = 0
    var bottom: Int = 0

    companion object CREATOR : Parcelable.Creator<Rect> {
        override fun createFromParcel(parcel: Parcel): Rect {
            return Rect(parcel)
        }

        override fun newArray(size: Int): Array<Rect?> {
            return Array(size) { null }
        }
    }

    private constructor(inParcel: Parcel) : this() {
        readFromParcel(inParcel)
    }

    override fun writeToParcel(outParcel: Parcel, flags: Int) {
        outParcel.writeInt(left)
        outParcel.writeInt(top)
        outParcel.writeInt(right)
        outParcel.writeInt(bottom)
    }

    private fun readFromParcel(inParcel: Parcel) {
        left = inParcel.readInt()
        top = inParcel.readInt()
        right = inParcel.readInt()
        bottom = inParcel.readInt()
    }

    override fun describeContents(): Int {
        return 0
    }
}

Rect 类中的编组非常简单。查看 Parcel 上的其他方法,了解您可以写入 Parcel 的其他类型的值。

警告:请注意从其他进程接收数据对安全性的影响。在本例中,Rect 会从 Parcel 中读取四个数字,但您需要确保这些数字在调用方尝试执行的任何操作的可接受值范围内。如需详细了解如何保护应用免受恶意软件的侵害,请参阅安全提示。

包含 Parcelable 的 Bundle 实参的方法

如果某个方法接受应包含 Parcelable 对象的 Bundle 对象,请确保在尝试从 Bundle 读取数据之前,通过调用 Bundle.setClassLoader(ClassLoader) 来设置 Bundle 的类加载器。否则,即使在应用中正确定义了 Parcelable,您也会遇到 ClassNotFoundException。

例如,请考虑以下示例 .aidl 文件:

// IRectInsideBundle.aidl
package com.example.android;

/** Example service interface. */
interface IRectInsideBundle {
    /** Rect parcelable is stored in the bundle with key "rect". */
    void saveRect(in Bundle bundle);
}
如以下实现所示,在读取 Rect 之前,ClassLoader 会在 Bundle 中显式设置:
private val binder = object : IRectInsideBundle.Stub() {
    override fun saveRect(bundle: Bundle) {
        bundle.classLoader = classLoader
        val rect = BundleCompat.getParcelable(bundle, "rect", Rect::class.java)
        process(rect) // Do more with the parcelable.
    }
}

调用 IPC 方法

如需调用使用 AIDL 定义的远程接口,请在调用类中执行以下步骤:

  1. 在项目 src/ 目录中添加 .aidl 文件。
  2. 声明 IBinder 接口的实例,该接口是根据 AIDL 生成的。
  3. 实现 ServiceConnection。
  4. 调用 Context.bindService(),并传入您的 ServiceConnection 实现。
  5. 在 onServiceConnected() 的实现中,您会收到一个名为 service 的 IBinder 实例。调用 YourInterfaceName.Stub.asInterface((IBinder)service),将返回的参数转换为 YourInterface 类型。
  6. 调用您在接口上定义的方法。始终捕获 DeadObjectException 异常,这些异常会在连接中断时抛出。此外,还要捕获 SecurityException 异常,当 IPC 方法调用中涉及的两个进程具有冲突的 AIDL 定义时,系统会抛出该异常。
  7. 如需断开连接,请使用接口实例调用 Context.unbindService()。

调用 IPC 服务时,请注意以下几点:

  • 对象是跨进程计数的引用。
  • 您可以将匿名对象作为方法参数发送。

如需详细了解如何绑定到服务,请参阅绑定服务概览。

以下是一些示例代码,取自 ApiDemos 项目中的 Remote Service 示例,展示了如何调用 AIDL 创建的服务。

private const val BUMP_MSG = 1

class Binding : Activity() {

    /** The primary interface you call on the service.  */
    private var mService: IRemoteService? = null

    /** Another interface you use on the service.  */
    internal var secondaryService: ISecondary? = null

    private lateinit var killButton: Button
    private lateinit var callbackText: TextView
    private lateinit var handler: InternalHandler

    private var isBound: Boolean = false

    /**
     * Class for interacting with the main interface of the service.
     */
    private val mConnection = object : ServiceConnection {

        override fun onServiceConnected(className: ComponentName, service: IBinder) {
            // This is called when the connection with the service is
            // established, giving us the service object we can use to
            // interact with the service.  We are communicating with our
            // service through an IDL interface, so get a client-side
            // representation of that from the raw service object.
            mService = IRemoteService.Stub.asInterface(service)
            killButton.isEnabled = true
            callbackText.text = "Attached."

            // We want to monitor the service for as long as we are
            // connected to it.
            try {
                mService?.registerCallback(mCallback)
            } catch (e: RemoteException) {
                // In this case, the service crashes before we can
                // do anything with it. We can count on soon being
                // disconnected (and then reconnected if it can be restarted)
                // so there is no need to do anything here.
            }

            // As part of the sample, tell the user what happened.
            Toast.makeText(
                    this@Binding,
                    R.string.remote_service_connected,
                    Toast.LENGTH_SHORT
            ).show()
        }

        override fun onServiceDisconnected(className: ComponentName) {
            // This is called when the connection with the service is
            // unexpectedly disconnected&mdash;that is, its process crashed.
            mService = null
            killButton.isEnabled = false
            callbackText.text = "Disconnected."

            // As part of the sample, tell the user what happened.
            Toast.makeText(
                    this@Binding,
                    R.string.remote_service_disconnected,
                    Toast.LENGTH_SHORT
            ).show()
        }
    }

    /**
     * Class for interacting with the secondary interface of the service.
     */
    private val secondaryConnection = object : ServiceConnection {

        override fun onServiceConnected(className: ComponentName, service: IBinder) {
            // Connecting to a secondary interface is the same as any
            // other interface.
            secondaryService = ISecondary.Stub.asInterface(service)
            killButton.isEnabled = true
        }

        override fun onServiceDisconnected(className: ComponentName) {
            secondaryService = null
            killButton.isEnabled = false
        }
    }

    private val mBindListener = View.OnClickListener {
        // Establish a couple connections with the service, binding
        // by interface names. This lets other applications be
        // installed that replace the remote service by implementing
        // the same interface.
        val intent = Intent(this@Binding, RemoteService::class.java)
        intent.action = IRemoteService::class.java.name
        bindService(intent, mConnection, Context.BIND_AUTO_CREATE)
        intent.action = ISecondary::class.java.name
        bindService(intent, secondaryConnection, Context.BIND_AUTO_CREATE)
        isBound = true
        callbackText.text = "Binding."
    }

    private val unbindListener = View.OnClickListener {
        if (isBound) {
            // If we have received the service, and hence registered with
            // it, then now is the time to unregister.
            try {
                mService?.unregisterCallback(mCallback)
            } catch (e: RemoteException) {
                // There is nothing special we need to do if the service
                // crashes.
            }

            // Detach our existing connection.
            unbindService(mConnection)
            unbindService(secondaryConnection)
            killButton.isEnabled = false
            isBound = false
            callbackText.text = "Unbinding."
        }
    }

    private val killListener = View.OnClickListener {
        // To kill the process hosting the service, we need to know its
        // PID.  Conveniently, the service has a call that returns
        // that information.
        try {
            secondaryService?.pid?.also { pid ->
                // Note that, though this API lets us request to
                // kill any process based on its PID, the kernel
                // still imposes standard restrictions on which PIDs you
                // can actually kill. Typically this means only
                // the process running your application and any additional
                // processes created by that app, as shown here. Packages
                // sharing a common UID are also able to kill each
                // other's processes.
                Process.killProcess(pid)
                callbackText.text = "Killed service process."
            }
        } catch (ex: RemoteException) {
            // Recover gracefully from the process hosting the
            // server dying.
            // For purposes of this sample, put up a notification.
            Toast.makeText(this@Binding, R.string.remote_call_failed, Toast.LENGTH_SHORT).show()
        }
    }

    // ----------------------------------------------------------------------
    // Code showing how to deal with callbacks.
    // ----------------------------------------------------------------------

    /**
     * This implementation is used to receive callbacks from the remote
     * service.
     */
    private val mCallback = object : IRemoteServiceCallback.Stub() {
        /**
         * This is called by the remote service regularly to tell us about
         * new values.  Note that IPC calls are dispatched through a thread
         * pool running in each process, so the code executing here is
         * NOT running in our main thread like most other things. So,
         * to update the UI, we need to use a Handler to hop over there.
         */
        override fun valueChanged(value: Int) {
            handler.sendMessage(handler.obtainMessage(BUMP_MSG, value, 0))
        }
    }

    /**
     * Standard initialization of this activity.  Set up the UI, then wait
     * for the user to interact with it before doing anything.
     */
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContentView(R.layout.remote_service_binding)

        // Watch for button taps.
        var button: Button = findViewById(R.id.bind)
        button.setOnClickListener(mBindListener)
        button = findViewById(R.id.unbind)
        button.setOnClickListener(unbindListener)
        killButton = findViewById(R.id.kill)
        killButton.setOnClickListener(killListener)
        killButton.isEnabled = false

        callbackText = findViewById(R.id.callback)
        callbackText.text = "Not attached."
        handler = InternalHandler(callbackText)
    }

    private class InternalHandler(
            textView: TextView,
            private val weakTextView: WeakReference<TextView> = WeakReference(textView)
    ) : Handler() {
        override fun handleMessage(msg: Message) {
            when (msg.what) {
                BUMP_MSG -> weakTextView.get()?.text = "Received from service: ${msg.arg1}"
                else -> super.handleMessage(msg)
            }
        }
    }
}