Um serviço vinculado é o servidor em uma interface servidor-cliente. Um serviço vinculado permite que componentes (como atividades) sejam vinculados ao serviço, enviem solicitações, recebam respostas e até estabeleçam comunicação entre processos (IPC). Um serviço vinculado, geralmente, vive somente enquanto serve outro componente do aplicativo e não é executado em segundo plano indefinidamente.
Este documento mostra como criar um serviço vinculado, inclusive como criar vínculos com o serviço a partir de outros componentes do aplicativo. No entanto, você também deve consultar a documentação Serviços para obter informações adicionais sobre serviços de forma geral, por exemplo: como enviar notificações de um serviço, como definir o serviço a ser executado em primeiro plano etc.
Um serviço vinculado é uma implementação da classe {@link android.app.Service} que permite que outros aplicativos sejam vinculados e interajam com ele. Para fornecer a vinculação a um serviço, você deve implementar o método de retorno de chamada {@link android.app.Service#onBind onBind()}. Este método retorna um objeto {@link android.os.IBinder} que define a interface de programação que os clientes podem usar para interagir com o serviço.
Como discutido na documentação Serviços, é possível criar um serviço que já foi iniciado e vinculado. Ou seja, o serviço pode ser iniciado chamando {@link android.content.Context#startService startService()}, que permite que ele permaneça em execução indefinidamente e também permite que um cliente vincule-o chamando {@link android.content.Context#bindService bindService()}.
Se você permitir que o serviço seja iniciado e vinculado, então, quando ele for iniciado, o sistema não o destruirá quando todos os clientes desfizerem a vínculo. Em vez disso, você deve interromper o serviço explicitamente chamando {@link android.app.Service#stopSelf stopSelf()} ou {@link android.content.Context#stopService stopService()}.
Apesar de normalmente se implementar {@link android.app.Service#onBind onBind()} ou {@link android.app.Service#onStartCommand onStartCommand()}, às vezes é necessário implementar ambos. Por exemplo, um reprodutor de música pode achar útil permitir que o seu serviço permaneça em execução indefinidamente, além de fornecer vinculação. Desta forma, uma atividade pode iniciar o serviço para reproduzir algumas músicas e a música continuará em reprodução mesmo quando o usuário sair do aplicativo. Em seguida, quando o usuário voltar ao aplicativo, a atividade poderá vincular-se ao serviço para retomar o controle da reprodução.
Certifique-se de ler a seção sobre Gerenciamento do ciclo de vida de um serviço vinculado para obter mais informações sobre o ciclo de vida do serviço ao adicionar vinculação a um serviço iniciado.
Um cliente pode vincular-se ao serviço chamando {@link android.content.Context#bindService bindService()}. Quando isto ocorre, é preciso fornecer uma implementação de {@link android.content.ServiceConnection}, que monitora a conexão com o serviço. O método {@link android.content.Context#bindService bindService()} retorna imediatamente sem um valor, mas quando o sistema Android cria a conexão entre o cliente e o serviço, ele chama {@link android.content.ServiceConnection#onServiceConnected onServiceConnected()} em {@link android.content.ServiceConnection} para fornecer o {@link android.os.IBinder} que o cliente pode usar para comunicar-se com o serviço.
Vários clientes podem conectar-se ao serviço de uma vez. No entanto, o sistema chama o método {@link android.app.Service#onBind onBind()} do serviço para recuperar o {@link android.os.IBinder} somente quando o primeiro cliente é vinculado. Em seguida, o sistema entrega o mesmo {@link android.os.IBinder} para quaisquer clientes adicionais que vincularem-se, sem chamar {@link android.app.Service#onBind onBind()} novamente.
Quando o último cliente desvincular-se do serviço, o sistema destruirá o serviço (a não ser que ele também seja iniciado por {@link android.content.Context#startService startService()}).
Ao implementar o serviço vinculado, o mais importante é definir a interface que o método de retorno de chamada {@link android.app.Service#onBind onBind()} retornará. Há poucas maneiras diferentes de definir a interface {@link android.os.IBinder} do serviço e a seção a seguir discute cada técnica.
Ao criar um serviço que fornece vinculação, você deve fornecer um {@link android.os.IBinder} que ofereça a interface de programação que os clientes podem usar para interagir com o serviço. Há três maneiras possíveis de definir a interface:
Esta é a técnica preferencial quando o serviço é meramente um trabalhador de segundo plano para o aplicativo. O único motivo pelo qual não se criaria a interface desta maneira é porque o serviço está sendo usado por outros aplicativos ou em processos separados.
Esta é a maneira mais simples de estabelecer comunicação entre processos (IPC), pois o {@link android.os.Messenger} coloca todas as solicitações em fila em um único encadeamento para que você não precise projetar o serviço de modo que seja seguro para encadeamentos.
Para usar a AIDL diretamente, deve-se criar um arquivo {@code .aidl} que defina a interface de programação. As ferramentas SDK do Android usam este arquivo para gerar uma classe abstrata que implemente a interface e lide com a IPC, que pode ser estendida dentro do serviço.
Observação: a maioria dos aplicativos não deve usar a AIDL para criar um serviço vinculado, pois isto requer capacidade de se trabalhar com encadeamentos múltiplos e pode resultar em uma implementação mais complicada. Portanto, a AIDL não é adequada para a maioria dos aplicativos e este documento não discute o seu uso para o serviço. Caso tenha certeza de que precisa usar a AIDL diretamente, consulte a documentação AIDL.
Se o serviço for usado somente pelo aplicativo local e não precisar trabalhar entre processos, então será possível implementar a própria classe {@link android.os.Binder} que fornece ao cliente acesso direto aos métodos públicos no serviço.
Observação: isto funciona somente se o cliente e o serviço estiverem no mesmo aplicativo e processo, o que é muito comum. Por exemplo, isto funcionaria bem para um aplicativo de música que precise vincular uma atividade ao próprio serviço que está reproduzindo música em segundo plano.
Como configurar:
Observação: o motivo pelo qual o serviço e o cliente devem estar no mesmo aplicativo é para que o cliente possa lançar o objeto retornado e chamar as APIs adequadamente. O serviço e o cliente também devem estar no mesmo processo, pois esta técnica não possui nenhuma ingerência entre processos.
Por exemplo, a seguir há um serviço que fornece aos clientes acesso aos métodos no serviço por meio de uma implementação de {@link android.os.Binder}:
public class LocalService extends Service {
// Binder given to clients
private final IBinder mBinder = new LocalBinder();
// Random number generator
private final Random mGenerator = new Random();
/**
* Class used for the client Binder. Because we know this service always
* runs in the same process as its clients, we don't need to deal with IPC.
*/
public class LocalBinder extends Binder {
LocalService getService() {
// Return this instance of LocalService so clients can call public methods
return LocalService.this;
}
}
@Override
public IBinder onBind(Intent intent) {
return mBinder;
}
/** method for clients */
public int getRandomNumber() {
return mGenerator.nextInt(100);
}
}
O {@code LocalBinder} fornece o método {@code getService()} para que os clientes recuperem a instância atual de {@code LocalService}. Isto permite que os clientes chamem métodos públicos no serviço. Por exemplo, eles podem chamar {@code getRandomNumber()} a partir do serviço.
Abaixo há uma atividade que vincula-se a {@code LocalService} e chama {@code getRandomNumber()} quando um botão é pressionado:
public class BindingActivity extends Activity {
LocalService mService;
boolean mBound = false;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
}
@Override
protected void onStart() {
super.onStart();
// Bind to LocalService
Intent intent = new Intent(this, LocalService.class);
bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
}
@Override
protected void onStop() {
super.onStop();
// Unbind from the service
if (mBound) {
unbindService(mConnection);
mBound = false;
}
}
/** Called when a button is clicked (the button in the layout file attaches to
* this method with the android:onClick attribute) */
public void onButtonClick(View v) {
if (mBound) {
// Call a method from the LocalService.
// However, if this call were something that might hang, then this request should
// occur in a separate thread to avoid slowing down the activity performance.
int num = mService.getRandomNumber();
Toast.makeText(this, "number: " + num, Toast.LENGTH_SHORT).show();
}
}
/** Defines callbacks for service binding, passed to bindService() */
private ServiceConnection mConnection = new ServiceConnection() {
@Override
public void onServiceConnected(ComponentName className,
IBinder service) {
// We've bound to LocalService, cast the IBinder and get LocalService instance
LocalBinder binder = (LocalBinder) service;
mService = binder.getService();
mBound = true;
}
@Override
public void onServiceDisconnected(ComponentName arg0) {
mBound = false;
}
};
}
O exemplo acima mostra como o cliente vincula um serviço usando uma implementação de {@link android.content.ServiceConnection} e o retorno de chamada {@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}. A próxima seção fornece mais informações sobre este processo de vinculação ao serviço.
Observação: o exemplo acima não desfaz a vinculação explicitamente a partir do serviço, mas todos os clientes devem fazê-lo no momento adequado (como quando a atividade pausa).
Para obter mais códigos de exemplo, consulte a classe {@code LocalService.java} e a classe {@code LocalServiceActivities.java} em ApiDemos.
Quando é necessário fazer uma IPC, usar o {@link android.os.Messenger} para a interface é mais simples do que implementá-la com AIDL, pois o {@link android.os.Messenger} enfileira todas as chamadas do serviço, enquanto que uma interface de AIDL pura envia solicitações simultâneas ao serviço, que deve então lidar com vários encadeamentos.
Para a maioria dos aplicativos, o serviço não precisa realizar vários encadeamentos. Portanto, usar {@link android.os.Messenger} permite que o serviço lide com uma chamada por vez. Caso seja importante que o serviço realize vários encadeamentos, deve-se usar a AIDL para definir a interface.
Caso precise que o serviço comunique-se com processos remotos, é possível usar o {@link android.os.Messenger} para fornecer a interface ao serviço. Esta técnica permite estabelecer comunicação entre processos (IPC) sem precisar usar a AIDL.
A seguir há um resumo sobre como usar um {@link android.os.Messenger}:
Desta forma, não há "métodos" para o cliente chamar no serviço. Em vez disso, o cliente envia "mensagens" (objetos {@link android.os.Message}) que o serviço recebe no {@link android.os.Handler}.
Abaixo há um exemplo simples de serviço que usa uma interface {@link android.os.Messenger}:
public class MessengerService extends Service {
/** Command to the service to display a message */
static final int MSG_SAY_HELLO = 1;
/**
* Handler of incoming messages from clients.
*/
class IncomingHandler extends Handler {
@Override
public void handleMessage(Message msg) {
switch (msg.what) {
case MSG_SAY_HELLO:
Toast.makeText(getApplicationContext(), "hello!", Toast.LENGTH_SHORT).show();
break;
default:
super.handleMessage(msg);
}
}
}
/**
* Target we publish for clients to send messages to IncomingHandler.
*/
final Messenger mMessenger = new Messenger(new IncomingHandler());
/**
* When binding to the service, we return an interface to our messenger
* for sending messages to the service.
*/
@Override
public IBinder onBind(Intent intent) {
Toast.makeText(getApplicationContext(), "binding", Toast.LENGTH_SHORT).show();
return mMessenger.getBinder();
}
}
Observe que o método {@link android.os.Handler#handleMessage handleMessage()} no {@link android.os.Handler} é onde o serviço recebe a {@link android.os.Message} e decide o que fazer, com base no membro {@link android.os.Message#what}.
Tudo que o cliente precisa fazer é criar um {@link android.os.Messenger} com base no {@link android.os.IBinder} retornado pelo serviço e enviar uma mensagem usando {@link android.os.Messenger#send send()}. Por exemplo, a seguir há uma atividade simples que vincula-se ao serviço e envia a mensagem {@code MSG_SAY_HELLO} a ele:
public class ActivityMessenger extends Activity {
/** Messenger for communicating with the service. */
Messenger mService = null;
/** Flag indicating whether we have called bind on the service. */
boolean mBound;
/**
* Class for interacting with the main interface of the service.
*/
private ServiceConnection mConnection = new ServiceConnection() {
public void onServiceConnected(ComponentName className, IBinder service) {
// This is called when the connection with the service has been
// established, giving us the object we can use to
// interact with the service. We are communicating with the
// service using a Messenger, so here we get a client-side
// representation of that from the raw IBinder object.
mService = new Messenger(service);
mBound = true;
}
public void onServiceDisconnected(ComponentName className) {
// This is called when the connection with the service has been
// unexpectedly disconnected -- that is, its process crashed.
mService = null;
mBound = false;
}
};
public void sayHello(View v) {
if (!mBound) return;
// Create and send a message to the service, using a supported 'what' value
Message msg = Message.obtain(null, MessengerService.MSG_SAY_HELLO, 0, 0);
try {
mService.send(msg);
} catch (RemoteException e) {
e.printStackTrace();
}
}
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
}
@Override
protected void onStart() {
super.onStart();
// Bind to the service
bindService(new Intent(this, MessengerService.class), mConnection,
Context.BIND_AUTO_CREATE);
}
@Override
protected void onStop() {
super.onStop();
// Unbind from the service
if (mBound) {
unbindService(mConnection);
mBound = false;
}
}
}
Observe que este exemplo não mostra como o serviço pode responder ao cliente. Caso queira que o serviço responda, é necessário criar um {@link android.os.Messenger} no cliente também. Em seguida, quando o cliente receber o retorno de chamada de {@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}, ele enviará uma {@link android.os.Message} para o serviço que inclui o {@link android.os.Messenger} no parâmetro {@link android.os.Message#replyTo} do método {@link android.os.Messenger#send send()}.
É possível ver um exemplo de como fornecer mensagens de duas vias nos exemplos {@code MessengerService.java} (serviço) e {@code MessengerServiceActivities.java} (cliente).
Um componente de aplicativo (cliente) pode vincular-se a um serviço chamando {@link android.content.Context#bindService bindService()}. O sistema Android, em seguida, chama o método {@link android.app.Service#onBind onBind()} do serviço, que retorna um {@link android.os.IBinder} para interagir com o serviço.
A vinculação é assíncrona. {@link android.content.Context#bindService bindService()} retorna imediatamente e não retorna o {@link android.os.IBinder} ao cliente. Para receber {@link android.os.IBinder}, o cliente deve criar uma instância de {@link android.content.ServiceConnection} e passá-la para {@link android.content.Context#bindService bindService()}. O {@link android.content.ServiceConnection} inclui um método de retorno de chamada que o sistema chama para entregar o {@link android.os.IBinder}.
Observação: somente atividades, serviços e provedores de conteúdo podem vincular-se a um serviço — você não pode fazer isto a partir de um receptor de transmissão.
Portanto, para vincular-se a um serviço a partir do cliente, deve-se:
Sua implementação deve substituir dois métodos de retorno de chamada:
Quando um cliente é destruído, o vínculo com o serviço acaba. No entanto, sempre desvincule-se ao terminar a interação com o serviço ou quando a atividade pausar para que o serviço possa ser encerrado enquanto não estiver em uso (os momentos adequados para vincular ou desvincular são abordados mais abaixo).
Por exemplo, o fragmento a seguir conecta o cliente ao serviço criado acima estendendo a classe Binder para que tudo que ele tenha que fazer seja lançar o {@link android.os.IBinder} retornado para a classe {@code LocalService} e solicitar a instância de {@code LocalService}:
LocalService mService;
private ServiceConnection mConnection = new ServiceConnection() {
// Called when the connection with the service is established
public void onServiceConnected(ComponentName className, IBinder service) {
// Because we have bound to an explicit
// service that is running in our own process, we can
// cast its IBinder to a concrete class and directly access it.
LocalBinder binder = (LocalBinder) service;
mService = binder.getService();
mBound = true;
}
// Called when the connection with the service disconnects unexpectedly
public void onServiceDisconnected(ComponentName className) {
Log.e(TAG, "onServiceDisconnected");
mBound = false;
}
};
Com este {@link android.content.ServiceConnection}, o cliente pode vincular-se a um serviço passando-o para {@link android.content.Context#bindService bindService()}. Por exemplo:
Intent intent = new Intent(this, LocalService.class); bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
A seguir há algumas observações importantes sobre a vinculação com um serviço:
Observação: geralmente, não se realiza o vínculo e o seu rompimento durante o {@link android.app.Activity#onResume onResume()} e o {@link android.app.Activity#onPause onPause()} da atividade, pois esses retornos de chamada ocorrem em todas as transições do ciclo de vida e deve-se usar menos processamento possível nessas transações. Além disso, se várias atividades no aplicativo vincularem-se ao mesmo serviço e houver uma transação entre duas dessas atividades, o serviço poderá ser destruído e recriado à medida que a atividade desvincula-se, durante a pausa, antes do próximo vínculo, durante a retomada (esta transição de atividade para como as atividades coordenam os ciclos de vida é descrita no documento Atividades ).
Para obter mais códigos de exemplo mostrando como vincular a um serviço, consulte a classe {@code RemoteService.java} no ApiDemos.
Quando um serviço é desvinculado de todos os clientes, o sistema Android o destrói (a não ser que ele também tenha sido inicializado com {@link android.app.Service#onStartCommand onStartCommand()}). Portanto, não é necessário gerenciar o ciclo de vida do serviço se ele for puramente um serviço vinculado — o sistema Android o gerencia com base nos vínculos com os clientes.
No entanto, se você escolher implementar o método de retorno de chamada {@link android.app.Service#onStartCommand onStartCommand()}, interrompa o serviço explicitamente, pois o serviço já terá sido considerado como iniciado. Neste caso, o serviço permanece em execução até ser interrompido com {@link android.app.Service#stopSelf()} ou outras chamadas de componente {@link android.content.Context#stopService stopService()}, independente de vínculo com qualquer cliente.
Além disso, se o serviço for iniciado e aceitar vínculos, quando o sistema chamar o método {@link android.app.Service#onUnbind onUnbind()}, será possível retornar {@code true} opcionalmente se você quiser receber uma chamada de {@link android.app.Service#onRebind onRebind()} na próxima vez em que um cliente vincular-se ao serviço (em vez de receber uma chamada de {@link android.app.Service#onBind onBind()}). {@link android.app.Service#onRebind onRebind()} retorna vazio, mas o cliente ainda recebe {@link android.os.IBinder} no retorno de chamada {@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}. Abaixo, a figura 1 ilustra a lógica para este tipo de ciclo de vida.
Figura 1. O ciclo de vida para um serviço que é iniciado e também permite vínculos.
Para obter mais informações sobre o ciclo de vida de um serviço iniciado, consulte o documento Serviços.