A linguagem de definição de interface do Android (AIDL, na sigla em inglês) é semelhante a outras IDLs: ela permite definir a interface de programação que o cliente e o serviço concordam em usar para se comunicar entre si usando a comunicação entre processos (IPC, na sigla em inglês).
No Android, um processo normalmente não pode acessar a memória de outro. Para se comunicarem, eles precisam decompor os objetos em primitivos que o sistema operacional possa entender e organizar os objetos além desse limite para você. O código para fazer esse marshalling é tedioso de escrever, então o Android lida com isso para você com a AIDL.
Observação: a AIDL só é necessária se você permitir que clientes de
aplicativos diferentes acessem seu serviço para IPC e quiser processar várias linhas de execução no
serviço. Se você não precisar realizar IPC simultâneas em
aplicativos diferentes, crie sua interface implementando um
Binder.
Se você quiser realizar a IPC, mas não precisar processar várias linhas de execução,
implemente a interface usando um Messenger.
De qualquer forma, entenda os serviços vinculados antes de
implementar uma AIDL.
Antes de começar a projetar sua interface AIDL, saiba que as chamadas para uma interface AIDL são chamadas de função diretas. Não faça suposições sobre a linha de execução em que a chamada ocorre. O que acontece é diferente dependendo se a chamada é de uma linha de execução no processo local ou em um processo remoto:
- As chamadas feitas do processo local são executadas na mesma linha de execução que está fazendo a chamada. Se
essa for sua linha de execução de interface principal, ela vai continuar sendo executada na interface AIDL. Se for outra linha de execução, ela será a que executará o código no serviço. Assim, se apenas as linhas de execução locais
estiverem acessando o serviço, você poderá controlar completamente quais linhas de execução estão sendo executadas nele. Mas,
se esse for o caso, não use a AIDL. Em vez disso, crie a
interface implementando um
Binder. - As chamadas de um processo remoto são enviadas de um pool de linhas de execução que a plataforma mantém dentro do seu próprio processo. Esteja preparado para receber chamadas recebidas de linhas de execução desconhecidas, com várias chamadas acontecendo ao mesmo tempo. Em outras palavras, uma implementação de uma interface AIDL precisa ser completamente thread-safe. As chamadas feitas de uma linha de execução no mesmo objeto remoto chegam em ordem no receptor.
- A palavra-chave
onewaymodifica o comportamento das chamadas remotas. Quando ele é usado, uma chamada remota não é bloqueada. Ele envia os dados da transação e retorna imediatamente. A implementação da interface recebe isso como uma chamada normal do pool de linhas de execuçãoBinder, como uma chamada remota normal. Seonewayfor usado com uma chamada local, não haverá impacto, e a chamada ainda será síncrona.
Como definir uma interface AIDL
Defina a interface AIDL em um arquivo .aidl usando a sintaxe da linguagem de programação
Java e salve-a no código-fonte, no diretório src/, tanto do
aplicativo que hospeda o serviço quanto de qualquer outro aplicativo que se vincule ao serviço.
Quando você cria cada aplicativo que contém o arquivo .aidl, as ferramentas do SDK do Android
geram uma interface IBinder com base no arquivo .aidl e a salvam no
diretório gen/ do projeto. O serviço precisa implementar a interface IBinder
conforme apropriado. Os aplicativos cliente podem se vincular ao serviço e chamar métodos do
IBinder para realizar a IPC.
Para criar um serviço vinculado usando a AIDL, siga as etapas abaixo, que são descritas nas seções a seguir:
- Criar o arquivo
.aidlEsse arquivo define a interface de programação com assinaturas de método.
- Implementar a interface
As ferramentas do SDK do Android geram uma interface na linguagem de programação Java com base no seu arquivo
.aidl. Essa interface tem uma classe abstrata interna chamadaStubque estendeBindere implementa métodos da sua interface AIDL. É necessário estender a classeStube implementar os métodos. - Expor a interface aos clientes
Implemente um
Servicee substituaonBind()para retornar sua implementação da classeStub.
Atenção: todas as mudanças feitas na interface AIDL após
a primeira versão precisam permanecer compatíveis com versões anteriores para evitar que outros aplicativos
que usam seu serviço sejam corrompidos. Ou seja, como o arquivo .aidl precisa ser copiado para outros aplicativos
para que eles possam acessar a interface do serviço, é necessário manter o suporte para a interface
original.
Criar o arquivo .aidl
A AIDL usa uma sintaxe simples que permite declarar uma interface com um ou mais métodos que podem receber parâmetros e retornar valores. Os parâmetros e valores de retorno podem ser de qualquer tipo, até mesmo outras interfaces geradas pela AIDL.
É preciso criar o arquivo .aidl usando a linguagem de programação Java. Cada arquivo .aidl
precisa definir uma única interface e requer apenas a declaração da interface e as assinaturas
de método.
Por padrão, a AIDL é compatível com os seguintes tipos de dados:
- Todos os tipos primitivos, exceto
short, na linguagem de programação Java (comoint,long,char,booleanetc.) - Matrizes de qualquer tipo, como
int[]ouMyParcelable[] StringCharSequenceListTodos os elementos no
Listprecisam ser um dos tipos de dados compatíveis nesta lista ou uma das outras interfaces ou parcelables gerados pela AIDL que você declarar. UmListpode ser usado como uma classe de tipo parametrizado, comoList<String>. A classe concreta real que o outro lado recebe é sempre umArrayList, embora o método seja gerado para usar a interfaceList.MapTodos os elementos no
Mapprecisam ser um dos tipos de dados compatíveis nesta lista ou uma das outras interfaces ou parcelables gerados pela AIDL que você declarar. Mapas de tipos parametrizados, como os do formatoMap<String,Integer>, não são compatíveis. A classe concreta real que o outro lado recebe é sempre umHashMap, embora o método seja gerado para usar a interfaceMap. Considere usar umBundlecomo alternativa aoMap.
É preciso incluir uma instrução import para cada tipo adicional não listado anteriormente,
mesmo que eles estejam definidos no mesmo pacote que a interface.
Ao definir a interface de serviço, esteja ciente de que:
- Os métodos podem receber zero ou mais parâmetros e retornar um valor ou void.
- Todos os parâmetros não primitivos exigem uma tag direcional que indica para onde os dados vão:
in,outouinout(veja o exemplo abaixo).Primitivos,
String,IBindere interfaces geradas por AIDL sãoinpor padrão e não podem ser de outra forma.Atenção: limite a direção ao que é realmente necessário, porque o marshalling de parâmetros é caro.
- Todos os comentários de código incluídos no arquivo
.aidlsão incluídos na interfaceIBindergerada, exceto os comentários antes das instruções de importação e pacote. - As constantes de string e int podem ser definidas na interface AIDL, como
const int VERSION = 1;. - As chamadas de método são enviadas por um
código
transact(), que normalmente se baseia em um índice de método na interface. Como isso dificulta o controle de versões, é possível atribuir manualmente o código de transação a um método:void method() = 10;. - Os argumentos anuláveis e os tipos de retorno precisam ser anotados usando
@nullable.
Veja um exemplo de arquivo .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); }
Salve o arquivo .aidl no diretório src/ do projeto. Quando você
cria o aplicativo, as ferramentas do SDK geram o arquivo de interface IBinder no diretório
gen/ do projeto. O nome do arquivo gerado corresponde ao nome do arquivo .aidl, mas
com uma extensão .java. Por exemplo, IRemoteService.aidl resulta em IRemoteService.java.
Se você usa o Android Studio, o build incremental gera a classe de vinculação quase imediatamente.
Se você não usa o Android Studio, a ferramenta Gradle gera a classe de vinculação na próxima vez que você
criar o aplicativo. Crie o projeto com gradle assembleDebug
ou gradle assembleRelease assim que terminar de escrever o arquivo .aidl,
para que o código possa ser vinculado à classe gerada.
Implementação da interface
Quando você cria o aplicativo, as ferramentas do SDK do Android geram um arquivo de interface .java
com o nome do arquivo .aidl. A interface gerada inclui uma subclasse chamada Stub,
que é uma implementação abstrata da interface pai, como YourInterface.Stub, e declara todos os métodos do arquivo .aidl.
Observação: Stub também
define alguns métodos auxiliares, principalmente asInterface(), que usa um IBinder, geralmente aquele transmitido para o método de callback onServiceConnected() de um cliente, e
retorna uma instância da interface de stub. Para mais detalhes sobre como fazer essa transmissão, consulte a seção Como chamar um método
de IPC.
Para implementar a interface gerada pelo .aidl, estenda a interface Binder
gerada, como YourInterface.Stub, e implemente os métodos
herdados do arquivo .aidl.
Confira um exemplo de implementação de uma interface chamada IRemoteService, definida pelo exemplo anterior de
IRemoteService.aidl, usando uma instância anônima:
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. } }
Agora, o binder é uma instância da classe Stub (um Binder),
que define a interface IPC para o serviço. Na próxima etapa, essa instância é exposta aos
clientes para que eles possam interagir com o serviço.
Ao implementar sua interface AIDL, lembre-se de algumas regras:
- Não há garantia de que as chamadas recebidas serão executadas na linha de execução principal. Por isso, é preciso pensar em multithreading desde o início e criar o serviço corretamente para que ele seja thread-safe.
- Por padrão, as chamadas de IPC são síncronas. Se você souber que o serviço leva mais do que alguns milissegundos para concluir uma solicitação, não o chame na linha de execução principal da atividade. Isso pode travar o aplicativo, fazendo com que o Android mostre uma caixa de diálogo "O app não está respondendo". Chame-o de uma linha de execução separada no cliente.
- Somente os tipos de exceção listados na documentação de referência de
Parcel.writeException()são enviados de volta ao autor da chamada.
Expor a interface aos clientes
Depois de implementar a interface para o serviço, você precisa expô-la aos
clientes para que eles possam se vincular a ela. Para expor a interface
do serviço, estenda Service e implemente onBind() para retornar uma instância da classe que implementa
o Stub gerado, conforme discutido na seção anterior. Veja um exemplo de serviço que expõe a interface de exemplo IRemoteService aos clientes.
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. } } }
Agora, quando um cliente, como uma atividade, chama bindService() para se conectar a esse serviço, o callback onServiceConnected() do cliente recebe a instância binder retornada pelo método onBind() do serviço.
O cliente também precisa ter acesso à classe de interface. Portanto, se o cliente e o serviço estiverem em
aplicativos separados, o aplicativo do cliente precisará ter uma cópia do arquivo .aidl
no diretório src/, que gera a interface
android.os.Binder, fornecendo ao cliente acesso aos métodos AIDL.
Quando o cliente recebe o IBinder
no callback onServiceConnected(), ele precisa chamar
YourServiceInterface.Stub.asInterface(service) para transmitir o parâmetro
retornado para o tipo 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 } }
Para mais exemplos de código, consulte a
classe
RemoteService.java em
ApiDemos.
Como transmitir objetos por IPC
No Android 10 (nível 29 da API ou mais recente), é possível definir
objetos Parcelable diretamente na
AIDL. Os tipos que são aceitos como argumentos de interface AIDL e outros parcelables também são
aceitos aqui. Isso evita o trabalho extra de escrever manualmente o código de marshalling e uma classe
personalizada. No entanto, isso também cria uma estrutura simples. Se você quiser acessadores personalizados ou outras funcionalidades, implemente 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;
}
O exemplo de código anterior gera automaticamente uma classe Java com os campos inteiros left,
top, right e bottom. Todo o código de marshalling relevante é
implementado automaticamente, e o objeto pode ser usado diretamente sem precisar adicionar nenhuma
implementação.
Também é possível enviar uma classe personalizada de um processo para outro usando uma interface IPC. No entanto,
verifique se o código da classe está disponível para o outro lado do canal de IPC e
se a classe é compatível com a interface Parcelable. A compatibilidade com
Parcelable é importante
porque permite que o sistema Android decomponha objetos em primitivos que podem ser empacotados
entre processos.
Para criar uma classe personalizada compatível com Parcelable, faça o
seguinte:
- Faça com que sua classe implemente a interface
Parcelable. - Implemente
writeToParcel, que usa o estado atual do objeto e o grava em umParcel. - Adicione um campo estático chamado
CREATORà sua classe, que é um objeto que implementa a interfaceParcelable.Creator. - Por fim, crie um arquivo
.aidlque declare sua classe parcelable, conforme mostrado no arquivoRect.aidlabaixo.Se você estiver usando um processo de build personalizado, não adicione o arquivo
.aidlao build. Semelhante a um arquivo principal na linguagem C, esse arquivo.aidlnão é compilado.
A AIDL usa esses métodos e campos no código que gera para organizar e desorganizar seus objetos.
Por exemplo, veja um arquivo Rect.aidl para criar uma classe Rect que é
parcelável:
package android.graphics; // Declare Rect so AIDL can find it and knows that it implements // the parcelable protocol. parcelable Rect;
Veja um exemplo de como a classe Rect implementa o protocolo 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 } }
A organização na classe Rect é simples. Confira os outros
métodos em Parcel para ver os outros tipos de valores que podem ser gravados
em um Parcel.
Aviso: lembre-se das implicações de segurança ao receber
dados de outros processos. Nesse caso, o Rect lê quatro números do Parcel, mas cabe a você garantir que eles estejam dentro do intervalo aceitável de
valores para o que o autor da chamada está tentando fazer. Para mais informações sobre como manter a segurança para aplicativos contra malware, consulte Dicas de segurança.
Métodos com argumentos de pacote que contêm Parcelables
Se um método aceitar um objetoBundle que deve conter
parcelables, defina o carregador de classe do Bundle
chamando Bundle.setClassLoader(ClassLoader) antes de tentar ler
do Bundle. Caso contrário, você vai encontrar ClassNotFoundException, mesmo que o parcelable esteja definido corretamente no aplicativo.
Por exemplo, considere o seguinte arquivo .aidl de amostra:
// 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); }
ClassLoader é
definido explicitamente no Bundle antes de ler Rect:
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. } }
Chamar um método IPC
Para chamar uma interface remota definida com a AIDL, siga estas etapas na classe de chamada:
- Inclua o arquivo
.aidlno diretóriosrc/do projeto. - Declare uma instância da interface
IBinder, que é gerada com base na AIDL. - implementar
ServiceConnection; - Chame
Context.bindService(), transmitindo sua implementação deServiceConnection. - Na implementação de
onServiceConnected(), você recebe uma instânciaIBinder, chamadaservice. ChameYourInterfaceName.Stub.asInterface((IBinder)service)para converter o parâmetro retornado no tipoYourInterface. - Chame os métodos que você definiu na interface. Sempre intercepte as exceções
DeadObjectException, que são geradas quando a conexão é interrompida. Além disso, intercepte as exceçõesSecurityException, que são geradas quando os dois processos envolvidos na chamada de método de IPC têm definições de AIDL conflitantes. - Para desconectar, chame
Context.unbindService()com a instância da sua interface.
Lembre-se destes pontos ao chamar um serviço de IPC:
- Objetos são referências contadas entre processos.
- É possível enviar objetos anônimos como argumentos de método.
Para mais informações sobre como vincular a um serviço, leia a Visão geral dos serviços vinculados.
Veja um exemplo de código que demonstra a chamada de um serviço criado pela AIDL, extraído do exemplo de serviço remoto no projeto ApiDemos.
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—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) } } } }