Home | History | Annotate | Download | only in app
      1 /*
      2  * Copyright (C) 2006 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.app;
     18 
     19 import android.content.ComponentCallbacks2;
     20 import android.content.ComponentName;
     21 import android.content.Intent;
     22 import android.content.ContextWrapper;
     23 import android.content.Context;
     24 import android.content.res.Configuration;
     25 import android.os.Build;
     26 import android.os.RemoteException;
     27 import android.os.IBinder;
     28 import android.util.Log;
     29 
     30 import java.io.FileDescriptor;
     31 import java.io.PrintWriter;
     32 
     33 /**
     34  * A Service is an application component representing either an application's desire
     35  * to perform a longer-running operation while not interacting with the user
     36  * or to supply functionality for other applications to use.  Each service
     37  * class must have a corresponding
     38  * {@link android.R.styleable#AndroidManifestService <service>}
     39  * declaration in its package's <code>AndroidManifest.xml</code>.  Services
     40  * can be started with
     41  * {@link android.content.Context#startService Context.startService()} and
     42  * {@link android.content.Context#bindService Context.bindService()}.
     43  *
     44  * <p>Note that services, like other application objects, run in the main
     45  * thread of their hosting process.  This means that, if your service is going
     46  * to do any CPU intensive (such as MP3 playback) or blocking (such as
     47  * networking) operations, it should spawn its own thread in which to do that
     48  * work.  More information on this can be found in
     49  * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">Processes and
     50  * Threads</a>.  The {@link IntentService} class is available
     51  * as a standard implementation of Service that has its own thread where it
     52  * schedules its work to be done.</p>
     53  *
     54  * <p>Topics covered here:
     55  * <ol>
     56  * <li><a href="#WhatIsAService">What is a Service?</a>
     57  * <li><a href="#ServiceLifecycle">Service Lifecycle</a>
     58  * <li><a href="#Permissions">Permissions</a>
     59  * <li><a href="#ProcessLifecycle">Process Lifecycle</a>
     60  * <li><a href="#LocalServiceSample">Local Service Sample</a>
     61  * <li><a href="#RemoteMessengerServiceSample">Remote Messenger Service Sample</a>
     62  * </ol>
     63  *
     64  * <div class="special reference">
     65  * <h3>Developer Guides</h3>
     66  * <p>For a detailed discussion about how to create services, read the
     67  * <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer guide.</p>
     68  * </div>
     69  *
     70  * <a name="WhatIsAService"></a>
     71  * <h3>What is a Service?</h3>
     72  *
     73  * <p>Most confusion about the Service class actually revolves around what
     74  * it is <em>not</em>:</p>
     75  *
     76  * <ul>
     77  * <li> A Service is <b>not</b> a separate process.  The Service object itself
     78  * does not imply it is running in its own process; unless otherwise specified,
     79  * it runs in the same process as the application it is part of.
     80  * <li> A Service is <b>not</b> a thread.  It is not a means itself to do work off
     81  * of the main thread (to avoid Application Not Responding errors).
     82  * </ul>
     83  *
     84  * <p>Thus a Service itself is actually very simple, providing two main features:</p>
     85  *
     86  * <ul>
     87  * <li>A facility for the application to tell the system <em>about</em>
     88  * something it wants to be doing in the background (even when the user is not
     89  * directly interacting with the application).  This corresponds to calls to
     90  * {@link android.content.Context#startService Context.startService()}, which
     91  * ask the system to schedule work for the service, to be run until the service
     92  * or someone else explicitly stop it.
     93  * <li>A facility for an application to expose some of its functionality to
     94  * other applications.  This corresponds to calls to
     95  * {@link android.content.Context#bindService Context.bindService()}, which
     96  * allows a long-standing connection to be made to the service in order to
     97  * interact with it.
     98  * </ul>
     99  *
    100  * <p>When a Service component is actually created, for either of these reasons,
    101  * all that the system actually does is instantiate the component
    102  * and call its {@link #onCreate} and any other appropriate callbacks on the
    103  * main thread.  It is up to the Service to implement these with the appropriate
    104  * behavior, such as creating a secondary thread in which it does its work.</p>
    105  *
    106  * <p>Note that because Service itself is so simple, you can make your
    107  * interaction with it as simple or complicated as you want: from treating it
    108  * as a local Java object that you make direct method calls on (as illustrated
    109  * by <a href="#LocalServiceSample">Local Service Sample</a>), to providing
    110  * a full remoteable interface using AIDL.</p>
    111  *
    112  * <a name="ServiceLifecycle"></a>
    113  * <h3>Service Lifecycle</h3>
    114  *
    115  * <p>There are two reasons that a service can be run by the system.  If someone
    116  * calls {@link android.content.Context#startService Context.startService()} then the system will
    117  * retrieve the service (creating it and calling its {@link #onCreate} method
    118  * if needed) and then call its {@link #onStartCommand} method with the
    119  * arguments supplied by the client.  The service will at this point continue
    120  * running until {@link android.content.Context#stopService Context.stopService()} or
    121  * {@link #stopSelf()} is called.  Note that multiple calls to
    122  * Context.startService() do not nest (though they do result in multiple corresponding
    123  * calls to onStartCommand()), so no matter how many times it is started a service
    124  * will be stopped once Context.stopService() or stopSelf() is called; however,
    125  * services can use their {@link #stopSelf(int)} method to ensure the service is
    126  * not stopped until started intents have been processed.
    127  *
    128  * <p>For started services, there are two additional major modes of operation
    129  * they can decide to run in, depending on the value they return from
    130  * onStartCommand(): {@link #START_STICKY} is used for services that are
    131  * explicitly started and stopped as needed, while {@link #START_NOT_STICKY}
    132  * or {@link #START_REDELIVER_INTENT} are used for services that should only
    133  * remain running while processing any commands sent to them.  See the linked
    134  * documentation for more detail on the semantics.
    135  *
    136  * <p>Clients can also use {@link android.content.Context#bindService Context.bindService()} to
    137  * obtain a persistent connection to a service.  This likewise creates the
    138  * service if it is not already running (calling {@link #onCreate} while
    139  * doing so), but does not call onStartCommand().  The client will receive the
    140  * {@link android.os.IBinder} object that the service returns from its
    141  * {@link #onBind} method, allowing the client to then make calls back
    142  * to the service.  The service will remain running as long as the connection
    143  * is established (whether or not the client retains a reference on the
    144  * service's IBinder).  Usually the IBinder returned is for a complex
    145  * interface that has been <a href="{@docRoot}guide/components/aidl.html">written
    146  * in aidl</a>.
    147  *
    148  * <p>A service can be both started and have connections bound to it.  In such
    149  * a case, the system will keep the service running as long as either it is
    150  * started <em>or</em> there are one or more connections to it with the
    151  * {@link android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE}
    152  * flag.  Once neither
    153  * of these situations hold, the service's {@link #onDestroy} method is called
    154  * and the service is effectively terminated.  All cleanup (stopping threads,
    155  * unregistering receivers) should be complete upon returning from onDestroy().
    156  *
    157  * <a name="Permissions"></a>
    158  * <h3>Permissions</h3>
    159  *
    160  * <p>Global access to a service can be enforced when it is declared in its
    161  * manifest's {@link android.R.styleable#AndroidManifestService &lt;service&gt;}
    162  * tag.  By doing so, other applications will need to declare a corresponding
    163  * {@link android.R.styleable#AndroidManifestUsesPermission &lt;uses-permission&gt;}
    164  * element in their own manifest to be able to start, stop, or bind to
    165  * the service.
    166  *
    167  * <p>As of {@link android.os.Build.VERSION_CODES#GINGERBREAD}, when using
    168  * {@link Context#startService(Intent) Context.startService(Intent)}, you can
    169  * also set {@link Intent#FLAG_GRANT_READ_URI_PERMISSION
    170  * Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION
    171  * Intent.FLAG_GRANT_WRITE_URI_PERMISSION} on the Intent.  This will grant the
    172  * Service temporary access to the specific URIs in the Intent.  Access will
    173  * remain until the Service has called {@link #stopSelf(int)} for that start
    174  * command or a later one, or until the Service has been completely stopped.
    175  * This works for granting access to the other apps that have not requested
    176  * the permission protecting the Service, or even when the Service is not
    177  * exported at all.
    178  *
    179  * <p>In addition, a service can protect individual IPC calls into it with
    180  * permissions, by calling the
    181  * {@link #checkCallingPermission}
    182  * method before executing the implementation of that call.
    183  *
    184  * <p>See the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>
    185  * document for more information on permissions and security in general.
    186  *
    187  * <a name="ProcessLifecycle"></a>
    188  * <h3>Process Lifecycle</h3>
    189  *
    190  * <p>The Android system will attempt to keep the process hosting a service
    191  * around as long as the service has been started or has clients bound to it.
    192  * When running low on memory and needing to kill existing processes, the
    193  * priority of a process hosting the service will be the higher of the
    194  * following possibilities:
    195  *
    196  * <ul>
    197  * <li><p>If the service is currently executing code in its
    198  * {@link #onCreate onCreate()}, {@link #onStartCommand onStartCommand()},
    199  * or {@link #onDestroy onDestroy()} methods, then the hosting process will
    200  * be a foreground process to ensure this code can execute without
    201  * being killed.
    202  * <li><p>If the service has been started, then its hosting process is considered
    203  * to be less important than any processes that are currently visible to the
    204  * user on-screen, but more important than any process not visible.  Because
    205  * only a few processes are generally visible to the user, this means that
    206  * the service should not be killed except in extreme low memory conditions.
    207  * <li><p>If there are clients bound to the service, then the service's hosting
    208  * process is never less important than the most important client.  That is,
    209  * if one of its clients is visible to the user, then the service itself is
    210  * considered to be visible.
    211  * <li><p>A started service can use the {@link #startForeground(int, Notification)}
    212  * API to put the service in a foreground state, where the system considers
    213  * it to be something the user is actively aware of and thus not a candidate
    214  * for killing when low on memory.  (It is still theoretically possible for
    215  * the service to be killed under extreme memory pressure from the current
    216  * foreground application, but in practice this should not be a concern.)
    217  * </ul>
    218  *
    219  * <p>Note this means that most of the time your service is running, it may
    220  * be killed by the system if it is under heavy memory pressure.  If this
    221  * happens, the system will later try to restart the service.  An important
    222  * consequence of this is that if you implement {@link #onStartCommand onStartCommand()}
    223  * to schedule work to be done asynchronously or in another thread, then you
    224  * may want to use {@link #START_FLAG_REDELIVERY} to have the system
    225  * re-deliver an Intent for you so that it does not get lost if your service
    226  * is killed while processing it.
    227  *
    228  * <p>Other application components running in the same process as the service
    229  * (such as an {@link android.app.Activity}) can, of course, increase the
    230  * importance of the overall
    231  * process beyond just the importance of the service itself.
    232  *
    233  * <a name="LocalServiceSample"></a>
    234  * <h3>Local Service Sample</h3>
    235  *
    236  * <p>One of the most common uses of a Service is as a secondary component
    237  * running alongside other parts of an application, in the same process as
    238  * the rest of the components.  All components of an .apk run in the same
    239  * process unless explicitly stated otherwise, so this is a typical situation.
    240  *
    241  * <p>When used in this way, by assuming the
    242  * components are in the same process, you can greatly simplify the interaction
    243  * between them: clients of the service can simply cast the IBinder they
    244  * receive from it to a concrete class published by the service.
    245  *
    246  * <p>An example of this use of a Service is shown here.  First is the Service
    247  * itself, publishing a custom class when bound:
    248  *
    249  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalService.java
    250  *      service}
    251  *
    252  * <p>With that done, one can now write client code that directly accesses the
    253  * running service, such as:
    254  *
    255  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.java
    256  *      bind}
    257  *
    258  * <a name="RemoteMessengerServiceSample"></a>
    259  * <h3>Remote Messenger Service Sample</h3>
    260  *
    261  * <p>If you need to be able to write a Service that can perform complicated
    262  * communication with clients in remote processes (beyond simply the use of
    263  * {@link Context#startService(Intent) Context.startService} to send
    264  * commands to it), then you can use the {@link android.os.Messenger} class
    265  * instead of writing full AIDL files.
    266  *
    267  * <p>An example of a Service that uses Messenger as its client interface
    268  * is shown here.  First is the Service itself, publishing a Messenger to
    269  * an internal Handler when bound:
    270  *
    271  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.java
    272  *      service}
    273  *
    274  * <p>If we want to make this service run in a remote process (instead of the
    275  * standard one for its .apk), we can use <code>android:process</code> in its
    276  * manifest tag to specify one:
    277  *
    278  * {@sample development/samples/ApiDemos/AndroidManifest.xml remote_service_declaration}
    279  *
    280  * <p>Note that the name "remote" chosen here is arbitrary, and you can use
    281  * other names if you want additional processes.  The ':' prefix appends the
    282  * name to your package's standard process name.
    283  *
    284  * <p>With that done, clients can now bind to the service and send messages
    285  * to it.  Note that this allows clients to register with it to receive
    286  * messages back as well:
    287  *
    288  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.java
    289  *      bind}
    290  */
    291 public abstract class Service extends ContextWrapper implements ComponentCallbacks2 {
    292     private static final String TAG = "Service";
    293 
    294     public Service() {
    295         super(null);
    296     }
    297 
    298     /** Return the application that owns this service. */
    299     public final Application getApplication() {
    300         return mApplication;
    301     }
    302 
    303     /**
    304      * Called by the system when the service is first created.  Do not call this method directly.
    305      */
    306     public void onCreate() {
    307     }
    308 
    309     /**
    310      * @deprecated Implement {@link #onStartCommand(Intent, int, int)} instead.
    311      */
    312     @Deprecated
    313     public void onStart(Intent intent, int startId) {
    314     }
    315 
    316     /**
    317      * Bits returned by {@link #onStartCommand} describing how to continue
    318      * the service if it is killed.  May be {@link #START_STICKY},
    319      * {@link #START_NOT_STICKY}, {@link #START_REDELIVER_INTENT},
    320      * or {@link #START_STICKY_COMPATIBILITY}.
    321      */
    322     public static final int START_CONTINUATION_MASK = 0xf;
    323 
    324     /**
    325      * Constant to return from {@link #onStartCommand}: compatibility
    326      * version of {@link #START_STICKY} that does not guarantee that
    327      * {@link #onStartCommand} will be called again after being killed.
    328      */
    329     public static final int START_STICKY_COMPATIBILITY = 0;
    330 
    331     /**
    332      * Constant to return from {@link #onStartCommand}: if this service's
    333      * process is killed while it is started (after returning from
    334      * {@link #onStartCommand}), then leave it in the started state but
    335      * don't retain this delivered intent.  Later the system will try to
    336      * re-create the service.  Because it is in the started state, it will
    337      * guarantee to call {@link #onStartCommand} after creating the new
    338      * service instance; if there are not any pending start commands to be
    339      * delivered to the service, it will be called with a null intent
    340      * object, so you must take care to check for this.
    341      *
    342      * <p>This mode makes sense for things that will be explicitly started
    343      * and stopped to run for arbitrary periods of time, such as a service
    344      * performing background music playback.
    345      */
    346     public static final int START_STICKY = 1;
    347 
    348     /**
    349      * Constant to return from {@link #onStartCommand}: if this service's
    350      * process is killed while it is started (after returning from
    351      * {@link #onStartCommand}), and there are no new start intents to
    352      * deliver to it, then take the service out of the started state and
    353      * don't recreate until a future explicit call to
    354      * {@link Context#startService Context.startService(Intent)}.  The
    355      * service will not receive a {@link #onStartCommand(Intent, int, int)}
    356      * call with a null Intent because it will not be re-started if there
    357      * are no pending Intents to deliver.
    358      *
    359      * <p>This mode makes sense for things that want to do some work as a
    360      * result of being started, but can be stopped when under memory pressure
    361      * and will explicit start themselves again later to do more work.  An
    362      * example of such a service would be one that polls for data from
    363      * a server: it could schedule an alarm to poll every N minutes by having
    364      * the alarm start its service.  When its {@link #onStartCommand} is
    365      * called from the alarm, it schedules a new alarm for N minutes later,
    366      * and spawns a thread to do its networking.  If its process is killed
    367      * while doing that check, the service will not be restarted until the
    368      * alarm goes off.
    369      */
    370     public static final int START_NOT_STICKY = 2;
    371 
    372     /**
    373      * Constant to return from {@link #onStartCommand}: if this service's
    374      * process is killed while it is started (after returning from
    375      * {@link #onStartCommand}), then it will be scheduled for a restart
    376      * and the last delivered Intent re-delivered to it again via
    377      * {@link #onStartCommand}.  This Intent will remain scheduled for
    378      * redelivery until the service calls {@link #stopSelf(int)} with the
    379      * start ID provided to {@link #onStartCommand}.  The
    380      * service will not receive a {@link #onStartCommand(Intent, int, int)}
    381      * call with a null Intent because it will will only be re-started if
    382      * it is not finished processing all Intents sent to it (and any such
    383      * pending events will be delivered at the point of restart).
    384      */
    385     public static final int START_REDELIVER_INTENT = 3;
    386 
    387     /**
    388      * Special constant for reporting that we are done processing
    389      * {@link #onTaskRemoved(Intent)}.
    390      * @hide
    391      */
    392     public static final int START_TASK_REMOVED_COMPLETE = 1000;
    393 
    394     /**
    395      * This flag is set in {@link #onStartCommand} if the Intent is a
    396      * re-delivery of a previously delivered intent, because the service
    397      * had previously returned {@link #START_REDELIVER_INTENT} but had been
    398      * killed before calling {@link #stopSelf(int)} for that Intent.
    399      */
    400     public static final int START_FLAG_REDELIVERY = 0x0001;
    401 
    402     /**
    403      * This flag is set in {@link #onStartCommand} if the Intent is a
    404      * a retry because the original attempt never got to or returned from
    405      * {@link #onStartCommand(Intent, int, int)}.
    406      */
    407     public static final int START_FLAG_RETRY = 0x0002;
    408 
    409     /**
    410      * Called by the system every time a client explicitly starts the service by calling
    411      * {@link android.content.Context#startService}, providing the arguments it supplied and a
    412      * unique integer token representing the start request.  Do not call this method directly.
    413      *
    414      * <p>For backwards compatibility, the default implementation calls
    415      * {@link #onStart} and returns either {@link #START_STICKY}
    416      * or {@link #START_STICKY_COMPATIBILITY}.
    417      *
    418      * <p>If you need your application to run on platform versions prior to API
    419      * level 5, you can use the following model to handle the older {@link #onStart}
    420      * callback in that case.  The <code>handleCommand</code> method is implemented by
    421      * you as appropriate:
    422      *
    423      * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/ForegroundService.java
    424      *   start_compatibility}
    425      *
    426      * <p class="caution">Note that the system calls this on your
    427      * service's main thread.  A service's main thread is the same
    428      * thread where UI operations take place for Activities running in the
    429      * same process.  You should always avoid stalling the main
    430      * thread's event loop.  When doing long-running operations,
    431      * network calls, or heavy disk I/O, you should kick off a new
    432      * thread, or use {@link android.os.AsyncTask}.</p>
    433      *
    434      * @param intent The Intent supplied to {@link android.content.Context#startService},
    435      * as given.  This may be null if the service is being restarted after
    436      * its process has gone away, and it had previously returned anything
    437      * except {@link #START_STICKY_COMPATIBILITY}.
    438      * @param flags Additional data about this start request.  Currently either
    439      * 0, {@link #START_FLAG_REDELIVERY}, or {@link #START_FLAG_RETRY}.
    440      * @param startId A unique integer representing this specific request to
    441      * start.  Use with {@link #stopSelfResult(int)}.
    442      *
    443      * @return The return value indicates what semantics the system should
    444      * use for the service's current started state.  It may be one of the
    445      * constants associated with the {@link #START_CONTINUATION_MASK} bits.
    446      *
    447      * @see #stopSelfResult(int)
    448      */
    449     public int onStartCommand(Intent intent, int flags, int startId) {
    450         onStart(intent, startId);
    451         return mStartCompatibility ? START_STICKY_COMPATIBILITY : START_STICKY;
    452     }
    453 
    454     /**
    455      * Called by the system to notify a Service that it is no longer used and is being removed.  The
    456      * service should clean up any resources it holds (threads, registered
    457      * receivers, etc) at this point.  Upon return, there will be no more calls
    458      * in to this Service object and it is effectively dead.  Do not call this method directly.
    459      */
    460     public void onDestroy() {
    461     }
    462 
    463     public void onConfigurationChanged(Configuration newConfig) {
    464     }
    465 
    466     public void onLowMemory() {
    467     }
    468 
    469     public void onTrimMemory(int level) {
    470     }
    471 
    472     /**
    473      * Return the communication channel to the service.  May return null if
    474      * clients can not bind to the service.  The returned
    475      * {@link android.os.IBinder} is usually for a complex interface
    476      * that has been <a href="{@docRoot}guide/components/aidl.html">described using
    477      * aidl</a>.
    478      *
    479      * <p><em>Note that unlike other application components, calls on to the
    480      * IBinder interface returned here may not happen on the main thread
    481      * of the process</em>.  More information about the main thread can be found in
    482      * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">Processes and
    483      * Threads</a>.</p>
    484      *
    485      * @param intent The Intent that was used to bind to this service,
    486      * as given to {@link android.content.Context#bindService
    487      * Context.bindService}.  Note that any extras that were included with
    488      * the Intent at that point will <em>not</em> be seen here.
    489      *
    490      * @return Return an IBinder through which clients can call on to the
    491      *         service.
    492      */
    493     public abstract IBinder onBind(Intent intent);
    494 
    495     /**
    496      * Called when all clients have disconnected from a particular interface
    497      * published by the service.  The default implementation does nothing and
    498      * returns false.
    499      *
    500      * @param intent The Intent that was used to bind to this service,
    501      * as given to {@link android.content.Context#bindService
    502      * Context.bindService}.  Note that any extras that were included with
    503      * the Intent at that point will <em>not</em> be seen here.
    504      *
    505      * @return Return true if you would like to have the service's
    506      * {@link #onRebind} method later called when new clients bind to it.
    507      */
    508     public boolean onUnbind(Intent intent) {
    509         return false;
    510     }
    511 
    512     /**
    513      * Called when new clients have connected to the service, after it had
    514      * previously been notified that all had disconnected in its
    515      * {@link #onUnbind}.  This will only be called if the implementation
    516      * of {@link #onUnbind} was overridden to return true.
    517      *
    518      * @param intent The Intent that was used to bind to this service,
    519      * as given to {@link android.content.Context#bindService
    520      * Context.bindService}.  Note that any extras that were included with
    521      * the Intent at that point will <em>not</em> be seen here.
    522      */
    523     public void onRebind(Intent intent) {
    524     }
    525 
    526     /**
    527      * This is called if the service is currently running and the user has
    528      * removed a task that comes from the service's application.  If you have
    529      * set {@link android.content.pm.ServiceInfo#FLAG_STOP_WITH_TASK ServiceInfo.FLAG_STOP_WITH_TASK}
    530      * then you will not receive this callback; instead, the service will simply
    531      * be stopped.
    532      *
    533      * @param rootIntent The original root Intent that was used to launch
    534      * the task that is being removed.
    535      */
    536     public void onTaskRemoved(Intent rootIntent) {
    537     }
    538 
    539     /**
    540      * Stop the service, if it was previously started.  This is the same as
    541      * calling {@link android.content.Context#stopService} for this particular service.
    542      *
    543      * @see #stopSelfResult(int)
    544      */
    545     public final void stopSelf() {
    546         stopSelf(-1);
    547     }
    548 
    549     /**
    550      * Old version of {@link #stopSelfResult} that doesn't return a result.
    551      *
    552      * @see #stopSelfResult
    553      */
    554     public final void stopSelf(int startId) {
    555         if (mActivityManager == null) {
    556             return;
    557         }
    558         try {
    559             mActivityManager.stopServiceToken(
    560                     new ComponentName(this, mClassName), mToken, startId);
    561         } catch (RemoteException ex) {
    562         }
    563     }
    564 
    565     /**
    566      * Stop the service if the most recent time it was started was
    567      * <var>startId</var>.  This is the same as calling {@link
    568      * android.content.Context#stopService} for this particular service but allows you to
    569      * safely avoid stopping if there is a start request from a client that you
    570      * haven't yet seen in {@link #onStart}.
    571      *
    572      * <p><em>Be careful about ordering of your calls to this function.</em>.
    573      * If you call this function with the most-recently received ID before
    574      * you have called it for previously received IDs, the service will be
    575      * immediately stopped anyway.  If you may end up processing IDs out
    576      * of order (such as by dispatching them on separate threads), then you
    577      * are responsible for stopping them in the same order you received them.</p>
    578      *
    579      * @param startId The most recent start identifier received in {@link
    580      *                #onStart}.
    581      * @return Returns true if the startId matches the last start request
    582      * and the service will be stopped, else false.
    583      *
    584      * @see #stopSelf()
    585      */
    586     public final boolean stopSelfResult(int startId) {
    587         if (mActivityManager == null) {
    588             return false;
    589         }
    590         try {
    591             return mActivityManager.stopServiceToken(
    592                     new ComponentName(this, mClassName), mToken, startId);
    593         } catch (RemoteException ex) {
    594         }
    595         return false;
    596     }
    597 
    598     /**
    599      * @deprecated This is a now a no-op, use
    600      * {@link #startForeground(int, Notification)} instead.  This method
    601      * has been turned into a no-op rather than simply being deprecated
    602      * because analysis of numerous poorly behaving devices has shown that
    603      * increasingly often the trouble is being caused in part by applications
    604      * that are abusing it.  Thus, given a choice between introducing
    605      * problems in existing applications using this API (by allowing them to
    606      * be killed when they would like to avoid it), vs allowing the performance
    607      * of the entire system to be decreased, this method was deemed less
    608      * important.
    609      *
    610      * @hide
    611      */
    612     @Deprecated
    613     public final void setForeground(boolean isForeground) {
    614         Log.w(TAG, "setForeground: ignoring old API call on " + getClass().getName());
    615     }
    616 
    617     /**
    618      * Make this service run in the foreground, supplying the ongoing
    619      * notification to be shown to the user while in this state.
    620      * By default services are background, meaning that if the system needs to
    621      * kill them to reclaim more memory (such as to display a large page in a
    622      * web browser), they can be killed without too much harm.  You can set this
    623      * flag if killing your service would be disruptive to the user, such as
    624      * if your service is performing background music playback, so the user
    625      * would notice if their music stopped playing.
    626      *
    627      * <p>If you need your application to run on platform versions prior to API
    628      * level 5, you can use the following model to call the the older setForeground()
    629      * or this modern method as appropriate:
    630      *
    631      * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/ForegroundService.java
    632      *   foreground_compatibility}
    633      *
    634      * @param id The identifier for this notification as per
    635      * {@link NotificationManager#notify(int, Notification)
    636      * NotificationManager.notify(int, Notification)}; must not be 0.
    637      * @param notification The Notification to be displayed.
    638      *
    639      * @see #stopForeground(boolean)
    640      */
    641     public final void startForeground(int id, Notification notification) {
    642         try {
    643             mActivityManager.setServiceForeground(
    644                     new ComponentName(this, mClassName), mToken, id,
    645                     notification, true);
    646         } catch (RemoteException ex) {
    647         }
    648     }
    649 
    650     /**
    651      * Remove this service from foreground state, allowing it to be killed if
    652      * more memory is needed.
    653      * @param removeNotification If true, the notification previously provided
    654      * to {@link #startForeground} will be removed.  Otherwise it will remain
    655      * until a later call removes it (or the service is destroyed).
    656      * @see #startForeground(int, Notification)
    657      */
    658     public final void stopForeground(boolean removeNotification) {
    659         try {
    660             mActivityManager.setServiceForeground(
    661                     new ComponentName(this, mClassName), mToken, 0, null,
    662                     removeNotification);
    663         } catch (RemoteException ex) {
    664         }
    665     }
    666 
    667     /**
    668      * Print the Service's state into the given stream.  This gets invoked if
    669      * you run "adb shell dumpsys activity service &lt;yourservicename&gt;"
    670      * (note that for this command to work, the service must be running, and
    671      * you must specify a fully-qualified service name).
    672      * This is distinct from "dumpsys &lt;servicename&gt;", which only works for
    673      * named system services and which invokes the {@link IBinder#dump} method
    674      * on the {@link IBinder} interface registered with ServiceManager.
    675      *
    676      * @param fd The raw file descriptor that the dump is being sent to.
    677      * @param writer The PrintWriter to which you should dump your state.  This will be
    678      * closed for you after you return.
    679      * @param args additional arguments to the dump request.
    680      */
    681     protected void dump(FileDescriptor fd, PrintWriter writer, String[] args) {
    682         writer.println("nothing to dump");
    683     }
    684 
    685     // ------------------ Internal API ------------------
    686 
    687     /**
    688      * @hide
    689      */
    690     public final void attach(
    691             Context context,
    692             ActivityThread thread, String className, IBinder token,
    693             Application application, Object activityManager) {
    694         attachBaseContext(context);
    695         mThread = thread;           // NOTE:  unused - remove?
    696         mClassName = className;
    697         mToken = token;
    698         mApplication = application;
    699         mActivityManager = (IActivityManager)activityManager;
    700         mStartCompatibility = getApplicationInfo().targetSdkVersion
    701                 < Build.VERSION_CODES.ECLAIR;
    702     }
    703 
    704     final String getClassName() {
    705         return mClassName;
    706     }
    707 
    708     // set by the thread after the constructor and before onCreate(Bundle icicle) is called.
    709     private ActivityThread mThread = null;
    710     private String mClassName = null;
    711     private IBinder mToken = null;
    712     private Application mApplication = null;
    713     private IActivityManager mActivityManager = null;
    714     private boolean mStartCompatibility = false;
    715 }
    716