19066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/* 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Copyright (C) 2006 The Android Open Source Project 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you may not use this file except in compliance with the License. 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * You may obtain a copy of the License at 79066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 99066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * See the License for the specific language governing permissions and 149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * limitations under the License. 159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpackage android.app; 189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 19c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackbornimport android.content.ComponentCallbacks2; 209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.content.ComponentName; 219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.content.Intent; 229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.content.ContextWrapper; 239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.content.Context; 249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.content.res.Configuration; 25f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackbornimport android.os.Build; 269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.os.RemoteException; 279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.os.IBinder; 28d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackbornimport android.util.Log; 299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport java.io.FileDescriptor; 319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport java.io.PrintWriter; 329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/** 34ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * A Service is an application component representing either an application's desire 35ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * to perform a longer-running operation while not interacting with the user 36ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * or to supply functionality for other applications to use. Each service 379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * class must have a corresponding 389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.styleable#AndroidManifestService <service>} 399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * declaration in its package's <code>AndroidManifest.xml</code>. Services 409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * can be started with 419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#startService Context.startService()} and 429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#bindService Context.bindService()}. 439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that services, like other application objects, run in the main 459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * thread of their hosting process. This means that, if your service is going 469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to do any CPU intensive (such as MP3 playback) or blocking (such as 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * networking) operations, it should spawn its own thread in which to do that 489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * work. More information on this can be found in 497aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">Processes and 507aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * Threads</a>. The {@link IntentService} class is available 51ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * as a standard implementation of Service that has its own thread where it 52ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * schedules its work to be done.</p> 539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Topics covered here: 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <ol> 56ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <li><a href="#WhatIsAService">What is a Service?</a> 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><a href="#ServiceLifecycle">Service Lifecycle</a> 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><a href="#Permissions">Permissions</a> 599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><a href="#ProcessLifecycle">Process Lifecycle</a> 6075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <li><a href="#LocalServiceSample">Local Service Sample</a> 6175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <li><a href="#RemoteMessengerServiceSample">Remote Messenger Service Sample</a> 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * </ol> 63b54e7a3d9f60ac605f404f9eb3c5e92ca51bbd23Joe Fernandez * 64b54e7a3d9f60ac605f404f9eb3c5e92ca51bbd23Joe Fernandez * <div class="special reference"> 65b54e7a3d9f60ac605f404f9eb3c5e92ca51bbd23Joe Fernandez * <h3>Developer Guides</h3> 66b54e7a3d9f60ac605f404f9eb3c5e92ca51bbd23Joe Fernandez * <p>For a detailed discussion about how to create services, read the 67b54e7a3d9f60ac605f404f9eb3c5e92ca51bbd23Joe Fernandez * <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer guide.</p> 68b54e7a3d9f60ac605f404f9eb3c5e92ca51bbd23Joe Fernandez * </div> 69b54e7a3d9f60ac605f404f9eb3c5e92ca51bbd23Joe Fernandez * 70ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <a name="WhatIsAService"></a> 71ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <h3>What is a Service?</h3> 72ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * 73ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <p>Most confusion about the Service class actually revolves around what 74ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * it is <em>not</em>:</p> 75ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * 76ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <ul> 77ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <li> A Service is <b>not</b> a separate process. The Service object itself 78ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * does not imply it is running in its own process; unless otherwise specified, 79ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * it runs in the same process as the application it is part of. 80ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <li> A Service is <b>not</b> a thread. It is not a means itself to do work off 81ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * of the main thread (to avoid Application Not Responding errors). 82ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * </ul> 83ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * 84ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <p>Thus a Service itself is actually very simple, providing two main features:</p> 85ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * 86ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <ul> 87ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <li>A facility for the application to tell the system <em>about</em> 88ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * something it wants to be doing in the background (even when the user is not 89ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * directly interacting with the application). This corresponds to calls to 90ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * {@link android.content.Context#startService Context.startService()}, which 91ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * ask the system to schedule work for the service, to be run until the service 92ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * or someone else explicitly stop it. 93ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <li>A facility for an application to expose some of its functionality to 94ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * other applications. This corresponds to calls to 95ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * {@link android.content.Context#bindService Context.bindService()}, which 96ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * allows a long-standing connection to be made to the service in order to 97ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * interact with it. 98ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * </ul> 99ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * 100ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <p>When a Service component is actually created, for either of these reasons, 101ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * all that the system actually does is instantiate the component 102ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * and call its {@link #onCreate} and any other appropriate callbacks on the 103ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * main thread. It is up to the Service to implement these with the appropriate 104ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * behavior, such as creating a secondary thread in which it does its work.</p> 105ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * 106ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * <p>Note that because Service itself is so simple, you can make your 107ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * interaction with it as simple or complicated as you want: from treating it 108ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * as a local Java object that you make direct method calls on (as illustrated 109ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * by <a href="#LocalServiceSample">Local Service Sample</a>), to providing 110ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * a full remoteable interface using AIDL.</p> 111ee3bcc4c6462d1402e48e9d260e16d038d8fe291Dianne Hackborn * 1129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a name="ServiceLifecycle"></a> 1139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <h3>Service Lifecycle</h3> 1149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>There are two reasons that a service can be run by the system. If someone 1169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * calls {@link android.content.Context#startService Context.startService()} then the system will 1179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * retrieve the service (creating it and calling its {@link #onCreate} method 118fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * if needed) and then call its {@link #onStartCommand} method with the 1199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * arguments supplied by the client. The service will at this point continue 1209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * running until {@link android.content.Context#stopService Context.stopService()} or 1219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #stopSelf()} is called. Note that multiple calls to 1229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.startService() do not nest (though they do result in multiple corresponding 123fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * calls to onStartCommand()), so no matter how many times it is started a service 124fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * will be stopped once Context.stopService() or stopSelf() is called; however, 125fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * services can use their {@link #stopSelf(int)} method to ensure the service is 126fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * not stopped until started intents have been processed. 127fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * 128fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * <p>For started services, there are two additional major modes of operation 129fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * they can decide to run in, depending on the value they return from 130fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * onStartCommand(): {@link #START_STICKY} is used for services that are 131fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * explicitly started and stopped as needed, while {@link #START_NOT_STICKY} 132fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * or {@link #START_REDELIVER_INTENT} are used for services that should only 133fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * remain running while processing any commands sent to them. See the linked 134fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * documentation for more detail on the semantics. 1359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Clients can also use {@link android.content.Context#bindService Context.bindService()} to 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * obtain a persistent connection to a service. This likewise creates the 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service if it is not already running (calling {@link #onCreate} while 139fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * doing so), but does not call onStartCommand(). The client will receive the 1409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.os.IBinder} object that the service returns from its 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onBind} method, allowing the client to then make calls back 1429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to the service. The service will remain running as long as the connection 1439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * is established (whether or not the client retains a reference on the 1449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service's IBinder). Usually the IBinder returned is for a complex 14540eee61e25fb887f5267686f8a0a7c5bd9f95769Scott Main * interface that has been <a href="{@docRoot}guide/components/aidl.html">written 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in aidl</a>. 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>A service can be both started and have connections bound to it. In such 1499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a case, the system will keep the service running as long as either it is 1509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * started <em>or</em> there are one or more connections to it with the 1519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE} 1529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * flag. Once neither 1539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * of these situations hold, the service's {@link #onDestroy} method is called 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * and the service is effectively terminated. All cleanup (stopping threads, 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * unregistering receivers) should be complete upon returning from onDestroy(). 1569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a name="Permissions"></a> 1589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <h3>Permissions</h3> 1599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Global access to a service can be enforced when it is declared in its 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * manifest's {@link android.R.styleable#AndroidManifestService <service>} 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * tag. By doing so, other applications will need to declare a corresponding 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>} 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * element in their own manifest to be able to start, stop, or bind to 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the service. 16621c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * 16721c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * <p>As of {@link android.os.Build.VERSION_CODES#GINGERBREAD}, when using 16821c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * {@link Context#startService(Intent) Context.startService(Intent)}, you can 16921c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * also set {@link Intent#FLAG_GRANT_READ_URI_PERMISSION 17021c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION 17121c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * Intent.FLAG_GRANT_WRITE_URI_PERMISSION} on the Intent. This will grant the 17221c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * Service temporary access to the specific URIs in the Intent. Access will 17321c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * remain until the Service has called {@link #stopSelf(int)} for that start 17421c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * command or a later one, or until the Service has been completely stopped. 17521c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * This works for granting access to the other apps that have not requested 17621c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * the permission protecting the Service, or even when the Service is not 17721c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * exported at all. 17821c241e061de29a538008ca42df9c878184bcfb8Dianne Hackborn * 1799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>In addition, a service can protect individual IPC calls into it with 1809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * permissions, by calling the 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #checkCallingPermission} 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * method before executing the implementation of that call. 1839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>See the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> 1859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * document for more information on permissions and security in general. 1869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a name="ProcessLifecycle"></a> 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <h3>Process Lifecycle</h3> 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>The Android system will attempt to keep the process hosting a service 1919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * around as long as the service has been started or has clients bound to it. 1929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * When running low on memory and needing to kill existing processes, the 1939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * priority of a process hosting the service will be the higher of the 1949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * following possibilities: 1959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <ul> 1979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If the service is currently executing code in its 198fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * {@link #onCreate onCreate()}, {@link #onStartCommand onStartCommand()}, 1999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or {@link #onDestroy onDestroy()} methods, then the hosting process will 2009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * be a foreground process to ensure this code can execute without 2019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * being killed. 2029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If the service has been started, then its hosting process is considered 2039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to be less important than any processes that are currently visible to the 2049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * user on-screen, but more important than any process not visible. Because 2059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * only a few processes are generally visible to the user, this means that 2069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the service should not be killed except in extreme low memory conditions. 2079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If there are clients bound to the service, then the service's hosting 2089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * process is never less important than the most important client. That is, 2099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if one of its clients is visible to the user, then the service itself is 2109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * considered to be visible. 211fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * <li><p>A started service can use the {@link #startForeground(int, Notification)} 212fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * API to put the service in a foreground state, where the system considers 213fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * it to be something the user is actively aware of and thus not a candidate 214fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * for killing when low on memory. (It is still theoretically possible for 215fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * the service to be killed under extreme memory pressure from the current 216fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * foreground application, but in practice this should not be a concern.) 2179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * </ul> 2189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note this means that most of the time your service is running, it may 2209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * be killed by the system if it is under heavy memory pressure. If this 2219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * happens, the system will later try to restart the service. An important 222fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * consequence of this is that if you implement {@link #onStartCommand onStartCommand()} 2239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to schedule work to be done asynchronously or in another thread, then you 22429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * may want to use {@link #START_FLAG_REDELIVERY} to have the system 22529e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * re-deliver an Intent for you so that it does not get lost if your service 22629e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * is killed while processing it. 2279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Other application components running in the same process as the service 2299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * (such as an {@link android.app.Activity}) can, of course, increase the 2309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * importance of the overall 2319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * process beyond just the importance of the service itself. 23275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 23375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <a name="LocalServiceSample"></a> 23475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <h3>Local Service Sample</h3> 23575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 23675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>One of the most common uses of a Service is as a secondary component 23775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * running alongside other parts of an application, in the same process as 23875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * the rest of the components. All components of an .apk run in the same 23975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * process unless explicitly stated otherwise, so this is a typical situation. 24075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 24175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>When used in this way, by assuming the 24275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * components are in the same process, you can greatly simplify the interaction 24375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * between them: clients of the service can simply cast the IBinder they 24475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * receive from it to a concrete class published by the service. 24575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 24675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>An example of this use of a Service is shown here. First is the Service 24775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * itself, publishing a custom class when bound: 24875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 24975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalService.java 25075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * service} 25175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 25275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>With that done, one can now write client code that directly accesses the 25375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * running service, such as: 25475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 25575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.java 25675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * bind} 25775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 25875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <a name="RemoteMessengerServiceSample"></a> 25975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <h3>Remote Messenger Service Sample</h3> 26075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 26175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>If you need to be able to write a Service that can perform complicated 26275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * communication with clients in remote processes (beyond simply the use of 26375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@link Context#startService(Intent) Context.startService} to send 26475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * commands to it), then you can use the {@link android.os.Messenger} class 26575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * instead of writing full AIDL files. 26675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 26775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>An example of a Service that uses Messenger as its client interface 26875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * is shown here. First is the Service itself, publishing a Messenger to 26975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * an internal Handler when bound: 27075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 27175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.java 27275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * service} 27375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 27475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>If we want to make this service run in a remote process (instead of the 27575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * standard one for its .apk), we can use <code>android:process</code> in its 27675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * manifest tag to specify one: 27775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 27875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/AndroidManifest.xml remote_service_declaration} 27975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 28075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>Note that the name "remote" chosen here is arbitrary, and you can use 28175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * other names if you want additional processes. The ':' prefix appends the 28275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * name to your package's standard process name. 28375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 28475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>With that done, clients can now bind to the service and send messages 28575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * to it. Note that this allows clients to register with it to receive 28675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * messages back as well: 28775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 28875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.java 28975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * bind} 2909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 291c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackbornpublic abstract class Service extends ContextWrapper implements ComponentCallbacks2 { 2929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private static final String TAG = "Service"; 2939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Service() { 2959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project super(null); 2969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** Return the application that owns this service. */ 2999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final Application getApplication() { 3009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mApplication; 3019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system when the service is first created. Do not call this method directly. 3059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onCreate() { 3079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 310f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @deprecated Implement {@link #onStartCommand(Intent, int, int)} instead. 311f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 312f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn @Deprecated 313f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public void onStart(Intent intent, int startId) { 314f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn } 315f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 316f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 317f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Bits returned by {@link #onStartCommand} describing how to continue 318f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * the service if it is killed. May be {@link #START_STICKY}, 319f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #START_NOT_STICKY}, {@link #START_REDELIVER_INTENT}, 320f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * or {@link #START_STICKY_COMPATIBILITY}. 321f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 322f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_CONTINUATION_MASK = 0xf; 323f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 324f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 325f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: compatibility 326f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * version of {@link #START_STICKY} that does not guarantee that 327f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand} will be called again after being killed. 328f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 329f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_STICKY_COMPATIBILITY = 0; 330f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 331f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 332f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 333f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 334f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), then leave it in the started state but 335f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * don't retain this delivered intent. Later the system will try to 336fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * re-create the service. Because it is in the started state, it will 337fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * guarantee to call {@link #onStartCommand} after creating the new 338fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * service instance; if there are not any pending start commands to be 339fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * delivered to the service, it will be called with a null intent 340fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * object, so you must take care to check for this. 341f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 342f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>This mode makes sense for things that will be explicitly started 343f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and stopped to run for arbitrary periods of time, such as a service 344f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * performing background music playback. 345f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 346f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_STICKY = 1; 347f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 348f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 349f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 350f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 351f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), and there are no new start intents to 352f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * deliver to it, then take the service out of the started state and 353f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * don't recreate until a future explicit call to 35429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * {@link Context#startService Context.startService(Intent)}. The 35529e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * service will not receive a {@link #onStartCommand(Intent, int, int)} 35629e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * call with a null Intent because it will not be re-started if there 35729e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * are no pending Intents to deliver. 358f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 359f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>This mode makes sense for things that want to do some work as a 360f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * result of being started, but can be stopped when under memory pressure 361f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and will explicit start themselves again later to do more work. An 362f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * example of such a service would be one that polls for data from 363f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * a server: it could schedule an alarm to poll every N minutes by having 364f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * the alarm start its service. When its {@link #onStartCommand} is 365f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * called from the alarm, it schedules a new alarm for N minutes later, 366f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and spawns a thread to do its networking. If its process is killed 367f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * while doing that check, the service will not be restarted until the 368f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * alarm goes off. 369f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 370f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_NOT_STICKY = 2; 371f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 372f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 373f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 374f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 375f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), then it will be scheduled for a restart 376f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and the last delivered Intent re-delivered to it again via 377f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}. This Intent will remain scheduled for 378f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * redelivery until the service calls {@link #stopSelf(int)} with the 37929e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * start ID provided to {@link #onStartCommand}. The 38029e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * service will not receive a {@link #onStartCommand(Intent, int, int)} 38129e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * call with a null Intent because it will will only be re-started if 38229e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * it is not finished processing all Intents sent to it (and any such 38329e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * pending events will be delivered at the point of restart). 384f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 385f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_REDELIVER_INTENT = 3; 386f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 387f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 3880c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * Special constant for reporting that we are done processing 3890c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * {@link #onTaskRemoved(Intent)}. 3900c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * @hide 3910c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn */ 3920c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn public static final int START_TASK_REMOVED_COMPLETE = 1000; 3930c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn 3940c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn /** 395f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * This flag is set in {@link #onStartCommand} if the Intent is a 396f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * re-delivery of a previously delivered intent, because the service 397f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * had previously returned {@link #START_REDELIVER_INTENT} but had been 398f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * killed before calling {@link #stopSelf(int)} for that Intent. 399f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 400f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_FLAG_REDELIVERY = 0x0001; 401f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 402f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 403f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * This flag is set in {@link #onStartCommand} if the Intent is a 404f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * a retry because the original attempt never got to or returned from 405f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand(Intent, int, int)}. 406f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 407f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_FLAG_RETRY = 0x0002; 408f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 409f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 4109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system every time a client explicitly starts the service by calling 4119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#startService}, providing the arguments it supplied and a 4129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * unique integer token representing the start request. Do not call this method directly. 413f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 414f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>For backwards compatibility, the default implementation calls 415f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStart} and returns either {@link #START_STICKY} 416f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * or {@link #START_STICKY_COMPATIBILITY}. 417f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 4180766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * <p>If you need your application to run on platform versions prior to API 4190766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * level 5, you can use the following model to handle the older {@link #onStart} 4200766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * callback in that case. The <code>handleCommand</code> method is implemented by 4210766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * you as appropriate: 4220766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * 423ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/ForegroundService.java 424ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * start_compatibility} 4250166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * 4260166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * <p class="caution">Note that the system calls this on your 4270166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * service's main thread. A service's main thread is the same 428ee34a49ffc92590cb59f3e17a3df136b67701529Brad Fitzpatrick * thread where UI operations take place for Activities running in the 4290166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * same process. You should always avoid stalling the main 4300166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * thread's event loop. When doing long-running operations, 4310166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * network calls, or heavy disk I/O, you should kick off a new 4320166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * thread, or use {@link android.os.AsyncTask}.</p> 4330166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * 4349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent supplied to {@link android.content.Context#startService}, 435f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * as given. This may be null if the service is being restarted after 436f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * its process has gone away, and it had previously returned anything 437f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * except {@link #START_STICKY_COMPATIBILITY}. 438f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @param flags Additional data about this start request. Currently either 439f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 0, {@link #START_FLAG_REDELIVERY}, or {@link #START_FLAG_RETRY}. 4409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param startId A unique integer representing this specific request to 441f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * start. Use with {@link #stopSelfResult(int)}. 442f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 443f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @return The return value indicates what semantics the system should 444f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * use for the service's current started state. It may be one of the 445f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * constants associated with the {@link #START_CONTINUATION_MASK} bits. 4469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult(int) 4489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 449f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public int onStartCommand(Intent intent, int flags, int startId) { 450f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn onStart(intent, startId); 451f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn return mStartCompatibility ? START_STICKY_COMPATIBILITY : START_STICKY; 4529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 453f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 4549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system to notify a Service that it is no longer used and is being removed. The 456f76a50ce8fdc6aea22cabc77b2977a1a15a79630Ken Wakasa * service should clean up any resources it holds (threads, registered 4579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * receivers, etc) at this point. Upon return, there will be no more calls 4589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in to this Service object and it is effectively dead. Do not call this method directly. 4599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onDestroy() { 4619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onConfigurationChanged(Configuration newConfig) { 4649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onLowMemory() { 4679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 468c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn 469c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn public void onTrimMemory(int level) { 470c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn } 471c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn 4729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Return the communication channel to the service. May return null if 4749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * clients can not bind to the service. The returned 4759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.os.IBinder} is usually for a complex interface 47640eee61e25fb887f5267686f8a0a7c5bd9f95769Scott Main * that has been <a href="{@docRoot}guide/components/aidl.html">described using 4779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * aidl</a>. 4789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p><em>Note that unlike other application components, calls on to the 4809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * IBinder interface returned here may not happen on the main thread 4817aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * of the process</em>. More information about the main thread can be found in 4827aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">Processes and 4837aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * Threads</a>.</p> 4849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 4869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 4879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 4889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 4899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Return an IBinder through which clients can call on to the 4919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service. 4929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public abstract IBinder onBind(Intent intent); 4949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when all clients have disconnected from a particular interface 4979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * published by the service. The default implementation does nothing and 4989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returns false. 4999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 5019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 5029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 5039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 5049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Return true if you would like to have the service's 5069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onRebind} method later called when new clients bind to it. 5079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean onUnbind(Intent intent) { 5099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 5109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 5139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when new clients have connected to the service, after it had 5149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * previously been notified that all had disconnected in its 5159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onUnbind}. This will only be called if the implementation 5169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * of {@link #onUnbind} was overridden to return true. 5179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 5199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 5209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 5219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 5229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onRebind(Intent intent) { 5249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 5270c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * This is called if the service is currently running and the user has 5280c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * removed a task that comes from the service's application. If you have 5290c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * set {@link android.content.pm.ServiceInfo#FLAG_STOP_WITH_TASK ServiceInfo.FLAG_STOP_WITH_TASK} 5300c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * then you will not receive this callback; instead, the service will simply 5310c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * be stopped. 5320c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * 5330c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * @param rootIntent The original root Intent that was used to launch 5340c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * the task that is being removed. 5350c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn */ 5360c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn public void onTaskRemoved(Intent rootIntent) { 5370c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn } 5380c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn 5390c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn /** 5409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Stop the service, if it was previously started. This is the same as 5419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * calling {@link android.content.Context#stopService} for this particular service. 5429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult(int) 5449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void stopSelf() { 5469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project stopSelf(-1); 5479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 5509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Old version of {@link #stopSelfResult} that doesn't return a result. 5519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult 5539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void stopSelf(int startId) { 5559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (mActivityManager == null) { 5569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return; 5579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 5599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager.stopServiceToken( 5609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project new ComponentName(this, mClassName), mToken, startId); 5619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 5629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 566105925376f8d0f6b318c9938c7b83ef7fef094daThe Android Open Source Project * Stop the service if the most recent time it was started was 5679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <var>startId</var>. This is the same as calling {@link 5689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * android.content.Context#stopService} for this particular service but allows you to 5699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * safely avoid stopping if there is a start request from a client that you 570105925376f8d0f6b318c9938c7b83ef7fef094daThe Android Open Source Project * haven't yet seen in {@link #onStart}. 5719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 57229e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * <p><em>Be careful about ordering of your calls to this function.</em>. 57329e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * If you call this function with the most-recently received ID before 57429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * you have called it for previously received IDs, the service will be 57529e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * immediately stopped anyway. If you may end up processing IDs out 57629e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * of order (such as by dispatching them on separate threads), then you 57729e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * are responsible for stopping them in the same order you received them.</p> 57829e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * 5799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param startId The most recent start identifier received in {@link 5809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * #onStart}. 5819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns true if the startId matches the last start request 5829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * and the service will be stopped, else false. 5839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelf() 5859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final boolean stopSelfResult(int startId) { 5879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (mActivityManager == null) { 5889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 5899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 5919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mActivityManager.stopServiceToken( 5929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project new ComponentName(this, mClassName), mToken, startId); 5939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 5949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 5969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 599d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @deprecated This is a now a no-op, use 60029e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * {@link #startForeground(int, Notification)} instead. This method 60129e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * has been turned into a no-op rather than simply being deprecated 60229e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * because analysis of numerous poorly behaving devices has shown that 60329e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * increasingly often the trouble is being caused in part by applications 60429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * that are abusing it. Thus, given a choice between introducing 60529e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * problems in existing applications using this API (by allowing them to 60629e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * be killed when they would like to avoid it), vs allowing the performance 60729e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * of the entire system to be decreased, this method was deemed less 60829e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * important. 6094f3867e3ce92101224ad79b8f2ff446bb4f99108Dianne Hackborn * 6104f3867e3ce92101224ad79b8f2ff446bb4f99108Dianne Hackborn * @hide 611d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn */ 612d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn @Deprecated 613d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void setForeground(boolean isForeground) { 614d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn Log.w(TAG, "setForeground: ignoring old API call on " + getClass().getName()); 615d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } 616d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn 617d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn /** 618d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * Make this service run in the foreground, supplying the ongoing 619d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * notification to be shown to the user while in this state. 6209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * By default services are background, meaning that if the system needs to 6219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * kill them to reclaim more memory (such as to display a large page in a 6229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * web browser), they can be killed without too much harm. You can set this 623d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * flag if killing your service would be disruptive to the user, such as 6249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if your service is performing background music playback, so the user 6259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * would notice if their music stopped playing. 6269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 6270766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * <p>If you need your application to run on platform versions prior to API 6284f3867e3ce92101224ad79b8f2ff446bb4f99108Dianne Hackborn * level 5, you can use the following model to call the the older setForeground() 6290766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * or this modern method as appropriate: 6300766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * 631ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/ForegroundService.java 632ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * foreground_compatibility} 6330766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * 634d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @param id The identifier for this notification as per 635d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * {@link NotificationManager#notify(int, Notification) 636d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * NotificationManager.notify(int, Notification)}. 637d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @param notification The Notification to be displayed. 638d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * 639d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @see #stopForeground(boolean) 6409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 641d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void startForeground(int id, Notification notification) { 642d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn try { 643d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn mActivityManager.setServiceForeground( 644d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn new ComponentName(this, mClassName), mToken, id, 645d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn notification, true); 646d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } catch (RemoteException ex) { 6479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 648d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } 649d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn 650d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn /** 651d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * Remove this service from foreground state, allowing it to be killed if 652d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * more memory is needed. 6531066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * @param removeNotification If true, the notification previously provided 6541066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * to {@link #startForeground} will be removed. Otherwise it will remain 6551066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * until a later call removes it (or the service is destroyed). 656d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @see #startForeground(int, Notification) 657d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn */ 658d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void stopForeground(boolean removeNotification) { 6599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 6609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager.setServiceForeground( 661d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn new ComponentName(this, mClassName), mToken, 0, null, 662d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn removeNotification); 6639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 6649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 6689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Print the Service's state into the given stream. This gets invoked if 6695554b7082220d37496e30f39a0d9146afc177ab4Jeff Sharkey * you run "adb shell dumpsys activity service <yourservicename>". 6705554b7082220d37496e30f39a0d9146afc177ab4Jeff Sharkey * This is distinct from "dumpsys <servicename>", which only works for 6719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * named system services and which invokes the {@link IBinder#dump} method 6729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * on the {@link IBinder} interface registered with ServiceManager. 6739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 6749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param fd The raw file descriptor that the dump is being sent to. 6759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param writer The PrintWriter to which you should dump your state. This will be 6769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * closed for you after you return. 6779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param args additional arguments to the dump request. 6789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project protected void dump(FileDescriptor fd, PrintWriter writer, String[] args) { 6809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project writer.println("nothing to dump"); 6819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // ------------------ Internal API ------------------ 6849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 6869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @hide 6879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void attach( 6899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Context context, 6909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ActivityThread thread, String className, IBinder token, 6919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Application application, Object activityManager) { 6929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project attachBaseContext(context); 6939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mThread = thread; // NOTE: unused - remove? 6949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mClassName = className; 6959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mToken = token; 6969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mApplication = application; 6979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager = (IActivityManager)activityManager; 698f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn mStartCompatibility = getApplicationInfo().targetSdkVersion 699f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn < Build.VERSION_CODES.ECLAIR; 7009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 7019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 7029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project final String getClassName() { 7039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mClassName; 7049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 7059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 7069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // set by the thread after the constructor and before onCreate(Bundle icicle) is called. 7079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private ActivityThread mThread = null; 7089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private String mClassName = null; 7099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private IBinder mToken = null; 7109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private Application mApplication = null; 7119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private IActivityManager mActivityManager = null; 712f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn private boolean mStartCompatibility = false; 7139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 714