guide/components/services.jd

page.title=Servios
@jd:body

<div id="qv-wrapper">
<ol id="qv">
<h2>Neste documento</h2>
<ol>
<li><a href="#Basics">Conceitos bsicos</a></li>
<ol>
  <li><a href="#Declaring">Declarao de servio no manifesto</a></li>
</ol>
<li><a href="#CreatingAService">Criao de servio iniciado</a>
  <ol>
    <li><a href="#ExtendingIntentService">Extenso da classe IntentService</a></li>
    <li><a href="#ExtendingService">Extenso da classe Service</a></li>
    <li><a href="#StartingAService">Incio de servio</a></li>
    <li><a href="#Stopping">Interrupo de servio</a></li>
  </ol>
</li>
<li><a href="#CreatingBoundService">Criao de servio vinculado</a></li>
<li><a href="#Notifications">Envio de notificaes ao usurio</a></li>
<li><a href="#Foreground">Execuo de servio em primeiro plano</a></li>
<li><a href="#Lifecycle">Gerenciamento do ciclo de vida de um servio</a>
<ol>
  <li><a href="#LifecycleCallbacks">Implementao dos retornos de chamada do ciclo de vida</a></li>
</ol>
</li>
</ol>

<h2>Classes principais</h2>
<ol>
  <li>{@link android.app.Service}</li>
  <li>{@link android.app.IntentService}</li>
</ol>

<h2>Exemplos</h2>
<ol>
  <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ServiceStartArguments.html">{@code
      ServiceStartArguments}</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/bound-services.html">Servios vinculados</a></li>
</ol>

</div>


<p>Um {@link android.app.Service}  um componente do aplicativo que pode realizar
operaes longas e no fornece uma interface do usurio. Outro componente do aplicativo
pode iniciar um servio e ele continuar em execuo em segundo plano mesmo que o usurio
alterne para outro aplicativo. Alm disso, um componente poder vincular-se a um servio
para interagir com ele e at estabelecer comunicao entre processos (IPC). Por exemplo, um servio pode lidar
com operaes de rede, reproduzir msica, executar E/S de arquivos, ou interagir com um provedor de contedo,
tudo a partir do segundo plano.</p>

<p>Um servio pode essencialmente ter duas formas:</p>

<dl>
  <dt>Iniciado</dt>
  <dd>Um servio  "iniciado" quando um componente do aplicativo (como um atividade)
