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 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * interface that has been <a href="{@docRoot}guide/developing/tools/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. 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>In addition, a service can protect individual IPC calls into it with 1689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * permissions, by calling the 1699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #checkCallingPermission} 1709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * method before executing the implementation of that call. 1719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>See the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> 1739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * document for more information on permissions and security in general. 1749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a name="ProcessLifecycle"></a> 1769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <h3>Process Lifecycle</h3> 1779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>The Android system will attempt to keep the process hosting a service 1799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * around as long as the service has been started or has clients bound to it. 1809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * When running low on memory and needing to kill existing processes, the 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * priority of a process hosting the service will be the higher of the 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * following possibilities: 1839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <ul> 1859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If the service is currently executing code in its 186fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * {@link #onCreate onCreate()}, {@link #onStartCommand onStartCommand()}, 1879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or {@link #onDestroy onDestroy()} methods, then the hosting process will 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * be a foreground process to ensure this code can execute without 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * being killed. 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If the service has been started, then its hosting process is considered 1919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to be less important than any processes that are currently visible to the 1929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * user on-screen, but more important than any process not visible. Because 1939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * only a few processes are generally visible to the user, this means that 1949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the service should not be killed except in extreme low memory conditions. 1959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If there are clients bound to the service, then the service's hosting 1969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * process is never less important than the most important client. That is, 1979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if one of its clients is visible to the user, then the service itself is 1989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * considered to be visible. 199fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * <li><p>A started service can use the {@link #startForeground(int, Notification)} 200fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * API to put the service in a foreground state, where the system considers 201fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * it to be something the user is actively aware of and thus not a candidate 202fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * for killing when low on memory. (It is still theoretically possible for 203fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * the service to be killed under extreme memory pressure from the current 204fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * foreground application, but in practice this should not be a concern.) 2059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * </ul> 2069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note this means that most of the time your service is running, it may 2089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * be killed by the system if it is under heavy memory pressure. If this 2099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * happens, the system will later try to restart the service. An important 210fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * consequence of this is that if you implement {@link #onStartCommand onStartCommand()} 2119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to schedule work to be done asynchronously or in another thread, then you 21229e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * may want to use {@link #START_FLAG_REDELIVERY} to have the system 21329e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * re-deliver an Intent for you so that it does not get lost if your service 21429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * is killed while processing it. 2159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Other application components running in the same process as the service 2179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * (such as an {@link android.app.Activity}) can, of course, increase the 2189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * importance of the overall 2199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * process beyond just the importance of the service itself. 22075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 22175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <a name="LocalServiceSample"></a> 22275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <h3>Local Service Sample</h3> 22375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 22475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>One of the most common uses of a Service is as a secondary component 22575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * running alongside other parts of an application, in the same process as 22675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * the rest of the components. All components of an .apk run in the same 22775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * process unless explicitly stated otherwise, so this is a typical situation. 22875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 22975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>When used in this way, by assuming the 23075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * components are in the same process, you can greatly simplify the interaction 23175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * between them: clients of the service can simply cast the IBinder they 23275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * receive from it to a concrete class published by the service. 23375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 23475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>An example of this use of a Service is shown here. First is the Service 23575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * itself, publishing a custom class when bound: 23675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 23775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalService.java 23875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * service} 23975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 24075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>With that done, one can now write client code that directly accesses the 24175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * running service, such as: 24275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 24375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.java 24475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * bind} 24575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 24675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <a name="RemoteMessengerServiceSample"></a> 24775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <h3>Remote Messenger Service Sample</h3> 24875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 24975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>If you need to be able to write a Service that can perform complicated 25075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * communication with clients in remote processes (beyond simply the use of 25175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@link Context#startService(Intent) Context.startService} to send 25275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * commands to it), then you can use the {@link android.os.Messenger} class 25375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * instead of writing full AIDL files. 25475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 25575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>An example of a Service that uses Messenger as its client interface 25675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * is shown here. First is the Service itself, publishing a Messenger to 25775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * an internal Handler when bound: 25875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 25975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.java 26075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * service} 26175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 26275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>If we want to make this service run in a remote process (instead of the 26375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * standard one for its .apk), we can use <code>android:process</code> in its 26475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * manifest tag to specify one: 26575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 26675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/AndroidManifest.xml remote_service_declaration} 26775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 26875288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>Note that the name "remote" chosen here is arbitrary, and you can use 26975288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * other names if you want additional processes. The ':' prefix appends the 27075288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * name to your package's standard process name. 27175288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 27275288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * <p>With that done, clients can now bind to the service and send messages 27375288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * to it. Note that this allows clients to register with it to receive 27475288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * messages back as well: 27575288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * 27675288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.java 27775288fa1a4ee4886959af7243995d8afd9c3c905Dianne Hackborn * bind} 2789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 279c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackbornpublic abstract class Service extends ContextWrapper implements ComponentCallbacks2 { 2809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private static final String TAG = "Service"; 2819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Service() { 2839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project super(null); 2849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** Return the application that owns this service. */ 2879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final Application getApplication() { 2889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mApplication; 2899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system when the service is first created. Do not call this method directly. 2939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onCreate() { 2959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 298f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @deprecated Implement {@link #onStartCommand(Intent, int, int)} instead. 299f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 300f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn @Deprecated 301f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public void onStart(Intent intent, int startId) { 302f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn } 303f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 304f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 305f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Bits returned by {@link #onStartCommand} describing how to continue 306f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * the service if it is killed. May be {@link #START_STICKY}, 307f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #START_NOT_STICKY}, {@link #START_REDELIVER_INTENT}, 308f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * or {@link #START_STICKY_COMPATIBILITY}. 309f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 310f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_CONTINUATION_MASK = 0xf; 311f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 312f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 313f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: compatibility 314f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * version of {@link #START_STICKY} that does not guarantee that 315f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand} will be called again after being killed. 316f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 317f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_STICKY_COMPATIBILITY = 0; 318f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 319f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 320f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 321f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 322f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), then leave it in the started state but 323f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * don't retain this delivered intent. Later the system will try to 324fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * re-create the service. Because it is in the started state, it will 325fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * guarantee to call {@link #onStartCommand} after creating the new 326fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * service instance; if there are not any pending start commands to be 327fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * delivered to the service, it will be called with a null intent 328fed534ee5d47a96c1d104f9bd303e9480102813cDianne Hackborn * object, so you must take care to check for this. 329f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 330f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>This mode makes sense for things that will be explicitly started 331f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and stopped to run for arbitrary periods of time, such as a service 332f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * performing background music playback. 333f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 334f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_STICKY = 1; 335f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 336f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 337f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 338f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 339f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), and there are no new start intents to 340f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * deliver to it, then take the service out of the started state and 341f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * don't recreate until a future explicit call to 34229e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * {@link Context#startService Context.startService(Intent)}. The 34329e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * service will not receive a {@link #onStartCommand(Intent, int, int)} 34429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * call with a null Intent because it will not be re-started if there 34529e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * are no pending Intents to deliver. 346f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 347f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>This mode makes sense for things that want to do some work as a 348f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * result of being started, but can be stopped when under memory pressure 349f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and will explicit start themselves again later to do more work. An 350f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * example of such a service would be one that polls for data from 351f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * a server: it could schedule an alarm to poll every N minutes by having 352f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * the alarm start its service. When its {@link #onStartCommand} is 353f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * called from the alarm, it schedules a new alarm for N minutes later, 354f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and spawns a thread to do its networking. If its process is killed 355f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * while doing that check, the service will not be restarted until the 356f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * alarm goes off. 357f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 358f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_NOT_STICKY = 2; 359f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 360f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 361f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 362f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 363f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), then it will be scheduled for a restart 364f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and the last delivered Intent re-delivered to it again via 365f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}. This Intent will remain scheduled for 366f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * redelivery until the service calls {@link #stopSelf(int)} with the 36729e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * start ID provided to {@link #onStartCommand}. The 36829e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * service will not receive a {@link #onStartCommand(Intent, int, int)} 36929e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * call with a null Intent because it will will only be re-started if 37029e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * it is not finished processing all Intents sent to it (and any such 37129e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * pending events will be delivered at the point of restart). 372f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 373f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_REDELIVER_INTENT = 3; 374f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 375f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 3760c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * Special constant for reporting that we are done processing 3770c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * {@link #onTaskRemoved(Intent)}. 3780c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * @hide 3790c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn */ 3800c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn public static final int START_TASK_REMOVED_COMPLETE = 1000; 3810c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn 3820c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn /** 383f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * This flag is set in {@link #onStartCommand} if the Intent is a 384f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * re-delivery of a previously delivered intent, because the service 385f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * had previously returned {@link #START_REDELIVER_INTENT} but had been 386f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * killed before calling {@link #stopSelf(int)} for that Intent. 387f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 388f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_FLAG_REDELIVERY = 0x0001; 389f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 390f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 391f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * This flag is set in {@link #onStartCommand} if the Intent is a 392f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * a retry because the original attempt never got to or returned from 393f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand(Intent, int, int)}. 394f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 395f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_FLAG_RETRY = 0x0002; 396f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 397f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 3989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system every time a client explicitly starts the service by calling 3999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#startService}, providing the arguments it supplied and a 4009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * unique integer token representing the start request. Do not call this method directly. 401f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 402f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>For backwards compatibility, the default implementation calls 403f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStart} and returns either {@link #START_STICKY} 404f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * or {@link #START_STICKY_COMPATIBILITY}. 405f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 4060766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * <p>If you need your application to run on platform versions prior to API 4070766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * level 5, you can use the following model to handle the older {@link #onStart} 4080766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * callback in that case. The <code>handleCommand</code> method is implemented by 4090766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * you as appropriate: 4100766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * 411ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/ForegroundService.java 412ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * start_compatibility} 4130166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * 4140166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * <p class="caution">Note that the system calls this on your 4150166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * service's main thread. A service's main thread is the same 416ee34a49ffc92590cb59f3e17a3df136b67701529Brad Fitzpatrick * thread where UI operations take place for Activities running in the 4170166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * same process. You should always avoid stalling the main 4180166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * thread's event loop. When doing long-running operations, 4190166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * network calls, or heavy disk I/O, you should kick off a new 4200166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * thread, or use {@link android.os.AsyncTask}.</p> 4210166c3530535355e7813f54c4e403a21db94a9d2Brad Fitzpatrick * 4229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent supplied to {@link android.content.Context#startService}, 423f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * as given. This may be null if the service is being restarted after 424f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * its process has gone away, and it had previously returned anything 425f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * except {@link #START_STICKY_COMPATIBILITY}. 426f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @param flags Additional data about this start request. Currently either 427f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 0, {@link #START_FLAG_REDELIVERY}, or {@link #START_FLAG_RETRY}. 4289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param startId A unique integer representing this specific request to 429f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * start. Use with {@link #stopSelfResult(int)}. 430f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 431f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @return The return value indicates what semantics the system should 432f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * use for the service's current started state. It may be one of the 433f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * constants associated with the {@link #START_CONTINUATION_MASK} bits. 4349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult(int) 4369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 437f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public int onStartCommand(Intent intent, int flags, int startId) { 438f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn onStart(intent, startId); 439f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn return mStartCompatibility ? START_STICKY_COMPATIBILITY : START_STICKY; 4409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 441f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 4429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system to notify a Service that it is no longer used and is being removed. The 4449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service should clean up an resources it holds (threads, registered 4459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * receivers, etc) at this point. Upon return, there will be no more calls 4469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in to this Service object and it is effectively dead. Do not call this method directly. 4479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onDestroy() { 4499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onConfigurationChanged(Configuration newConfig) { 4529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onLowMemory() { 4559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 456c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn 457c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn public void onTrimMemory(int level) { 458c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn } 459c68c913d357e2955d4bd7ca52829071e531c7825Dianne Hackborn 4609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Return the communication channel to the service. May return null if 4629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * clients can not bind to the service. The returned 4639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.os.IBinder} is usually for a complex interface 4649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * that has been <a href="{@docRoot}guide/developing/tools/aidl.html">described using 4659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * aidl</a>. 4669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p><em>Note that unlike other application components, calls on to the 4689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * IBinder interface returned here may not happen on the main thread 4697aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * of the process</em>. More information about the main thread can be found in 4707aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">Processes and 4717aee61f5a96e94e158bf5ad3d8e192c4d4f7eff6Scott Main * Threads</a>.</p> 4729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 4749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 4759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 4769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 4779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Return an IBinder through which clients can call on to the 4799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service. 4809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public abstract IBinder onBind(Intent intent); 4829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when all clients have disconnected from a particular interface 4859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * published by the service. The default implementation does nothing and 4869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returns false. 4879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 4899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 4909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 4919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 4929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Return true if you would like to have the service's 4949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onRebind} method later called when new clients bind to it. 4959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean onUnbind(Intent intent) { 4979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 4989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 5019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when new clients have connected to the service, after it had 5029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * previously been notified that all had disconnected in its 5039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onUnbind}. This will only be called if the implementation 5049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * of {@link #onUnbind} was overridden to return true. 5059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 5079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 5089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 5099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 5109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onRebind(Intent intent) { 5129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 5150c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * This is called if the service is currently running and the user has 5160c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * removed a task that comes from the service's application. If you have 5170c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * set {@link android.content.pm.ServiceInfo#FLAG_STOP_WITH_TASK ServiceInfo.FLAG_STOP_WITH_TASK} 5180c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * then you will not receive this callback; instead, the service will simply 5190c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * be stopped. 5200c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * 5210c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * @param rootIntent The original root Intent that was used to launch 5220c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn * the task that is being removed. 5230c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn */ 5240c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn public void onTaskRemoved(Intent rootIntent) { 5250c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn } 5260c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn 5270c5001d776d56bae02a5cc2663286a125d99bc5eDianne Hackborn /** 5289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Stop the service, if it was previously started. This is the same as 5299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * calling {@link android.content.Context#stopService} for this particular service. 5309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult(int) 5329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void stopSelf() { 5349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project stopSelf(-1); 5359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 5389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Old version of {@link #stopSelfResult} that doesn't return a result. 5399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult 5419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void stopSelf(int startId) { 5439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (mActivityManager == null) { 5449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return; 5459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 5479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager.stopServiceToken( 5489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project new ComponentName(this, mClassName), mToken, startId); 5499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 5509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 554105925376f8d0f6b318c9938c7b83ef7fef094daThe Android Open Source Project * Stop the service if the most recent time it was started was 5559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <var>startId</var>. This is the same as calling {@link 5569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * android.content.Context#stopService} for this particular service but allows you to 5579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * safely avoid stopping if there is a start request from a client that you 558105925376f8d0f6b318c9938c7b83ef7fef094daThe Android Open Source Project * haven't yet seen in {@link #onStart}. 5599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 56029e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * <p><em>Be careful about ordering of your calls to this function.</em>. 56129e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * If you call this function with the most-recently received ID before 56229e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * you have called it for previously received IDs, the service will be 56329e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * immediately stopped anyway. If you may end up processing IDs out 56429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * of order (such as by dispatching them on separate threads), then you 56529e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * are responsible for stopping them in the same order you received them.</p> 56629e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * 5679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param startId The most recent start identifier received in {@link 5689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * #onStart}. 5699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns true if the startId matches the last start request 5709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * and the service will be stopped, else false. 5719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 5729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelf() 5739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final boolean stopSelfResult(int startId) { 5759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (mActivityManager == null) { 5769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 5779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 5799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mActivityManager.stopServiceToken( 5809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project new ComponentName(this, mClassName), mToken, startId); 5819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 5829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 5849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 587d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @deprecated This is a now a no-op, use 58829e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * {@link #startForeground(int, Notification)} instead. This method 58929e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * has been turned into a no-op rather than simply being deprecated 59029e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * because analysis of numerous poorly behaving devices has shown that 59129e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * increasingly often the trouble is being caused in part by applications 59229e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * that are abusing it. Thus, given a choice between introducing 59329e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * problems in existing applications using this API (by allowing them to 59429e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * be killed when they would like to avoid it), vs allowing the performance 59529e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * of the entire system to be decreased, this method was deemed less 59629e4a3c566f435c32f0b95e4ac8e8b33cac6fabaDianne Hackborn * important. 5974f3867e3ce92101224ad79b8f2ff446bb4f99108Dianne Hackborn * 5984f3867e3ce92101224ad79b8f2ff446bb4f99108Dianne Hackborn * @hide 599d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn */ 600d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn @Deprecated 601d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void setForeground(boolean isForeground) { 602d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn Log.w(TAG, "setForeground: ignoring old API call on " + getClass().getName()); 603d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } 604d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn 605d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn /** 606d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * Make this service run in the foreground, supplying the ongoing 607d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * notification to be shown to the user while in this state. 6089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * By default services are background, meaning that if the system needs to 6099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * kill them to reclaim more memory (such as to display a large page in a 6109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * web browser), they can be killed without too much harm. You can set this 611d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * flag if killing your service would be disruptive to the user, such as 6129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if your service is performing background music playback, so the user 6139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * would notice if their music stopped playing. 6149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 6150766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * <p>If you need your application to run on platform versions prior to API 6164f3867e3ce92101224ad79b8f2ff446bb4f99108Dianne Hackborn * level 5, you can use the following model to call the the older setForeground() 6170766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * or this modern method as appropriate: 6180766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * 619ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/ForegroundService.java 620ab8a8ed2eb068b696f6b5519c55a03546a5927efDianne Hackborn * foreground_compatibility} 6210766b2d0f398dcad10e332b695bbc0cbe5011882Dianne Hackborn * 622d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @param id The identifier for this notification as per 623d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * {@link NotificationManager#notify(int, Notification) 624d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * NotificationManager.notify(int, Notification)}. 625d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @param notification The Notification to be displayed. 626d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * 627d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @see #stopForeground(boolean) 6289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 629d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void startForeground(int id, Notification notification) { 630d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn try { 631d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn mActivityManager.setServiceForeground( 632d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn new ComponentName(this, mClassName), mToken, id, 633d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn notification, true); 634d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } catch (RemoteException ex) { 6359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 636d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } 637d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn 638d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn /** 639d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * Remove this service from foreground state, allowing it to be killed if 640d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * more memory is needed. 6411066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * @param removeNotification If true, the notification previously provided 6421066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * to {@link #startForeground} will be removed. Otherwise it will remain 6431066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * until a later call removes it (or the service is destroyed). 644d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @see #startForeground(int, Notification) 645d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn */ 646d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void stopForeground(boolean removeNotification) { 6479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 6489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager.setServiceForeground( 649d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn new ComponentName(this, mClassName), mToken, 0, null, 650d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn removeNotification); 6519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 6529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 6569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Print the Service's state into the given stream. This gets invoked if 6579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you run "adb shell dumpsys activity service <yourservicename>". 6589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * This is distinct from "dumpsys <servicename>", which only works for 6599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * named system services and which invokes the {@link IBinder#dump} method 6609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * on the {@link IBinder} interface registered with ServiceManager. 6619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 6629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param fd The raw file descriptor that the dump is being sent to. 6639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param writer The PrintWriter to which you should dump your state. This will be 6649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * closed for you after you return. 6659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param args additional arguments to the dump request. 6669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project protected void dump(FileDescriptor fd, PrintWriter writer, String[] args) { 6689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project writer.println("nothing to dump"); 6699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // ------------------ Internal API ------------------ 6729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 6749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @hide 6759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void attach( 6779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Context context, 6789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ActivityThread thread, String className, IBinder token, 6799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Application application, Object activityManager) { 6809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project attachBaseContext(context); 6819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mThread = thread; // NOTE: unused - remove? 6829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mClassName = className; 6839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mToken = token; 6849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mApplication = application; 6859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager = (IActivityManager)activityManager; 686f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn mStartCompatibility = getApplicationInfo().targetSdkVersion 687f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn < Build.VERSION_CODES.ECLAIR; 6889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project final String getClassName() { 6919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mClassName; 6929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 6939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // set by the thread after the constructor and before onCreate(Bundle icicle) is called. 6959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private ActivityThread mThread = null; 6969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private String mClassName = null; 6979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private IBinder mToken = null; 6989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private Application mApplication = null; 6999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private IActivityManager mActivityManager = null; 700f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn private boolean mStartCompatibility = false; 7019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 702