guide/components/bound-services.jd

page.title=Servios vinculados
parent.title=Servios
parent.link=services.html
@jd:body


<div id="qv-wrapper">
<ol id="qv">
<h2>Neste documento</h2>
<ol>
  <li><a href="#Basics">Conceitos bsicos</a></li>
  <li><a href="#Creating">Criao de um servio vinculado</a>
    <ol>
      <li><a href="#Binder">Extenso da classe Binder</a></li>
      <li><a href="#Messenger">Uso de um mensageiro</a></li>
    </ol>
  </li>
  <li><a href="#Binding">Vinculao a um servio</a></li>
  <li><a href="#Lifecycle">Gerenciamento do ciclo de vida de um servio vinculado</a></li>
</ol>

<h2>Classes principais</h2>
<ol>
  <li>{@link android.app.Service}</li>
  <li>{@link android.content.ServiceConnection}</li>
  <li>{@link android.os.IBinder}</li>
</ol>

<h2>Exemplos</h2>
<ol>
  <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code
      RemoteService}</a></li>
  <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code
      LocalService}</a></li>
</ol>

<h2>Veja tambm</h2>
<ol>
  <li><a href="{@docRoot}guide/components/services.html">Servios</a></li>
</ol>
</div>


<p>Um servio vinculado  o servidor em uma interface servidor-cliente. Um servio vinculado permite que componentes
(como atividades) sejam vinculados ao servio, enviem solicitaes, recebam respostas e at estabeleam
comunicao entre processos (IPC). Um servio vinculado, geralmente, vive somente enquanto serve
outro componente do aplicativo e no  executado em segundo plano indefinidamente.</p>

<p>Este documento mostra como criar um servio vinculado, inclusive como criar vnculos
com o servio a partir de outros componentes do aplicativo. No entanto, voc tambm deve consultar a documentao <a href="{@docRoot}guide/components/services.html">Servios</a> para obter
informaes adicionais sobre servios de forma geral, por exemplo: como enviar notificaes de um servio,
como definir o servio a ser executado em primeiro plano etc.</p>


<h2 id="Basics">Conceitos bsicos</h2>