inicia-o chamando {@link android.content.Context#startService startService()}. Quando iniciado, um servio
pode ficar em execuo em segundo plano indefinidamente, mesmo que o componente que o iniciou seja destrudo. Geralmente,
um servio iniciado realiza uma nica operao e no retorna um resultado para o autor da chamada.
Por exemplo, ele pode fazer download ou upload de um arquivo pela rede. Quando a operao for concluda,
o servio dever ser interrompido.</dd>
  <dt>Vinculado</dt>
  <dd>Um servio  "vinculado" quando um componente do aplicativo o vincula chamando {@link
android.content.Context#bindService bindService()}. Um servio vinculado oferece uma interface
servidor-cliente que permite que os componentes interajam com a interface, enviem solicitaes, obtenham resultados,
mesmo em processos com comunicao interprocessual (IPC). Um servio vinculado permanece em execuo somente enquanto
outro componente do aplicativo estiver vinculado a ele. Vrios componentes podem ser vinculados ao servio de uma s vez,
mas quando todos desfizerem o vnculo, o servio ser destrudo.</dd>
</dl>

<p>Apesar de esta documentao discutir os dois tipos de servios separadamente,
um servio pode funcionar das duas maneiras &mdash; ele pode ser iniciado (para permanecer em execuo indefinidamente) e tambm permitir a vinculao.
Basta voc implementar alguns mtodos de retorno de chamada: {@link
android.app.Service#onStartCommand onStartCommand()} para permitir que os componentes iniciem o servio e {@link
android.app.Service#onBind onBind()} para permitir a vinculao.</p>

<p>Se o aplicativo for iniciado, vinculado ou ambos, qualquer componente do aplicativo
poder usar o servio (mesmo a partir de um aplicativo separado), da mesma forma que qualquer componente poder usar
uma atividade &mdash; iniciando com uma {@link android.content.Intent}. No entanto,  possvel declarar
o servio como privado, no arquivo do manifesto, e bloquear o acesso de outros aplicativos. Isto  discutido com mais detalhes
na seo <a href="#Declaring">Declarao do servio
no manifesto</a>.</p>

<p class="caution"><strong>Ateno:</strong> um servio  executado
no encadeamento principal em seu processo de hospedagem &mdash; o servio <strong>no</strong> cria seu prprio encadeamento
e <strong>no</strong>  executado em um processo separado (salvo se especificado). Isso significa que,
 se o servio for realizar qualquer trabalho intensivo de CPU ou operaes de bloqueio (como reproduo
de MP3 ou rede), voc deve criar um novo encadeamento dentro do servio. Usando um encadeamento separado,
voc reduzir o risco da ocorrncia de erros de Aplicativo no respondendo (ANR)
e o encadeamento principal do aplicativo poder permanecer dedicado  interao do usurio com as atividades.</p>


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

<div class="sidebox-wrapper">
<div class="sidebox">
  <h3>Voc deve usar um servio ou um encadeamento?</h3>
  <p>Um servio  simplesmente um componente que pode ser executado em segundo plano mesmo quando o usurio
no est interagindo com o aplicativo. Portanto, um servio deve ser criado somente
se for realmente necessrio.</p>
  <p>Caso precise realizar trabalhos fora do encadeamento principal, mas somente enquanto o usurio estiver interagindo
com o aplicativo, ento voc deve criar um novo encadeamento e no um servio. Por exemplo,
se quiser reproduzir msicas, mas somente enquanto a atividade estiver em execuo, voc pode criar um encadeamento
em {@link android.app.Activity#onCreate onCreate()}, iniciando a execuo em {@link
android.app.Activity#onStart onStart()}, e interrompendo em {@link android.app.Activity#onStop
onStop()}. Considere tambm usar {@link android.os.AsyncTask} ou {@link android.os.HandlerThread},
em vez de a classe tradicional {@link java.lang.Thread}. Consulte o documento <a href="{@docRoot}guide/components/processes-and-threads.html#Threads">Processos e
encadeamentos</a> para obter mais informaes sobre encadeamentos.</p>
  <p>Lembre-se de que, se usar um servio, ele ainda ser executado no encadeamento principal do aplicativo por padro,
portanto deve-se criar um novo encadeamento dentro do servio se ele realizar operaes
intensivas ou de bloqueio.</p>
</div>
</div>

<p>Para criar um servio, voc deve criar uma subclasse de {@link android.app.Service}
(ou uma das subclasses existentes). Na implementao, ser necessrio substituir alguns mtodos de retorno de chamada
que lidem com aspectos essenciais do ciclo de vida do servio e forneam um mecanismo para vincular
componentes ao servio, se apropriado. Os dois mtodos mais importantes de retorno de chamada que voc deve substituir so:</p>

<dl>
  <dt>{@link android.app.Service#onStartCommand onStartCommand()}</dt>
    <dd>O sistema chama este mtodo quando outro componente, como uma atividade,
solicita que o servio seja iniciado, chamando {@link android.content.Context#startService
startService()}. Quando este mtodo  executado, o servio  iniciado e pode ser executado
em segundo plano indefinidamente. Se implementar isto,  de sua responsabilidade interromper o servio
quando o trabalho for concludo, chamando {@link android.app.Service#stopSelf stopSelf()} ou {@link
android.content.Context#stopService stopService()} (caso queira somente fornecer a vinculao,
no  necessrio implementar este mtodo).</dd>
  <dt>{@link android.app.Service#onBind onBind()}</dt>
    <dd>O sistema chama este mtodo quando outro componente quer vincular-se
ao servio (como para realizaes de RPC) chamando {@link android.content.Context#bindService
bindService()}. Na implementao deste mtodo, voc deve fornecer uma interface que os clientes
usem para comunicar-se com o servio, retornando um {@link android.os.IBinder}. Voc sempre deve implementar este mtodo,
mas, se no quiser permitir a vinculao, retorne nulo.</dd>
  <dt>{@link android.app.Service#onCreate()}</dt>
    <dd>O sistema chama este mtodo quando o servio  criado pela primeira vez para realizar procedimentos nicos
de configurao (antes de chamar {@link android.app.Service#onStartCommand onStartCommand()} ou
{@link android.app.Service#onBind onBind()}). Se o servio j estiver em execuo, este mtodo
no  chamado.</dd>
  <dt>{@link android.app.Service#onDestroy()}</dt>
    <dd>O sistema chama este mtodo quando o servio no  mais usado e est sendo destrudo.
O servio deve implementar isto para limpar quaisquer recursos, como encadeamentos, escutas
registradas, receptores etc. Esta  a ltima chamada que o servio recebe.</dd>
</dl>

<p>Se um componente iniciar o servio chamando {@link
android.content.Context#startService startService()} (o que resulta em uma chamada para {@link
android.app.Service#onStartCommand onStartCommand()}),
o servio permanecer em execuo at ser interrompido por conta prpria com {@link android.app.Service#stopSelf()} ou por outro componente
chamando {@link android.content.Context#stopService stopService()}.</p>

<p>Se um componente
chamar {@link android.content.Context#bindService bindService()} para criar o servio (e {@link
android.app.Service#onStartCommand onStartCommand()} <em>no</em> for chamado), o servio ser executado
somente enquanto o componente estiver vinculado a ele. Quando o servio for desvinculado de todos os clientes,
o sistema o destruir.</p>

<p>O sistema Android forar a interrupo de um servio somente quando a memria estiver baixa e precisar
recuperar os recursos do sistema para a atividade com que o usurio estiver interagindo. Se o servio estiver vinculado a uma atividade que o usurio
tenha atribudo foco,  menos provvel que ele seja eliminado. E, se o servio for declarado para <a href="#Foreground">ser executado em primeiro plano</a> (discutido posteriormente), ento ele quase nunca ser eliminado.
Caso contrrio, se o servio for iniciado e estiver em uma longa execuo, o sistema reduzir sua posio
na lista de tarefas de segundo plano no decorrer do tempo e o servio se tornar altamente suscetvel
 eliminao &mdash; se o servio for iniciado, ento voc deve program-lo para lidar
com reinicializaes pelo sistema. Se o sistema eliminar o seu servio, ele reiniciar assim que os recursos
estiverem disponveis novamente (apesar de isto tambm depender do valor que voc retornar de {@link
android.app.Service#onStartCommand onStartCommand()}, como discutido a seguir). Para obter mais informaes sobre
quando o sistema deve destruir um servio, consulte o documento <a href="{@docRoot}guide/components/processes-and-threads.html">Processos e encadeamentos</a>
.</p>

<p>Nas seguintes sees, voc ver como  possvel criar cada tipo de servio e como
us-los a partir de outros componentes do aplicativo.</p>


<h3 id="Declaring">Declarao de servio no manifesto</h3>

<p>Como atividades (e outros componentes), voc deve declarar todos os servios no arquivo de manifesto
do aplicativo.</p>

<p>Para declarar o servio, adicione um elemento <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a>
como filho do elemento <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>
. Por exemplo:</p>

<pre>
&lt;manifest ... &gt;
  ...
  &lt;application ... &gt;
      &lt;service android:name=".ExampleService" /&gt;
      ...
  &lt;/application&gt;
&lt;/manifest&gt;
</pre>

<p>Consulte a referncia de elemento <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a>
para obter mais informaes sobre como declarar o servio no manifesto.</p>

<p> possvel incluir outros atributos no elemento <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a>
para definir propriedades como permisses necessrias para iniciar o servio e o processo
em que o servio deve ser executado. O atributo <a href="{@docRoot}guide/topics/manifest/service-element.html#nm">{@code android:name}</a>
 o nico necessrio &mdash; ele especifica o nome da classe do servio. Ao publicar o aplicativo,
 no deve-se alterar-lhe o nome porque, se isso acontecer, h riscos de ocorrncia de erros
de cdigo devido  dependncia de intenes explcitas para iniciar ou vincular o servio (leia a publicao do blogue, <a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Coisas
que no podem mudar</a>).

<p>Para garantir a segurana do aplicativo, <strong>sempre use uma inteno explcita ao iniciar ou vincular
{@link android.app.Service}</strong> e no declare filtros de inteno para o servio. Caso seja essencial permitir alguma ambiguidade, como qual servio deve ser usado para iniciar,
 possvel fornecer filtros de intenes
para os servios e excluir o nome do componente de {@link
android.content.Intent}, mas  preciso definir o pacote para a inteno com {@link
android.content.Intent#setPackage setPackage()}, que fornece desambiguidade suficiente para
o servio alvo.</p>

<p>Alm disso,  possvel garantir que o servio esteja disponvel somente para o aplicativo
incluindo o atributo <a href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a>
e definindo-o como {@code "false"}. Isto impede efetivamente que outros aplicativos iniciem o servio,
 mesmo usando uma inteno explcita.</p>


<h2 id="CreatingStartedService">Criao de um servio iniciado</h2>

<p>Um servio iniciado  o que outro componente inicia chamando {@link
android.content.Context#startService startService()}, resultando em uma chamada para o mtodo
{@link android.app.Service#onStartCommand onStartCommand()} do servio.</p>

<p>Quando um servio  iniciado, ele tem um ciclo de vida que no depende do componente
que o iniciou. Alm disso, o servio pode ser executado em segundo plano indefinidamente,
mesmo se o componente que o iniciou for eliminado. Alm disso, o servio deve ser interrompido quando o seu trabalho
for realizado, chamando {@link android.app.Service#stopSelf stopSelf()}. Outros componentes podem interromp-lo
chamando {@link android.content.Context#stopService stopService()}.</p>

<p>Um componente do aplicativo, como uma atividade, pode iniciar o servio chamando {@link
android.content.Context#startService startService()} e passando {@link android.content.Intent},
que especifica o servio e inclui os dados para o servio usar. O servio
recebe esta {@link android.content.Intent} no mtodo {@link android.app.Service#onStartCommand
onStartCommand()}.</p>

<p>Por exemplo, presuma que uma atividade precise salvar alguns dados em um banco de dados on-line. A atividade pode iniciar
um servio de acompanhamento e entregar a ele os dados a salvar passando uma inteno para {@link
android.content.Context#startService startService()}. O servio recebe a inteno em {@link
android.app.Service#onStartCommand onStartCommand()}, conecta-se  Internet e realiza
a transao no banco de dados. Quando a operao  concluda, o servio  interrompido
e destrudo.</p>

<p class="caution"><strong>Ateno:</strong> um servio  executado no mesmo processo que o aplicativo
em que ele  declarado e no encadeamento principal do aplicativo, por padro. Portanto, se o servio
realizar operaes intensivas ou de bloqueio quando o usurio interagir com uma atividade do mesmo aplicativo,
diminuir o desempenho da atividade. Para evitar impacto no desempenho do aplicativo,
deve-se iniciar um novo encadeamento dentro do servio.</p>

<p>Geralmente, h duas classes que podem ser estendidas para criar um servio iniciado:</p>
<dl>
  <dt>{@link android.app.Service}</dt>
  <dd>Esta  a classe de base para todos os servios. Ao estender esta classe,  importante
criar um novo encadeamento para fazer todo o trabalho do servio, pois o servio usa
o encadeamento principal do aplicativo, por padro, o que deve diminuir o desempenho de qualquer atividade
que o aplicativo estiver executando.</dd>
  <dt>{@link android.app.IntentService}</dt>
  <dd>Esta  uma subclasse de {@link android.app.Service} que usa um encadeamento de trabalho para lidar
com todas as solicitaes de inicializao, uma por vez. Esta  a melhor opo se no quiser que o servio
lide com vrias solicitaes simultaneamente. Tudo que precisa fazer  implementar {@link
android.app.IntentService#onHandleIntent onHandleIntent()}, que recebe a inteno para cada solicitao
de incio para que voc possa realizar o trabalho de segundo plano.</dd>
</dl>

<p>As seguintes sees descrevem como  possvel implementar o servio usando
uma dessas classes.</p>


<h3 id="ExtendingIntentService">Extenso da classe IntentService</h3>

<p>Como a maioria dos servios no precisam lidar com vrias solicitaes simultaneamente
(o que pode ser perigoso para situaes de vrios encadeamentos),  melhor
se o servio for implementado usando a classe {@link android.app.IntentService}.</p>

<p>O {@link android.app.IntentService} faz o seguinte:</p>

<ul>
  <li>Cria um encadeamento de trabalho padro que executa todas as intenes entregues a {@link
android.app.Service#onStartCommand onStartCommand()} separado do encadeamento principal
do aplicativo.</li>
  <li>Cria uma fila de trabalho que passa uma inteno por vez  implementao {@link
android.app.IntentService#onHandleIntent onHandleIntent()}, para que nunca seja necessrio
preocupar-se com vrios encadeamentos.</li>
  <li>Interrompe o servio depois que todas as solicitaes forem resolvidas para que no seja necessrio chamar
{@link android.app.Service#stopSelf}.</li>
  <li>Fornece implementaes padro de {@link android.app.IntentService#onBind onBind()}
que retornam como nulo.</li>
  <li>Fornece uma implementao padro de {@link android.app.IntentService#onStartCommand
onStartCommand()} que envia a inteno para a fila de trabalho e, em seguida, para a implementao de {@link
android.app.IntentService#onHandleIntent onHandleIntent()}.</li>
</ul>

<p>Tudo isso adiciona-se ao fato de que basta implementar {@link
android.app.IntentService#onHandleIntent onHandleIntent()} para fazer o trabalho fornecido
pelo cliente (embora tambm seja necessrio fornecer um pequeno construtor para o servio).</p>

<p>A seguir h um exemplo de implementao de {@link android.app.IntentService}:</p>

<pre>
public class HelloIntentService extends IntentService {

  /**
   * A constructor is required, and must call the super {@link android.app.IntentService#IntentService}
   * constructor with a name for the worker thread.
   */
  public HelloIntentService() {
      super("HelloIntentService");
  }

  /**
   * The IntentService calls this method from the default worker thread with
   * the intent that started the service. When this method returns, IntentService
   * stops the service, as appropriate.
   */
  &#64;Override
  protected void onHandleIntent(Intent intent) {
      // Normally we would do some work here, like download a file.
      // For our sample, we just sleep for 5 seconds.
      long endTime = System.currentTimeMillis() + 5*1000;
      while (System.currentTimeMillis() &lt; endTime) {
          synchronized (this) {
              try {
                  wait(endTime - System.currentTimeMillis());
              } catch (Exception e) {
              }
          }
      }
  }
}
</pre>

<p> tudo que voc precisa: um construtor e uma implementao de {@link
android.app.IntentService#onHandleIntent onHandleIntent()}.</p>

<p>Caso decida substituir outros mtodos de retorno de chamada, como {@link
android.app.IntentService#onCreate onCreate()}, {@link
android.app.IntentService#onStartCommand onStartCommand()} ou {@link
android.app.IntentService#onDestroy onDestroy()}, certifique-se de chamar a super-implementao
para que o {@link android.app.IntentService} possa lidar adequadamente com a vida do encadeamento de trabalho.</p>

<p>Por exemplo, {@link android.app.IntentService#onStartCommand onStartCommand()} deve retornar
a implementao padro (que  como a inteno  entregue para {@link
android.app.IntentService#onHandleIntent onHandleIntent()}):</p>

<pre>
&#64;Override
public int onStartCommand(Intent intent, int flags, int startId) {
    Toast.makeText(this, "service starting", Toast.LENGTH_SHORT).show();
    return super.onStartCommand(intent,flags,startId);
}
</pre>

<p>Alm de {@link android.app.IntentService#onHandleIntent onHandleIntent()}, o nico mtodo
que no precisa ser usado para chamar a superclasse  {@link android.app.IntentService#onBind
onBind()} (mas  necessrio implement-lo se o servio permitir vinculaes).</p>

<p>Na prxima seo, voc ver como o mesmo tipo de servio  implementado ao estender
a classe de base {@link android.app.Service}, que possui muito mais cdigos, mas que pode
ser apropriada para lidar com solicitaes de inicializao simultneas.</p>


<h3 id="ExtendingService">Extenso da classe Service</h3>

<p>Como voc viu na seo anterior, o uso de {@link android.app.IntentService}
torna a implementao de um servio iniciado muito simples. Se, no entanto, voc precisa do servio
para realizar vrios encadeamentos (em vez de processar as solicitaes de inicializao por meio de uma fila de trabalho),
 possvel estender a classe {@link android.app.Service} para lidar com cada inteno.</p>

<p>Para efeito de comparao, o seguinte exemplo de cdigo  uma implementao da classe {@link
android.app.Service} que realiza exatamente o mesmo trabalho que o exemplo acima usando {@link
android.app.IntentService}. Ou seja, para cada solicitao de inicializao, ela usa um encadeamento
de trabalho para realizar o trabalho e processa apenas uma solicitao por vez.</p>

<pre>
public class HelloService extends Service {
  private Looper mServiceLooper;
  private ServiceHandler mServiceHandler;

  // Handler that receives messages from the thread
  private final class ServiceHandler extends Handler {
      public ServiceHandler(Looper looper) {
          super(looper);
      }
      &#64;Override
      public void handleMessage(Message msg) {
          // Normally we would do some work here, like download a file.
          // For our sample, we just sleep for 5 seconds.
          long endTime = System.currentTimeMillis() + 5*1000;
          while (System.currentTimeMillis() &lt; endTime) {
              synchronized (this) {
                  try {
                      wait(endTime - System.currentTimeMillis());
                  } catch (Exception e) {
                  }
              }
          }
          // Stop the service using the startId, so that we don't stop
          // the service in the middle of handling another job
          stopSelf(msg.arg1);
      }
  }

  &#64;Override
  public void onCreate() {
    // Start up the thread running the service.  Note that we create a
    // separate thread because the service normally runs in the process's
    // main thread, which we don't want to block.  We also make it
    // background priority so CPU-intensive work will not disrupt our UI.
    HandlerThread thread = new HandlerThread("ServiceStartArguments",
            Process.THREAD_PRIORITY_BACKGROUND);
    thread.start();

    // Get the HandlerThread's Looper and use it for our Handler
    mServiceLooper = thread.getLooper();
    mServiceHandler = new ServiceHandler(mServiceLooper);
  }

  &#64;Override
  public int onStartCommand(Intent intent, int flags, int startId) {
      Toast.makeText(this, "service starting", Toast.LENGTH_SHORT).show();

      // For each start request, send a message to start a job and deliver the
      // start ID so we know which request we're stopping when we finish the job
      Message msg = mServiceHandler.obtainMessage();
      msg.arg1 = startId;
      mServiceHandler.sendMessage(msg);

      // If we get killed, after returning from here, restart
      return START_STICKY;
  }

  &#64;Override
  public IBinder onBind(Intent intent) {
      // We don't provide binding, so return null
      return null;
  }

  &#64;Override
  public void onDestroy() {
    Toast.makeText(this, "service done", Toast.LENGTH_SHORT).show();
  }
}
</pre>

<p>Como pode ver,  muito mais trabalhoso do que usar {@link android.app.IntentService}.</p>

<p>No entanto, como voc lida com cada chamada de {@link android.app.Service#onStartCommand
onStartCommand()},  possvel realizar vrias solicitaes simultaneamente. Isso no  o que este exemplo faz,
mas, se for o que quer,  possvel criar um novo encadeamento
para cada solicitao e execut-las na hora (em vez de esperar que a solicitao anterior seja concluda).</p>

<p>Observe que o mtodo {@link android.app.Service#onStartCommand onStartCommand()} deve retornar
um nmero inteiro. O nmero inteiro  um valor que descreve como o sistema deve continuar o servio
no evento em que o sistema o eliminar (como discutido acima, a implementao padro de {@link
android.app.IntentService} lida com isto, apesar de ser possvel modific-lo). O valor de retorno
de {@link android.app.Service#onStartCommand onStartCommand()} deve ser uma das seguintes
constantes:</p>

<dl>
  <dt>{@link android.app.Service#START_NOT_STICKY}</dt>
    <dd>Se o sistema eliminar o servio aps o retorno de {@link android.app.Service#onStartCommand
onStartCommand()}, <em>no</em> recrie o servio, a no ser que tenha
intenes pendentes para entregar. Esta  a opo mais segura para evitar executar o servio quando desnecessrio
e quando o aplicativo puder simplesmente reiniciar qualquer trabalho incompleto.</dd>
  <dt>{@link android.app.Service#START_STICKY}</dt>
    <dd>Se o sistema eliminar o servio aps o retorno de {@link android.app.Service#onStartCommand
onStartCommand()}, recrie o servio e chame {@link
android.app.Service#onStartCommand onStartCommand()}, mas <em>no</em> entregue novamente a ltima inteno.
Em vez disso, o sistema chama {@link android.app.Service#onStartCommand onStartCommand()} com inteno nula,
a no ser que tenha intenes pendentes para iniciar o servio e,
nesse caso, essas intenes so entregues. Isto  adequado para reprodutores de mdia (ou servios semelhantes)
que no estejam executando comandos, mas estejam em execuo indefinidamente e aguardando um trabalho.</dd>
  <dt>{@link android.app.Service#START_REDELIVER_INTENT}</dt>
    <dd>Se o sistema eliminar o servio aps o retorno de {@link android.app.Service#onStartCommand
onStartCommand()}, recrie o servio e chame {@link
android.app.Service#onStartCommand onStartCommand()} com a ltima inteno que foi entregue
ao servio. Quaisquer intenes pendentes so entregues, por sua vez. Isto  adequado para servios que estejam realizando
um trabalho ativamente que deva ser retomado imediatamente, como o download de um arquivo.</dd>
</dl>
<p>Para obter mais informaes sobre esses valores de retorno, veja a documentao de referncia vinculada
a cada constante.</p>


<h3 id="StartingAService">Incio de um servio</h3>

<p> possvel iniciar um dispositivo de uma atividade ou outro componente do aplicativo passando uma
{@link android.content.Intent} a {@link
android.content.Context#startService startService()}. O sistema Android chama o mtodo {@link
android.app.Service#onStartCommand onStartCommand()} do servio e passa a ele a {@link
android.content.Intent} (nunca deve-se chamar {@link android.app.Service#onStartCommand
onStartCommand()} diretamente).</p>

<p>Por exemplo, uma atividade pode iniciar o servio de exemplo na seo anterior ({@code
HelloSevice}) usando uma inteno explcita com {@link android.content.Context#startService
startService()}:</p>

<pre>
Intent intent = new Intent(this, HelloService.class);
startService(intent);
</pre>

<p>O mtodo {@link android.content.Context#startService startService()} retorna imediatamente
e o sistema Android chama o mtodo {@link android.app.Service#onStartCommand
onStartCommand()} do servio. Se o servio no estiver em execuo, o sistemo primeiro chama {@link
android.app.Service#onCreate onCreate()} e, em seguida, chama {@link android.app.Service#onStartCommand
onStartCommand()}.</p>

<p>Se o servio no fornecer vinculao, a inteno entregue com {@link
android.content.Context#startService startService()}  o nico modo de comunicao entre
o componente do aplicativo e o servio. No entanto, se quiser que o servio envie um resultado de volta,
o cliente que iniciar o servio poder criar um {@link android.app.PendingIntent} para uma transmisso
(com {@link android.app.PendingIntent#getBroadcast getBroadcast()}) e entreg-la ao servio
na {@link android.content.Intent} que iniciar o servio. O servio pode ento
usar a transmisso para entregar um resultado.</p>

<p>Vrias solicitaes para iniciar o servio resultam em diversas chamadas correspondentes
ao {@link android.app.Service#onStartCommand onStartCommand()} do servio. No entanto, somente uma solicitao para interromper
o servio (com {@link android.app.Service#stopSelf stopSelf()} ou {@link
android.content.Context#stopService stopService()})  necessria para interromp-lo.</p>


<h3 id="Stopping">Interrupo de um servio</h3>

<p>Um servio iniciado deve gerenciar seu prprio ciclo de vida. Ou seja, o sistema no interrompe
ou elimina o servio, a no ser que tenha que recuperar a memria do sistema e o servio
continuar em execuo depois que {@link android.app.Service#onStartCommand onStartCommand()} retornar. Portanto,
o servio deve ser interrompido chamando {@link android.app.Service#stopSelf stopSelf()} ou outro
componente pode interromp-lo chamando {@link android.content.Context#stopService stopService()}.</p>

<p>Ao solicitar o interrompimento com {@link android.app.Service#stopSelf stopSelf()} ou {@link
android.content.Context#stopService stopService()}, o sistema elimina o servio
assim que possvel.</p>

<p>No entanto, se o servio lida com vrias solicitaes para {@link
android.app.Service#onStartCommand onStartCommand()} ao mesmo tempo, no se deve interromper
o servio ao terminar o processamento de uma solicitao de inicializao, pois  possvel
que uma nova solicitao de inicializao tenha ocorrido (interromper no final da primeira solicitao eliminaria a segunda). Para evitar este problema,
 possvel usar {@link android.app.Service#stopSelf(int)} para garantir que a solicitao
que interrompe o servio sempre se baseie na solicitao de inicializao mais recente. Ou seja, ao chamar {@link
android.app.Service#stopSelf(int)}, voc passa o ID da solicitao de inicializao (o <code>startId</code>
entregue a {@link android.app.Service#onStartCommand onStartCommand()}) para aquele que solicitao de interrompimento
corresponde. Em seguida, se o servio receber uma nova solicitao de inicializao antes de ser possvel chamar {@link
android.app.Service#stopSelf(int)}, o ID no corresponder e o servio no ser interrompido.</p>

<p class="caution"><strong>Ateno:</strong>  importante que um aplicativo interrompa seus servios
quando terminar os trabalhos para evitar o desperdcio dos recursos do sistema e consumo da bateria. Se necessrio,
outros componentes podem interromper o servio chamando {@link
android.content.Context#stopService stopService()}. Mesmo se for possvel vincular-se ao servio,
deve-se sempre interromp-lo por conta prpria se ele tiver recebido uma chamada de {@link
android.app.Service#onStartCommand onStartCommand()}.</p>

<p>Para obter mais informaes sobre o ciclo de vida de um servio, consulte a seo <a href="#Lifecycle">Gerenciamento do ciclo de vida de um servio</a> abaixo.</p>


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

<p>Um servio vinculado permite que componentes de aplicativo sejam vinculados chamando {@link
android.content.Context#bindService bindService()} para criar uma conexo de longo prazo
(e, geralmente, no permite que os componentes o <em>iniciem</em> chamando {@link
android.content.Context#startService startService()}).</p>

<p>Deve-se criar um servio vinculado quando se deseja interagir com o servio a partir de atividades
e outros componentes no aplicativo ou para expor algumas das funcionalidades do aplicativo
para outros aplicativos, por meio de comunicao entre processos (IPC).</p>

<p>Para criar um servio vinculado, voc deve implementar o mtodo de retorno de chamada {@link
android.app.Service#onBind onBind()} para retornar um {@link android.os.IBinder}
que define a interface para a comunicao com o servio. Outros componentes de aplicativo podem chamar
{@link android.content.Context#bindService bindService()} para recuperar a interface
e comear a chamar mtodos no servio. O servio vive somente para servir o componente do aplicativo
ao qual ele est vinculado. Portanto, quando no houver componentes vinculados ao servio, o sistema o eliminar
(<em>no</em>  necessrio interromper um servio vinculado da mesma maneira que quando o servio  iniciado
por meio de {@link android.app.Service#onStartCommand onStartCommand()}).</p>

<p>Para criar um servio vinculado, a primeira coisa a se fazer  definir a interface que especifica
como um cliente pode comunicar-se com o servidor. Esta interface entre o servio
e um cliente deve ser uma implementao de {@link android.os.IBinder} e  o que o servio deve retornar
a partir do mtodo de retorno de chamada {@link android.app.Service#onBind
onBind()}. Quando o cliente receber {@link android.os.IBinder}, ele poder comear
a interagir com o servio por meio da interface.</p>

<p>Vrios clientes podem vincular-se ao servio por vez. Quando um cliente terminar de interagir com o servio,
 ele chamar {@link android.content.Context#unbindService unbindService()} para desvincular-se. Quando no houver
clientes vinculados ao servio, o sistema o eliminar.</p>

<p>H vrias maneiras de implementar um servio vinculado e a implementao  mais complicada
que um servio iniciado. Logo, a discusso sobre servios vinculados aparece em um documento separado
sobre <a href="{@docRoot}guide/components/bound-services.html">Servios vinculados</a>.</p>


<h2 id="Notifications">Enviar notificaes ao usurio</h2>

<p>Quando em execuo, um servio pode notificar o usurio sobre eventos usando <a href="{@docRoot}guide/topics/ui/notifiers/toasts.html">Notificaes de aviso</a> ou <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notificaes da barra de status</a>.</p>

<p>Uma notificao de aviso  uma mensagem que aparece na superfcie da janela atual
por um breve momento antes de desaparecer, enquanto que uma notificao da barra de status fornece um cone na barra de status
com uma mensagem que o usurio pode selecionar para realizar uma ao (como iniciar uma atividade).</p>

<p>Geralmente, uma notificao da barra de status  a melhor tcnica quando um trabalho de segundo plano  concludo
(como download
de arquivo completo) e o usurio pode agir a partir dele. Quando o usurio seleciona a notificao a partir
da vista expandida, ela pode iniciar uma atividade (como a vista do arquivo baixado).</p>

<p>Consulte os guias de desenvolvedor <a href="{@docRoot}guide/topics/ui/notifiers/toasts.html">Notificaes de aviso</a> ou <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notificaes da barra de status</a>
para obter mais informaes.</p>


<h2 id="Foreground">Execuo de servio em primeiro plano</h2>

<p>Um servio de primeiro plano  aquele
com que o usurio est ativamente interagindo e no  uma opo para o sistema elimin-lo quando a memria estiver baixa. Um servio de primeiro plano
deve fornecer uma notificao para a barra de status, que  colocada sob
"o cabealho "Em andamento", o que significa que a notificao no pode ser dispensada a no ser que o servio
seja interrompido ou removido do primeiro plano.</p>

<p>Por exemplo, um reprodutor de msica que reproduz a partir de um servio deve ser configurado
para permanecer em execuo em primeiro plano, pois o usurio est
prestando ateno em sua operao explicitamente. A notificao na barra de status pode indicar a msica atual
e permitir que o usurio inicie uma atividade para interagir com o reprodutor de msica.</p>

<p>Para solicitar que o servio seja executado em primeiro plano, chame {@link
android.app.Service#startForeground startForeground()}. Este mtodo usa dois parmetros: um nmero inteiro
que identifica unicamente a notificao e {@link
android.app.Notification} para a barra de status. Por exemplo:</p>

<pre>
Notification notification = new Notification(R.drawable.icon, getText(R.string.ticker_text),
        System.currentTimeMillis());
Intent notificationIntent = new Intent(this, ExampleActivity.class);
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
notification.setLatestEventInfo(this, getText(R.string.notification_title),
        getText(R.string.notification_message), pendingIntent);
startForeground(ONGOING_NOTIFICATION_ID, notification);
</pre>

<p class="caution"><strong>Ateno:</strong> O ID do nmero inteiro fornecido para {@link
android.app.Service#startForeground startForeground()} no deve ser zero.</p>


<p>Para remover o servio do primeiro plano, chame {@link
android.app.Service#stopForeground stopForeground()}. Este mtodo usa um booleano,
indicando se deve remover tambm a notificao da barra de status. Este mtodo <em>no</em> interrompe
o servio. No entanto, se voc interromper o servio enquanto estiver em execuo em primeiro plano,
a notificao tambm ser removida.</p>

<p>Para obter mais informaes sobre notificaes, consulte <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Criao de notificaes
da barra de status</a>.</p>


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

<p>O ciclo de vida de um servio  muito mais simples do que o de uma atividade. No entanto,  ainda mais importante
que voc preste muita ateno em como o servio  criado e eliminado, pois ele
pode ser executado em primeiro plano sem que o usurio esteja ciente.</p>

<p>O ciclo de vida do servio &mdash; desde quando  criado at ser eliminado &mdash; pode seguir
dois caminhos:</p>

<ul>
<li>Um servio iniciado
  <p>O servio  criado quando outro componente chama {@link
android.content.Context#startService startService()}. Depois, o servio permanece em execuo indefinidamente e deve
interromper-se chamando {@link
android.app.Service#stopSelf() stopSelf()}. Outro componente tambm pode interromper
o servio chamando {@link
android.content.Context#stopService stopService()}. Quando o servio  interrompido, o sistema o elimina.</p></li>

<li>Um servio vinculado
  <p>O servio  criado quando outro componente (um cliente) chama {@link
android.content.Context#bindService bindService()}. O cliente comunica-se com o servio
pela interface {@link android.os.IBinder}. O cliente pode escolher encerrar a conexo chamando
{@link android.content.Context#unbindService unbindService()}. Vrios clientes podem ser vinculados
ao mesmo servio e, quando todos os vnculos terminam, o sistema destri o servio (o servio
<em>no</em> precisa ser interrompido).</p></li>
</ul>

<p>Esses dois caminhos no so inteiramente separados. Ou seja,  possvel vincular um servio
que j foi iniciado com {@link android.content.Context#startService startService()}. Por exemplo, um servio de msica
de segundo plano pode ser iniciado chamando {@link android.content.Context#startService
startService()} com uma {@link android.content.Intent} que identifica a msica reproduzida. Depois,
possivelmente quando o usurio quiser exercer mais controle sobre o reprodutor ou obter informaes
sobre a msica em reproduo, uma atividade pode ser vinculada ao servio chamando {@link
android.content.Context#bindService bindService()}. Em casos como esse, {@link
android.content.Context#stopService stopService()} ou {@link android.app.Service#stopSelf
stopSelf()} no interrompe o servio at que todos os clientes sejam desvinculados. </p>


<h3 id="LifecycleCallbacks">Implementao de retornos de chamada do ciclo de vida</h3>

<p>Como uma atividade, um servio tem um mtodo de ciclo de vida que  possvel implementar
para monitorar as alteraes no estado do servio e realizar trabalhos em momentos adequados. O seguinte servio de esqueleto
demonstra cada um dos mtodos de ciclo de vida:</p>

<pre>
public class ExampleService extends Service {
    int mStartMode;       // indicates how to behave if the service is killed
    IBinder mBinder;      // interface for clients that bind
    boolean mAllowRebind; // indicates whether onRebind should be used

    &#64;Override
    public void {@link android.app.Service#onCreate onCreate}() {
        // The service is being created
    }
    &#64;Override
    public int {@link android.app.Service#onStartCommand onStartCommand}(Intent intent, int flags, int startId) {
        // The service is starting, due to a call to {@link android.content.Context#startService startService()}
        return <em>mStartMode</em>;
    }
    &#64;Override
    public IBinder {@link android.app.Service#onBind onBind}(Intent intent) {
        // A client is binding to the service with {@link android.content.Context#bindService bindService()}
        return <em>mBinder</em>;
    }
    &#64;Override
    public boolean {@link android.app.Service#onUnbind onUnbind}(Intent intent) {
        // All clients have unbound with {@link android.content.Context#unbindService unbindService()}
        return <em>mAllowRebind</em>;
    }
    &#64;Override
    public void {@link android.app.Service#onRebind onRebind}(Intent intent) {
        // A client is binding to the service with {@link android.content.Context#bindService bindService()},
        // after onUnbind() has already been called
    }
    &#64;Override
    public void {@link android.app.Service#onDestroy onDestroy}() {
        // The service is no longer used and is being destroyed
    }
}
</pre>

<p class="note"><strong>Observao:</strong> diferentemente dos mtodos de retorno de chamada do ciclo de vida da atividade,
voc <em>no</em> precisa chamar a implementao da superclasse.</p>

<img src="{@docRoot}images/service_lifecycle.png" alt="" />
<p class="img-caption"><strong>Figura 2.</strong> Ciclo de vida do servio. O diagrama  esquerda
mostra o ciclo de vida quando o servio  criado com {@link android.content.Context#startService
startService()} e o diagrama  direita mostra o ciclo de vida quando o servio
 criado com {@link android.content.Context#bindService bindService()}.</p>

<p>Ao implementar esses mtodos,  possvel monitorar dois retornos (loops) aninhados no ciclo de vida do servio: </p>

<ul>
<li><strong>Todo o ciclo de vida</strong> de um servio acontece entre o momento em que {@link
android.app.Service#onCreate onCreate()}  chamado e em que {@link
android.app.Service#onDestroy} retorna. Como uma atividade, um servio faz a sua configurao inicial
em {@link android.app.Service#onCreate onCreate()} e libera todos os recursos restantes em {@link
android.app.Service#onDestroy onDestroy()}.  Por exemplo,
um servio de reproduo de msica pode criar um encadeamento onde a msica ser reproduzida em {@link
android.app.Service#onCreate onCreate()}, e interromper o encadeamento em {@link
android.app.Service#onDestroy onDestroy()}.

<p>Os mtodos {@link android.app.Service#onCreate onCreate()} e {@link android.app.Service#onDestroy
onDestroy()} so chamados para todos os servios,
se tiverem sido criados por {@link android.content.Context#startService startService()} ou {@link
android.content.Context#bindService bindService()}.</p></li>

<li>O <strong>ciclo de vida ativo</strong> de um servio comea com uma chamada de {@link
android.app.Service#onStartCommand onStartCommand()} ou {@link android.app.Service#onBind onBind()}.
Cada mtodo entrega a {@link
android.content.Intent} que foi passada para {@link android.content.Context#startService
startService()} ou {@link android.content.Context#bindService bindService()}, respectivamente.
<p>Se o servio for iniciado, o ciclo de vida ativo terminar no mesmo momento
em que o ciclo de vida inteiro terminar (o servio permanece ativo mesmo aps o retorno de {@link android.app.Service#onStartCommand
onStartCommand()}). Se o servio estiver vinculado, o ciclo de ida ativo acabar quando {@link
android.app.Service#onUnbind onUnbind()} retornar.</p>
</li>
</ul>

<p class="note"><strong>Observao:</strong> apesar de um servio iniciado ser interrompido com uma chamada
de {@link android.app.Service#stopSelf stopSelf()} ou {@link
android.content.Context#stopService stopService()}, no h um retorno de chamada respectivo
para o servio (no h retorno de chamada de {@code onStop()}). Portanto, a no ser que o servio esteja vinculado a um cliente,
o sistema o eliminar quando for interrompido &mdash; {@link
android.app.Service#onDestroy onDestroy()} ser o nico retorno de chamada recebido.</p>

<p>A figura 2 ilustra os mtodos de retorno de chamada tradicionais para um servio. Apesar de a figura separar
os servios que so criados por {@link android.content.Context#startService startService()}
daqueles que so criados por {@link android.content.Context#bindService bindService()},
observe que qualquer servio, no importa como foi iniciado, pode permitir a vinculao de clientes.
Portanto, um servio que j foi iniciado com {@link android.app.Service#onStartCommand
onStartCommand()} (por um cliente chamando  {@link android.content.Context#startService startService()})
ainda pode receber uma chamada de {@link android.app.Service#onBind onBind()} (quando um cliente chama
{@link android.content.Context#bindService bindService()}).</p>

<p>Para obter mais informaes sobre como criar um servio que fornea vinculao, consulte o documento <a href="{@docRoot}guide/components/bound-services.html">Servios vinculados</a>,
que aborda mais profundamente o mtodo de retorno de chamada {@link android.app.Service#onRebind onRebind()}
na seo sobre <a href="{@docRoot}guide/components/bound-services.html#Lifecycle">Gerenciamento do ciclo de vida
de um servio vinculado</a>.</p>


<!--
<h2>Beginner's Path</h2>

<p>To learn how to query data from the system or other applications (such as contacts or media
stored on the device), continue with the <b><a
href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a></b>
document.</p>
-->