guide/components/services.jd

page.title=
@jd:body

<div id="qv-wrapper">
<ol id="qv">
<h2></h2>
<ol>
<li><a href="#Basics"></a></li>
<ol>
  <li><a href="#Declaring"></a></li>
</ol>
<li><a href="#CreatingAService"></a>
  <ol>
    <li><a href="#ExtendingIntentService"> IntentService </a></li>
    <li><a href="#ExtendingService"></a></li>
    <li><a href="#StartingAService"></a></li>
    <li><a href="#Stopping"></a></li>
  </ol>
</li>
<li><a href="#CreatingBoundService"></a></li>
<li><a href="#Notifications"></a></li>
<li><a href="#Foreground"></a></li>
<li><a href="#Lifecycle"></a>
<ol>
  <li><a href="#LifecycleCallbacks"></a></li>
</ol>
</li>
</ol>

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

<h2></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></h2>
<ol>
<li><a href="{@docRoot}guide/components/bound-services.html"></a></li>
</ol>

</div>


<p>{@link android.app.Service}


 (IPC)
/

</p>

<p></p>

<dl>
  <dt></dt>
  <dd> ( Activity)
{@link android.content.Context#startService startService()}


</dd>
  <dt></dt>
  <dd> {@link
android.content.Context#bindService bindService()}  (IPC)


</dd>
</dl>

<p> &mdash;  ()
{@link
android.app.Service#onStartCommand onStartCommand()}  {@link
android.app.Service#onBind onBind()}
</p>

<p> () Activity  &mdash;  {@link android.content.Intent}


<a href="#Declaring"></a>

</p>

<p class="caution"><strong></strong> &mdash; <strong></strong><strong></strong> ()

 CPU  ( MP3 )

 (ANR)  Activity

</p>


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

<div class="sidebox-wrapper">
<div class="sidebox">
  <h3></h3>
  <p>

</p>
  <p>
 Activity
{@link android.app.Activity#onCreate onCreate()}  {@link
android.app.Activity#onStart onStart()}  {@link android.app.Activity#onStop
onStop()}
 {@link android.os.AsyncTask}  {@link android.os.HandlerThread} {@link java.lang.Thread}
<a href="{@docRoot}guide/components/processes-and-threads.html#Threads"></a>
</p>
  <p>

</p>
</div>
</div>

<p> {@link android.app.Service}  ()


</p>

<dl>
  <dt>{@link android.app.Service#onStartCommand onStartCommand()}</dt>
    <dd> ( Activity)  {@link android.content.Context#startService
startService()}

 {@link android.app.Service#stopSelf stopSelf()}  {@link
android.content.Context#stopService stopService()}
()
</dd>
  <dt>{@link android.app.Service#onBind onBind()}</dt>
    <dd> ( RPC)  {@link android.content.Context#bindService
bindService()}
 {@link android.os.IBinder}
 null
</dd>
  <dt>{@link android.app.Service#onCreate()}</dt>
    <dd> ( {@link android.app.Service#onStartCommand onStartCommand()}
{@link android.app.Service#onBind onBind()} )

</dd>
  <dt>{@link android.app.Service#onDestroy()}</dt>
    <dd>

</dd>
</dl>

<p> {@link
android.content.Context#startService startService()} ( {@link
android.app.Service#onStartCommand onStartCommand()} )  {@link android.app.Service#stopSelf()}
{@link android.content.Context#stopService stopService()}
</p>

<p>
{@link android.content.Context#bindService bindService()}  ( {@link
android.app.Service#onStartCommand onStartCommand()}<em></em>)

</p>

<p> Activity Android
 Activity<a href="#Foreground"></a> ()
 &mdash;


 ( {@link
android.app.Service#onStartCommand onStartCommand()} )
<a href="{@docRoot}guide/components/processes-and-threads.html"></a>

</p>

<p>
</p>


<h3 id="Declaring"></h3>

<p> Activity ()
</p>

<p> <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a>  <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>

</p>

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

<p> <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a>
</p>

<p> <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a>

<a href="{@docRoot}guide/topics/manifest/service-element.html#nm">{@code android:name}</a>  &mdash;
 (<a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html"></a>)


<p><strong> {@link android.app.Service} </strong>
 {@link
android.content.Intent}  {@link
android.content.Intent#setPackage setPackage()}


</p>

<p> <a href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a>  {@code "false"}


</p>


<h2 id="CreatingStartedService"></h2>

<p> {@link
android.content.Context#startService startService()}
{@link android.app.Service#onStartCommand onStartCommand()} </p>

<p>

 {@link android.app.Service#stopSelf stopSelf()}  {@link android.content.Context#stopService stopService()}

</p>

<p> Activity  {@link
android.content.Context#startService startService()}
{@link android.content.Intent} {@link android.app.Service#onStartCommand
onStartCommand()}  {@link android.content.Intent}
</p>

<p> Activity  {@link
android.content.Context#startService startService()}Activity
 {@link
android.app.Service#onStartCommand onStartCommand()}

</p>

<p class="caution"><strong></strong>
 Activity  Activity


</p>

<p></p>
<dl>
  <dt>{@link android.app.Service}</dt>
  <dd> Activity


</dd>
  <dt>{@link android.app.IntentService}</dt>
  <dd> {@link android.app.Service}  worker

 {@link
android.app.IntentService#onHandleIntent onHandleIntent()}
</dd>
</dl>

<p>
</p>


<h3 id="ExtendingIntentService"> IntentService </h3>

<p>() {@link android.app.IntentService}

</p>

<p>{@link android.app.IntentService} </p>

<ul>
  <li> worker  {@link
android.app.Service#onStartCommand onStartCommand()}
</li>
  <li> {@link
android.app.IntentService#onHandleIntent onHandleIntent()}
</li>
  <li>
{@link android.app.Service#stopSelf}</li>
  <li> null  {@link android.app.IntentService#onBind onBind()}
</li>
  <li> {@link android.app.IntentService#onStartCommand
onStartCommand()}  {@link
android.app.IntentService#onHandleIntent onHandleIntent()} </li>
</ul>

<p> {@link
android.app.IntentService#onHandleIntent onHandleIntent()}
()</p>

<p> {@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>{@link
android.app.IntentService#onHandleIntent onHandleIntent()} </p>

<p> {@link
android.app.IntentService#onCreate onCreate()}{@link
android.app.IntentService#onStartCommand onStartCommand()}  {@link
android.app.IntentService#onDestroy onDestroy()}
{@link android.app.IntentService}  worker </p>

<p>{@link android.app.IntentService#onStartCommand onStartCommand()}  ( {@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> {@link android.app.IntentService#onHandleIntent onHandleIntent()} {@link android.app.IntentService#onBind
onBind()} ()
</p>

<p> {@link android.app.Service}

</p>


<h3 id="ExtendingService"></h3>

<p> {@link android.app.IntentService}
 () {@link android.app.Service}

</p>

<p> {@link
android.app.Service}  {@link
android.app.IntentService}  worker
</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> {@link android.app.IntentService}</p>

<p> {@link android.app.Service#onStartCommand
onStartCommand()}  ()

</p>

<p>{@link android.app.Service#onStartCommand onStartCommand()}
 ( {@link
android.app.IntentService} )

{@link android.app.Service#onStartCommand onStartCommand()}
</p>

<dl>
  <dt>{@link android.app.Service#START_NOT_STICKY}</dt>
    <dd> {@link android.app.Service#onStartCommand
onStartCommand()} <em></em>

</dd>
  <dt>{@link android.app.Service#START_STICKY}</dt>
    <dd> {@link android.app.Service#onStartCommand
onStartCommand()}  {@link
android.app.Service#onStartCommand onStartCommand()}<em></em>
 null  {@link android.app.Service#onStartCommand onStartCommand()}

 ()
</dd>
  <dt>{@link android.app.Service#START_REDELIVER_INTENT}</dt>
    <dd> {@link android.app.Service#onStartCommand
onStartCommand()}  {@link
android.app.Service#onStartCommand onStartCommand()}

</dd>
</dl>
<p>
</p>


<h3 id="StartingAService"></h3>

<p>
{@link android.content.Intent} ()  {@link
android.content.Context#startService startService()} Activity Android  {@link
android.app.Service#onStartCommand onStartCommand()}  {@link
android.content.Intent} ( {@link android.app.Service#onStartCommand
onStartCommand()})</p>

<p> {@link android.content.Context#startService
startService()}Activity  ({@code
HelloSevice})</p>

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

<p>{@link android.content.Context#startService startService()} Android  {@link android.app.Service#onStartCommand
onStartCommand()}
 {@link
android.app.Service#onCreate onCreate()} {@link android.app.Service#onStartCommand
onStartCommand()}</p>

<p> {@link
android.content.Context#startService startService()}
 {@link android.app.PendingIntent}( {@link android.app.PendingIntent#getBroadcast getBroadcast()})  {@link android.content.Intent}


</p>

<p>
{@link android.app.Service#onStartCommand onStartCommand()} ( {@link android.app.Service#stopSelf stopSelf()}  {@link
android.content.Context#stopService stopService()})
</p>


<h3 id="Stopping"></h3>

<p> {@link android.app.Service#onStartCommand onStartCommand()}

 {@link android.app.Service#stopSelf stopSelf()}  {@link android.content.Context#stopService stopService()}

</p>

<p> {@link android.app.Service#stopSelf stopSelf()}  {@link
android.content.Context#stopService stopService()}
</p>

<p> {@link
android.app.Service#onStartCommand onStartCommand()}  ()

 {@link android.app.Service#stopSelf(int)}

 {@link
android.app.Service#stopSelf(int)}  ID (<code>startId</code>  {@link android.app.Service#onStartCommand onStartCommand()})

 {@link
android.app.Service#stopSelf(int)}  ID </p>

<p class="caution"><strong></strong>
 {@link
android.content.Context#stopService stopService()}
 {@link
android.app.Service#onStartCommand onStartCommand()}
</p>

<p><a href="#Lifecycle"></a></p>


<h2 id="CreatingBoundService"></h2>

<p> {@link
android.content.Context#bindService bindService()}  ( {@link
android.content.Context#startService startService()} <em></em> )
</p>

<p> (IPC) Activity

</p>

<p> {@link
android.app.Service#onBind onBind()}
{@link android.os.IBinder} ()
{@link android.content.Context#bindService bindService()}

 (
{@link android.app.Service#onStartCommand onStartCommand()} <em></em>)
</p>

<p>
 {@link android.os.IBinder}  {@link android.app.Service#onBind
onBind()}

 {@link android.os.IBinder}
</p>

<p> {@link android.content.Context#unbindService unbindService()}

</p>

<p><a href="{@docRoot}guide/components/bound-services.html"></a>

</p>


<h2 id="Notifications"></h2>

<p><a href="{@docRoot}guide/topics/ui/notifiers/toasts.html"></a><a href="{@docRoot}guide/topics/ui/notifiers/notifications.html"></a></p>

<p> ( Activity)

</p>

<p>()

 Activity ()
</p>

<p><a href="{@docRoot}guide/topics/ui/notifiers/toasts.html"></a><a href="{@docRoot}guide/topics/ui/notifiers/notifications.html"></a>
</p>


<h2 id="Foreground"></h2>

<p>


</p>

<p>

 Activity
</p>

<p> {@link
android.app.Service#startForeground startForeground()} {@link
android.app.Notification}
</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></strong> {@link
android.app.Service#startForeground startForeground()}  ID  0</p>


<p> {@link
android.app.Service#stopForeground stopForeground()}
<em></em>

</p>

<p><a href="{@docRoot}guide/topics/ui/notifiers/notifications.html"></a>
</p>


<h2 id="Lifecycle"></h2>

<p> Activity

</p>

<p> &mdash;  &mdash;
</p>

<ul>
<li>
  <p> {@link
android.content.Context#startService startService()}  {@link
android.app.Service#stopSelf() stopSelf()}
 {@link android.content.Context#stopService
stopService()}
</p></li>

<li>
  <p> ()  {@link
android.content.Context#bindService bindService()}
{@link android.os.IBinder}
{@link android.content.Context#unbindService unbindService()}
(<em></em>)
</p></li>
</ul>

<p>
{@link android.content.Context#startService startService()}  {@link android.content.Context#startService
startService()}  {@link android.content.Intent}
 Activity  {@link
android.content.Context#bindService bindService()}

 {@link
android.content.Context#stopService stopService()}  {@link android.app.Service#stopSelf
stopSelf()}  </p>


<h3 id="LifecycleCallbacks"></h3>

<p> Activity

</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></strong> Activity <em></em>
</p>

<img src="{@docRoot}images/service_lifecycle.png" alt="" />
<p class="img-caption"><strong> 2.</strong> {@link android.content.Context#startService
startService()}
{@link android.content.Context#bindService bindService()}
</p>

<p> </p>

<ul>
<li><strong></strong> {@link
android.app.Service#onCreate onCreate()}  {@link
android.app.Service#onDestroy}  Activity
{@link android.app.Service#onCreate onCreate()}  {@link
android.app.Service#onDestroy onDestroy()}  {@link
android.app.Service#onCreate onCreate()}  {@link
android.app.Service#onDestroy onDestroy()}


<p>{@link android.app.Service#onCreate onCreate()}  {@link android.app.Service#onDestroy
onDestroy()}  {@link android.content.Context#startService startService()}  {@link
android.content.Context#bindService bindService()}
</p></li>

<li><strong></strong> {@link
android.app.Service#onStartCommand onStartCommand()}  {@link android.app.Service#onBind onBind()}
 {@link
android.content.Intent} {@link android.content.Context#startService
startService()}  {@link android.content.Context#bindService bindService()}
<p> ( {@link android.app.Service#onStartCommand
onStartCommand()} )
 {@link
android.app.Service#onUnbind onUnbind()} </p>
</li>
</ul>

<p class="note"><strong></strong>
 {@link android.app.Service#stopSelf stopSelf()}  {@link
android.content.Context#stopService stopService()}  ( {@code onStop()} )
 &mdash; {@link
android.app.Service#onDestroy onDestroy()}
</p>

<p> 2
{@link android.content.Context#startService startService()}
{@link android.content.Context#bindService bindService()}

 {@link android.app.Service#onStartCommand
onStartCommand()}  ( {@link android.content.Context#startService startService()}) {@link android.app.Service#onBind onBind()}  (
{@link android.content.Context#bindService bindService()} )
</p>

<p><a href="{@docRoot}guide/components/bound-services.html"></a><a href="{@docRoot}guide/components/bound-services.html#Lifecycle"></a> {@link android.app.Service#onRebind onRebind()}


</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>
-->