<p>Um servio vinculado  uma implementao da classe {@link android.app.Service} que permite
que outros aplicativos sejam vinculados e interajam com ele. Para fornecer a vinculao
a um servio, voc deve implementar o mtodo de retorno de chamada {@link android.app.Service#onBind onBind()}. Este mtodo
retorna um objeto {@link android.os.IBinder} que define a interface de programao
que os clientes podem usar para interagir com o servio.</p>

<div class="sidebox-wrapper">
<div class="sidebox">
  <h3>Vinculao com um servio iniciado</h3>

<p>Como discutido na documentao <a href="{@docRoot}guide/components/services.html">Servios</a>,
 possvel criar um servio que j foi iniciado e vinculado. Ou seja, o servio pode
ser iniciado chamando {@link android.content.Context#startService startService()}, que permite que ele
permanea em execuo indefinidamente e tambm permite que um cliente vincule-o chamando {@link
android.content.Context#bindService bindService()}.
  <p>Se voc permitir que o servio seja iniciado e vinculado, ento, quando ele
for iniciado, o sistema <em>no</em> o destruir quando todos os clientes desfizerem a vnculo. Em vez disso, voc deve
interromper o servio explicitamente chamando {@link android.app.Service#stopSelf stopSelf()} ou {@link
android.content.Context#stopService stopService()}.</p>

<p>Apesar de normalmente se implementar {@link android.app.Service#onBind onBind()}
<em>ou</em> {@link android.app.Service#onStartCommand onStartCommand()}, s vezes
 necessrio implementar ambos. Por exemplo, um reprodutor de msica pode achar til permitir que o seu servio
permanea em execuo indefinidamente, alm de fornecer vinculao. Desta forma, uma atividade pode iniciar o servio
para reproduzir algumas msicas e a msica continuar em reproduo mesmo quando o usurio sair do aplicativo. Em seguida, quando o usurio
voltar ao aplicativo, a atividade poder vincular-se ao servio para retomar o controle da reproduo.</p>

<p>Certifique-se de ler a seo sobre <a href="#Lifecycle">Gerenciamento do ciclo de vida de um servio
vinculado</a> para obter mais informaes sobre o ciclo de vida do servio ao adicionar vinculao
a um servio iniciado.</p>
</div>
</div>

<p>Um cliente pode vincular-se ao servio chamando {@link android.content.Context#bindService
bindService()}. Quando isto ocorre,  preciso fornecer uma implementao de {@link
android.content.ServiceConnection}, que monitora a conexo com o servio. O mtodo {@link
android.content.Context#bindService bindService()} retorna imediatamente sem um valor,
mas quando o sistema Android cria a conexo entre
o cliente e o servio, 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 servio.</p>

<p>Vrios clientes podem conectar-se ao servio de uma vez. No entanto, o sistema chama o mtodo
{@link android.app.Service#onBind onBind()} do servio 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.</p>

<p>Quando o ltimo cliente desvincular-se do servio, o sistema destruir o servio
(a no ser que ele tambm seja iniciado por {@link android.content.Context#startService startService()}).</p>

<p>Ao implementar o servio vinculado, o mais importante  definir a interface
que o mtodo de retorno de chamada {@link android.app.Service#onBind onBind()} retornar. H poucas maneiras diferentes
de definir a interface {@link android.os.IBinder} do servio e a
seo a seguir discute cada tcnica.</p>


<h2 id="Creating">Criao de um servio vinculado</h2>

<p>Ao criar um servio que fornece vinculao, voc deve fornecer um {@link android.os.IBinder}
que oferea a interface de programao que os clientes podem usar para interagir com o servio. H trs maneiras
possveis de definir a interface:</p>

<dl>
  <dt><a href="#Binder">Extenso da classe Binder</a></dt>
  <dd>Se o servio for privado para o prprio aplicativo e for executado no mesmo processo que o cliente
(o que  comum), deve-se criar a interface estendendo-se a classe {@link android.os.Binder}
e retornando uma instncia dela a partir de
{@link android.app.Service#onBind onBind()}. O cliente receber {@link android.os.Binder}
e poder us-lo para acessar os mtodos pblicos disponveis na implementao de {@link android.os.Binder}
ou at em {@link android.app.Service} diretamente.
  <p>Esta  a tcnica preferencial quando o servio  meramente um trabalhador de segundo plano
para o aplicativo. O nico motivo pelo qual no se criaria a interface desta maneira
 porque o servio est sendo usado por outros aplicativos ou em processos separados.</dd>

  <dt><a href="#Messenger">Uso de um mensageiro</a></dt>
  <dd>Caso precise que a interface funcione em diferentes processos,  possvel
criar uma interface para o servio com {@link android.os.Messenger}. Desta maneira, o servio
define um {@link android.os.Handler} que responde a diferentes tipos de objetos {@link
android.os.Message}. Este {@link android.os.Handler}
 a base para {@link android.os.Messenger}, que pode ento compartilhar um {@link android.os.IBinder}
com o cliente, permitindo que ele envie comandos ao servio usando objetos {@link
android.os.Message}. Alm disso, o cliente pode definir o prprio {@link android.os.Messenger}
para que o servio possa enviar as mensagens de volta.
  <p>Esta  a maneira mais simples de estabelecer comunicao entre processos (IPC), pois o {@link
android.os.Messenger} coloca todas as solicitaes em fila em um nico encadeamento para que voc no precise
projetar o servio de modo que seja seguro para encadeamentos.</p>
  </dd>

  <dt>Uso de AIDL</dt>
  <dd>O AIDL (Android Interface Definition Language, linguagem de definio de interface do Android) realiza todo o trabalho de decomposio de objetos
em primitivos para que o sistema operacional possa entend-los e disp-los em processos
para realizar a IPC. A tcnica anterior, usando o {@link android.os.Messenger}, tem base em AIDL
como a estrutura fundamental. Como mencionado acima, o {@link android.os.Messenger} cria uma fila
de todas as solicitaes de cliente em um nico encadeamento para que o servio receba uma solicitao por vez. Se, no entanto,
voc quiser que o servio lide com vrias solicitaes simultaneamente,  possvel usar a AIDL
diretamente. Neste caso, o servio dever ser capaz de realizar vrios encadeamentos e ser programado de forma segura para encadeamentos.
  <p>Para usar a AIDL diretamente, deve-se
criar um arquivo {@code .aidl} que defina a interface de programao. 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 servio.</p>
  </dd>
</dl>

  <p class="note"><strong>Observao:</strong> a maioria dos aplicativos <strong>no deve</strong> usar a AIDL
para criar um servio vinculado, pois isto requer capacidade de se trabalhar com encadeamentos mltiplos
e pode resultar em uma implementao mais complicada. Portanto, a AIDL no  adequada para a maioria dos aplicativos
e este documento no discute o seu uso para o servio. Caso tenha certeza de que
precisa usar a AIDL diretamente, consulte a documentao
<a href="{@docRoot}guide/components/aidl.html">AIDL</a>.</p>


<h3 id="Binder">Extenso da classe Binder</h3>

<p>Se o servio for usado somente pelo aplicativo local e no precisar trabalhar entre processos,
ento ser possvel implementar a prpria classe {@link android.os.Binder} que fornece ao cliente
acesso direto aos mtodos pblicos no servio.</p>

<p class="note"><strong>Observao:</strong> isto funciona somente se o cliente e o servio
estiverem no mesmo aplicativo e processo, o que  muito comum. Por exemplo, isto funcionaria bem para um
aplicativo de msica que precise vincular uma atividade ao prprio servio que est
reproduzindo msica em segundo plano.</p>

<p>Como configurar:</p>
<ol>
  <li>No servio, crie uma instncia de {@link android.os.Binder} que:
    <ul>
      <li>contenha mtodos pblicos que o cliente possa chamar</li>
      <li>retorne ao cliente a instncia {@link android.app.Service}, que tenha mtodos pblicos
que ele possa chamar</li>
      <li>ou retorne uma instncia de outra classe hospedada pelo servio com mtodos pblicos
que o cliente possa chamar</li>
    </ul>
  <li>Retorne esta instncia de {@link android.os.Binder} a partir do mtodo de retorno de chamada {@link
android.app.Service#onBind onBind()}.</li>
  <li>No cliente, receba o {@link android.os.Binder} a partir do mtodo de retorno de chamada {@link
android.content.ServiceConnection#onServiceConnected onServiceConnected()}
e faa chamadas para o servios vinculados usando os mtodos fornecidos.</li>
</ol>

<p class="note"><strong>Observao:</strong> o motivo pelo qual o servio e o cliente devem estar no mesmo aplicativo
 para que o cliente possa lanar o objeto retornado e chamar as APIs adequadamente. O servio e o cliente
tambm devem estar no mesmo processo, pois esta tcnica no possui
nenhuma ingerncia entre processos.</p>

<p>Por exemplo, a seguir h um servio que fornece aos clientes acesso aos mtodos no servio
por meio de uma implementao de {@link android.os.Binder}:</p>

<pre>
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;
        }
    }

    &#64;Override
    public IBinder onBind(Intent intent) {
        return mBinder;
    }

    /** method for clients */
    public int getRandomNumber() {
      return mGenerator.nextInt(100);
    }
}
</pre>

<p>O {@code LocalBinder} fornece o mtodo {@code getService()} para que os clientes
recuperem a instncia atual de {@code LocalService}. Isto permite que os clientes chamem mtodos pblicos
no servio. Por exemplo, eles podem chamar {@code getRandomNumber()} a partir do servio.</p>

<p>Abaixo h uma atividade que vincula-se a {@code LocalService} e chama {@code getRandomNumber()}
quando um boto  pressionado:</p>

<pre>
public class BindingActivity extends Activity {
    LocalService mService;
    boolean mBound = false;

    &#64;Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }

    &#64;Override
    protected void onStart() {
        super.onStart();
        // Bind to LocalService
        Intent intent = new Intent(this, LocalService.class);
        bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
    }

    &#64;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() {

        &#64;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;
        }

        &#64;Override
        public void onServiceDisconnected(ComponentName arg0) {
            mBound = false;
        }
    };
}
</pre>

<p>O exemplo acima mostra como o cliente vincula um servio usando uma implementao
de {@link android.content.ServiceConnection} e o retorno de chamada {@link
android.content.ServiceConnection#onServiceConnected onServiceConnected()}. A prxima seo
fornece mais informaes sobre este processo de vinculao ao servio.</p>

<p class="note"><strong>Observao:</strong> o exemplo acima no desfaz a vinculao explicitamente a partir do servio,
mas todos os clientes devem faz-lo no momento adequado (como quando a atividade pausa).</p>

<p>Para obter mais cdigos de exemplo, consulte a classe <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code
LocalService.java}</a> e a classe <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.html">{@code
LocalServiceActivities.java}</a> em <a href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p>


<h3 id="Messenger">Uso de um mensageiro</h3>

<div class="sidebox-wrapper">
<div class="sidebox">
  <h4>Comparado ao AIDL</h4>
  <p>Quando  necessrio 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 servio, enquanto que uma interface de AIDL pura envia solicitaes simultneas
ao servio, que deve ento lidar com vrios encadeamentos.</p>
  <p>Para a maioria dos aplicativos, o servio no precisa realizar vrios encadeamentos. Portanto, usar {@link
android.os.Messenger} permite que o servio lide com uma chamada por vez. Caso seja importante
que o servio realize vrios encadeamentos, deve-se usar a <a href="{@docRoot}guide/components/aidl.html">AIDL</a> para definir a interface.</p>
</div>
</div>

<p>Caso precise que o servio comunique-se com processos remotos,  possvel usar
o {@link android.os.Messenger} para fornecer a interface ao servio. Esta tcnica permite
estabelecer comunicao entre processos (IPC) sem precisar usar a AIDL.</p>

<p>A seguir h um resumo sobre como usar um {@link android.os.Messenger}:</p>

<ul>
  <li>O servio implementa um {@link android.os.Handler} que recebe um retorno de chamada
para cada chamada de um cliente.</li>
  <li>O {@link android.os.Handler}  usado para criar um objeto {@link android.os.Messenger}
(que  uma referncia para o {@link android.os.Handler}).</li>
  <li>O {@link android.os.Messenger} cria um {@link android.os.IBinder} que o servio
retorna aos clientes a partir de {@link android.app.Service#onBind onBind()}.</li>
  <li>Os clientes usam {@link android.os.IBinder} para instanciar o {@link android.os.Messenger}
(que menciona o {@link android.os.Handler} do servio), que usam para enviar objetos
{@link android.os.Message} para o servio.</li>
  <li>O servio recebe cada {@link android.os.Message} em seu {@link
android.os.Handler} &mdash; especificamente, no mtodo {@link android.os.Handler#handleMessage
handleMessage()}.</li>
</ul>


<p>Desta forma, no h "mtodos" para o cliente chamar no servio. Em vez disso, o cliente
envia "mensagens" (objetos {@link android.os.Message}) que o servio recebe
no {@link android.os.Handler}.</p>

<p>Abaixo h um exemplo simples de servio que usa uma interface {@link android.os.Messenger}:</p>

<pre>
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 {
        &#64;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.
     */
    &#64;Override
    public IBinder onBind(Intent intent) {
        Toast.makeText(getApplicationContext(), "binding", Toast.LENGTH_SHORT).show();
        return mMessenger.getBinder();
    }
}
</pre>

<p>Observe que o mtodo {@link android.os.Handler#handleMessage handleMessage()}
no {@link android.os.Handler}  onde o servio recebe a {@link android.os.Message}
e decide o que fazer, com base no membro {@link android.os.Message#what}.</p>

<p>Tudo que o cliente precisa fazer  criar um {@link android.os.Messenger} com base no {@link
android.os.IBinder} retornado pelo servio e enviar uma mensagem usando {@link
android.os.Messenger#send send()}. Por exemplo, a seguir h uma atividade simples que vincula-se
ao servio e envia a mensagem {@code MSG_SAY_HELLO} a ele:</p>

<pre>
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();
        }
    }

    &#64;Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }

    &#64;Override
    protected void onStart() {
        super.onStart();
        // Bind to the service
        bindService(new Intent(this, MessengerService.class), mConnection,
            Context.BIND_AUTO_CREATE);
    }

    &#64;Override
    protected void onStop() {
        super.onStop();
        // Unbind from the service
        if (mBound) {
            unbindService(mConnection);
            mBound = false;
        }
    }
}
</pre>

<p>Observe que este exemplo no mostra como o servio pode responder ao cliente. Caso queira que o servio responda,
 necessrio criar um {@link android.os.Messenger} no cliente tambm. 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 servio que inclui
o {@link android.os.Messenger} no parmetro {@link android.os.Message#replyTo}
do mtodo {@link android.os.Messenger#send send()}.</p>

<p> possvel ver um exemplo de como fornecer mensagens de duas vias nos exemplos <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.html">{@code
MessengerService.java}</a> (servio) e <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.html">{@code
MessengerServiceActivities.java}</a> (cliente).</p>


<h2 id="Binding">Vinculao a um servio</h2>

<p>Um componente de aplicativo (cliente) pode vincular-se a um servio chamando
{@link android.content.Context#bindService bindService()}. O sistema Android, em seguida,
chama o mtodo {@link android.app.Service#onBind
onBind()} do servio, que retorna um {@link android.os.IBinder} para interagir com o servio.</p>

<p>A vinculao  assncrona. {@link android.content.Context#bindService
bindService()} retorna imediatamente e <em>no</em> retorna o {@link android.os.IBinder}
ao cliente. Para receber {@link android.os.IBinder}, o cliente deve criar uma instncia de {@link
android.content.ServiceConnection} e pass-la para {@link android.content.Context#bindService
bindService()}. O {@link android.content.ServiceConnection} inclui um mtodo de retorno de chamada
que o sistema chama para entregar o {@link android.os.IBinder}.</p>

<p class="note"><strong>Observao:</strong> somente atividades, servios e provedores de contedo
podem vincular-se a um servio &mdash; voc <strong>no</strong> pode fazer isto a partir de um receptor de transmisso.</p>

<p>Portanto, para vincular-se a um servio a partir do cliente, deve-se: </p>
<ol>
  <li>Implementar {@link android.content.ServiceConnection}.
    <p>Sua implementao deve substituir dois mtodos de retorno de chamada:</p>
    <dl>
      <dt>{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}</dt>
        <dd>O sistema chama isto para entregar o {@link android.os.IBinder} retornado
pelo mtodo {@link android.app.Service#onBind onBind()} do servio.</dd>
      <dt>{@link android.content.ServiceConnection#onServiceDisconnected
onServiceDisconnected()}</dt>
        <dd>O sistema Android chama isto quando a conexo ao servio  perdida inesperadamente,
 como quando o servio apresenta problemas ou  fechado repentinamente. Isto <em>no</em>  chamado quando
o cliente desfaz o vnculo.</dd>
    </dl>
  </li>
  <li>Chamar {@link
android.content.Context#bindService bindService()}, passando a implementao {@link
android.content.ServiceConnection}. </li>
  <li>Quando o sistema chamar o mtodo de retorno de chamada {@link android.content.ServiceConnection#onServiceConnected
onServiceConnected()},  possvel fazer chamadas para o servio
usando os mtodos definidos pela interface.</li>
  <li>Para desconectar-se de um servio, chamar {@link
android.content.Context#unbindService unbindService()}.
    <p>Quando um cliente  destrudo, o vnculo com o servio acaba. No entanto, sempre desvincule-se
ao terminar a interao com o servio ou quando a atividade pausar para que o servio
possa ser encerrado enquanto no estiver em uso (os momentos adequados para vincular ou desvincular
so abordados mais abaixo).</p>
  </li>
</ol>

<p>Por exemplo, o fragmento a seguir conecta o cliente ao servio criado acima
<a href="#Binder">estendendo a classe Binder</a> para que tudo que ele tenha que fazer seja lanar
o {@link android.os.IBinder} retornado para a classe {@code LocalService} e solicitar a instncia de {@code
LocalService}:</p>

<pre>
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;
    }
};
</pre>

<p>Com este {@link android.content.ServiceConnection}, o cliente pode vincular-se a um servio
passando-o para {@link android.content.Context#bindService bindService()}. Por exemplo:</p>

<pre>
Intent intent = new Intent(this, LocalService.class);
bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
</pre>

<ul>
  <li>O primeiro parmetro de {@link android.content.Context#bindService bindService()}
 uma {@link android.content.Intent} que nomeia explicitamente o servio que ser vinculado (apesar de a inteno
poder ser implcita).</li>
<li>O segundo parmetro  o objeto {@link android.content.ServiceConnection}.</li>
<li>O terceiro parmetro  um sinalizador que indica as opes de vinculao. Geralmente, ele deve ser {@link
android.content.Context#BIND_AUTO_CREATE} para criar o servio se no estiver ativo ainda.
Outros possveis valores so {@link android.content.Context#BIND_DEBUG_UNBIND}
e {@link android.content.Context#BIND_NOT_FOREGROUND}, ou {@code 0} para nada.</li>
</ul>


<h3>Observaes adicionais</h3>

<p>A seguir h algumas observaes importantes sobre a vinculao com um servio:</p>
<ul>
  <li>Deve-se sempre capturar excees{@link android.os.DeadObjectException}, que so lanadas
quando a conexo apresenta erros. Esta  a nica exceo lanada por mtodos remotos.</li>
  <li>Objetos so referncias contadas em todos os processos. </li>
  <li>Geralmente, alterna-se entre a vinculao e a desvinculao
durante os momentos crescentes e decrescentes do ciclo de vida do cliente. Por exemplo:
    <ul>
      <li>Caso precise interagir com o servio enquanto a atividade estiver visvel,
deve-se vincular durante {@link android.app.Activity#onStart onStart()} e desvincular durante {@link
android.app.Activity#onStop onStop()}.</li>
      <li>Caso queira que a atividade receba mensagens mesmo quando for interrompida
em segundo plano,  possvel vincular durante {@link android.app.Activity#onCreate onCreate()}
e desvincular durante {@link android.app.Activity#onDestroy onDestroy()}. Cuidado, pois isto significa que a atividade
precisa usar o servio durante todo o tempo de execuo (mesmo em segundo plano).
Portanto, se o servio estiver em outro processo, o peso do processo ser aumentado
e  mais provvel que o sistema elimine-o.</li>
    </ul>
    <p class="note"><strong>Observao:</strong> geralmente, <strong>no</strong> se realiza o vnculo 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 transies do ciclo de vida
e deve-se usar menos processamento possvel nessas transaes. Alm disso,
se vrias atividades no aplicativo vincularem-se ao mesmo servio e houver uma transao entre duas
dessas atividades, o servio poder ser destrudo e recriado  medida que a atividade desvincula-se,
durante a pausa, antes do prximo vnculo, durante a retomada (esta transio de atividade
para como as atividades coordenam os ciclos de vida  descrita no documento <a href="{@docRoot}guide/components/activities.html#CoordinatingActivities">Atividades</a>
).</p>
</ul>

<p>Para obter mais cdigos de exemplomostrando como vincular a um servio, consulte a classe <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code
RemoteService.java}</a> no <a href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p>


<h2 id="Lifecycle">Gerenciamento do ciclo de vida de um servio vinculado</h2>

<p>Quando um servio  desvinculado de todos os clientes, o sistema Android o destri (a no ser que ele
tambm tenha sido inicializado com {@link android.app.Service#onStartCommand onStartCommand()}). Portanto, no  necessrio
gerenciar o ciclo de vida do servio se ele for puramente um servio vinculado
&mdash; o sistema Android o gerencia com base nos vnculos com os clientes.</p>

<p>No entanto, se voc escolher implementar o mtodo de retorno de chamada {@link android.app.Service#onStartCommand
onStartCommand()}, interrompa o servio explicitamente, pois o servio
j ter sido considerado como <em>iniciado</em>. Neste caso, o servio permanece em execuo at
ser interrompido com {@link android.app.Service#stopSelf()} ou outras chamadas de componente {@link
android.content.Context#stopService stopService()}, independente de vnculo
com qualquer cliente.</p>

<p>Alm disso, se o servio for iniciado e aceitar vnculos, quando o sistema chamar
o mtodo {@link android.app.Service#onUnbind onUnbind()}, ser possvel retornar
{@code true} opcionalmente se voc quiser receber uma chamada de {@link android.app.Service#onRebind
onRebind()} na prxima vez em que um cliente vincular-se ao servio (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 lgica para este tipo de ciclo de vida.</p>


<img src="{@docRoot}images/fundamentals/service_binding_tree_lifecycle.png" alt="" />
<p class="img-caption"><strong>Figura 1.</strong> O ciclo de vida para um servio que  iniciado
e tambm permite vnculos.</p>


<p>Para obter mais informaes sobre o ciclo de vida de um servio iniciado, consulte o documento <a href="{@docRoot}guide/components/services.html#Lifecycle">Servios</a>.</p>