Service.java revision f6f9f2d0256930ce0bb4913b2260b8480914edc2
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 199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.content.ComponentCallbacks; 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/** 349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * A Service is an application component that runs in the background, not 359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * interacting with the user, for an indefinite period of time. Each service 369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * class must have a corresponding 379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.styleable#AndroidManifestService <service>} 389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * declaration in its package's <code>AndroidManifest.xml</code>. Services 399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * can be started with 409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#startService Context.startService()} and 419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#bindService Context.bindService()}. 429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that services, like other application objects, run in the main 449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * thread of their hosting process. This means that, if your service is going 459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to do any CPU intensive (such as MP3 playback) or blocking (such as 469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * networking) operations, it should spawn its own thread in which to do that 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * work. More information on this can be found in 489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a href="{@docRoot}guide/topics/fundamentals.html#procthread">Application Fundamentals: 499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Processes and Threads</a>.</p> 509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>The Service class is an important part of an 529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a href="{@docRoot}guide/topics/fundamentals.html#lcycles">application's overall lifecycle</a>.</p> 539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Topics covered here: 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <ol> 569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><a href="#ServiceLifecycle">Service Lifecycle</a> 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><a href="#Permissions">Permissions</a> 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><a href="#ProcessLifecycle">Process Lifecycle</a> 599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * </ol> 609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a name="ServiceLifecycle"></a> 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <h3>Service Lifecycle</h3> 639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>There are two reasons that a service can be run by the system. If someone 659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * calls {@link android.content.Context#startService Context.startService()} then the system will 669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * retrieve the service (creating it and calling its {@link #onCreate} method 679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if needed) and then call its {@link #onStart} method with the 689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * arguments supplied by the client. The service will at this point continue 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * running until {@link android.content.Context#stopService Context.stopService()} or 709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #stopSelf()} is called. Note that multiple calls to 719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.startService() do not nest (though they do result in multiple corresponding 729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * calls to onStart()), so no matter how many times it is started a service 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will be stopped once Context.stopService() or stopSelf() is called. 749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Clients can also use {@link android.content.Context#bindService Context.bindService()} to 769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * obtain a persistent connection to a service. This likewise creates the 779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service if it is not already running (calling {@link #onCreate} while 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * doing so), but does not call onStart(). The client will receive the 799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.os.IBinder} object that the service returns from its 809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onBind} method, allowing the client to then make calls back 819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to the service. The service will remain running as long as the connection 829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * is established (whether or not the client retains a reference on the 839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service's IBinder). Usually the IBinder returned is for a complex 849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * interface that has been <a href="{@docRoot}guide/developing/tools/aidl.html">written 859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in aidl</a>. 869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>A service can be both started and have connections bound to it. In such 889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a case, the system will keep the service running as long as either it is 899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * started <em>or</em> there are one or more connections to it with the 909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE} 919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * flag. Once neither 929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * of these situations hold, the service's {@link #onDestroy} method is called 939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * and the service is effectively terminated. All cleanup (stopping threads, 949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * unregistering receivers) should be complete upon returning from onDestroy(). 959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a name="Permissions"></a> 979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <h3>Permissions</h3> 989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Global access to a service can be enforced when it is declared in its 1009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * manifest's {@link android.R.styleable#AndroidManifestService <service>} 1019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * tag. By doing so, other applications will need to declare a corresponding 1029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>} 1039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * element in their own manifest to be able to start, stop, or bind to 1049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the service. 1059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>In addition, a service can protect individual IPC calls into it with 1079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * permissions, by calling the 1089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #checkCallingPermission} 1099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * method before executing the implementation of that call. 1109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>See the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> 1129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * document for more information on permissions and security in general. 1139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <a name="ProcessLifecycle"></a> 1159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <h3>Process Lifecycle</h3> 1169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>The Android system will attempt to keep the process hosting a service 1189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * around as long as the service has been started or has clients bound to it. 1199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * When running low on memory and needing to kill existing processes, the 1209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * priority of a process hosting the service will be the higher of the 1219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * following possibilities: 1229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <ul> 1249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If the service is currently executing code in its 1259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onCreate onCreate()}, {@link #onStart onStart()}, 1269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or {@link #onDestroy onDestroy()} methods, then the hosting process will 1279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * be a foreground process to ensure this code can execute without 1289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * being killed. 1299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If the service has been started, then its hosting process is considered 1309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to be less important than any processes that are currently visible to the 1319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * user on-screen, but more important than any process not visible. Because 1329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * only a few processes are generally visible to the user, this means that 1339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the service should not be killed except in extreme low memory conditions. 1349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <li><p>If there are clients bound to the service, then the service's hosting 1359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * process is never less important than the most important client. That is, 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if one of its clients is visible to the user, then the service itself is 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * considered to be visible. 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * </ul> 1399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note this means that most of the time your service is running, it may 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * be killed by the system if it is under heavy memory pressure. If this 1429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * happens, the system will later try to restart the service. An important 1439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * consequence of this is that if you implement {@link #onStart onStart()} 1449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to schedule work to be done asynchronously or in another thread, then you 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * may want to write information about that work into persistent storage 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * during the onStart() call so that it does not get lost if the service later 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * gets killed. 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Other application components running in the same process as the service 1509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * (such as an {@link android.app.Activity}) can, of course, increase the 1519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * importance of the overall 1529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * process beyond just the importance of the service itself. 1539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic abstract class Service extends ContextWrapper implements ComponentCallbacks { 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private static final String TAG = "Service"; 1569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Service() { 1589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project super(null); 1599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** Return the application that owns this service. */ 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final Application getApplication() { 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mApplication; 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system when the service is first created. Do not call this method directly. 1689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onCreate() { 1709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 173f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @deprecated Implement {@link #onStartCommand(Intent, int, int)} instead. 174f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 175f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn @Deprecated 176f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public void onStart(Intent intent, int startId) { 177f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn } 178f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 179f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 180f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Bits returned by {@link #onStartCommand} describing how to continue 181f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * the service if it is killed. May be {@link #START_STICKY}, 182f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #START_NOT_STICKY}, {@link #START_REDELIVER_INTENT}, 183f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * or {@link #START_STICKY_COMPATIBILITY}. 184f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 185f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_CONTINUATION_MASK = 0xf; 186f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 187f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 188f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: compatibility 189f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * version of {@link #START_STICKY} that does not guarantee that 190f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand} will be called again after being killed. 191f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 192f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_STICKY_COMPATIBILITY = 0; 193f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 194f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 195f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 196f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 197f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), then leave it in the started state but 198f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * don't retain this delivered intent. Later the system will try to 199f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * re-create the service, but it will <em>not</em> call 200f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand} unless there has been a new call to 201f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link Context#startService Context.startService(Intent)} with a new 202f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Intent to deliver. 203f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 204f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>This mode makes sense for things that will be explicitly started 205f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and stopped to run for arbitrary periods of time, such as a service 206f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * performing background music playback. 207f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 208f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_STICKY = 1; 209f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 210f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 211f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 212f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 213f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), and there are no new start intents to 214f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * deliver to it, then take the service out of the started state and 215f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * don't recreate until a future explicit call to 216f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link Context#startService Context.startService(Intent)}. 217f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 218f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>This mode makes sense for things that want to do some work as a 219f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * result of being started, but can be stopped when under memory pressure 220f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and will explicit start themselves again later to do more work. An 221f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * example of such a service would be one that polls for data from 222f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * a server: it could schedule an alarm to poll every N minutes by having 223f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * the alarm start its service. When its {@link #onStartCommand} is 224f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * called from the alarm, it schedules a new alarm for N minutes later, 225f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and spawns a thread to do its networking. If its process is killed 226f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * while doing that check, the service will not be restarted until the 227f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * alarm goes off. 228f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 229f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_NOT_STICKY = 2; 230f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 231f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 232f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * Constant to return from {@link #onStartCommand}: if this service's 233f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * process is killed while it is started (after returning from 234f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}), then it will be scheduled for a restart 235f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * and the last delivered Intent re-delivered to it again via 236f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand}. This Intent will remain scheduled for 237f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * redelivery until the service calls {@link #stopSelf(int)} with the 238f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * start ID provided to {@link #onStartCommand}. 239f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 240f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_REDELIVER_INTENT = 3; 241f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 242f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 243f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * This flag is set in {@link #onStartCommand} if the Intent is a 244f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * re-delivery of a previously delivered intent, because the service 245f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * had previously returned {@link #START_REDELIVER_INTENT} but had been 246f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * killed before calling {@link #stopSelf(int)} for that Intent. 247f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 248f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_FLAG_REDELIVERY = 0x0001; 249f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 250f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 251f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * This flag is set in {@link #onStartCommand} if the Intent is a 252f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * a retry because the original attempt never got to or returned from 253f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStartCommand(Intent, int, int)}. 254f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn */ 255f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public static final int START_FLAG_RETRY = 0x0002; 256f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 257f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn /** 2589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system every time a client explicitly starts the service by calling 2599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.content.Context#startService}, providing the arguments it supplied and a 2609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * unique integer token representing the start request. Do not call this method directly. 261f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 262f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * <p>For backwards compatibility, the default implementation calls 263f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * {@link #onStart} and returns either {@link #START_STICKY} 264f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * or {@link #START_STICKY_COMPATIBILITY}. 265f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 2669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent supplied to {@link android.content.Context#startService}, 267f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * as given. This may be null if the service is being restarted after 268f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * its process has gone away, and it had previously returned anything 269f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * except {@link #START_STICKY_COMPATIBILITY}. 270f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @param flags Additional data about this start request. Currently either 271f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 0, {@link #START_FLAG_REDELIVERY}, or {@link #START_FLAG_RETRY}. 2729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param startId A unique integer representing this specific request to 273f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * start. Use with {@link #stopSelfResult(int)}. 274f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * 275f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * @return The return value indicates what semantics the system should 276f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * use for the service's current started state. It may be one of the 277f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn * constants associated with the {@link #START_CONTINUATION_MASK} bits. 2789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult(int) 2809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 281f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn public int onStartCommand(Intent intent, int flags, int startId) { 282f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn onStart(intent, startId); 283f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn return mStartCompatibility ? START_STICKY_COMPATIBILITY : START_STICKY; 2849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 285f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn 2869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called by the system to notify a Service that it is no longer used and is being removed. The 2889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service should clean up an resources it holds (threads, registered 2899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * receivers, etc) at this point. Upon return, there will be no more calls 2909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in to this Service object and it is effectively dead. Do not call this method directly. 2919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onDestroy() { 2939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onConfigurationChanged(Configuration newConfig) { 2969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onLowMemory() { 2999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Return the communication channel to the service. May return null if 3039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * clients can not bind to the service. The returned 3049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.os.IBinder} is usually for a complex interface 3059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * that has been <a href="{@docRoot}guide/developing/tools/aidl.html">described using 3069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * aidl</a>. 3079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p><em>Note that unlike other application components, calls on to the 3099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * IBinder interface returned here may not happen on the main thread 3109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * of the process</em>. More information about this can be found 3119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in <a href="{@docRoot}guide/topics/fundamentals.html#procthread">Application Fundamentals: 3129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Processes and Threads</a>.</p> 3139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 3159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 3169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 3179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 3189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Return an IBinder through which clients can call on to the 3209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * service. 3219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public abstract IBinder onBind(Intent intent); 3239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when all clients have disconnected from a particular interface 3269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * published by the service. The default implementation does nothing and 3279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returns false. 3289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 3309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 3319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 3329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 3339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Return true if you would like to have the service's 3359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onRebind} method later called when new clients bind to it. 3369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean onUnbind(Intent intent) { 3389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 3399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when new clients have connected to the service, after it had 3439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * previously been notified that all had disconnected in its 3449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #onUnbind}. This will only be called if the implementation 3459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * of {@link #onUnbind} was overridden to return true. 3469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param intent The Intent that was used to bind to this service, 3489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * as given to {@link android.content.Context#bindService 3499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context.bindService}. Note that any extras that were included with 3509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Intent at that point will <em>not</em> be seen here. 3519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onRebind(Intent intent) { 3539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Stop the service, if it was previously started. This is the same as 3579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * calling {@link android.content.Context#stopService} for this particular service. 3589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult(int) 3609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void stopSelf() { 3629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project stopSelf(-1); 3639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Old version of {@link #stopSelfResult} that doesn't return a result. 3679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelfResult 3699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void stopSelf(int startId) { 3719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (mActivityManager == null) { 3729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return; 3739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 3759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager.stopServiceToken( 3769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project new ComponentName(this, mClassName), mToken, startId); 3779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 3789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 382105925376f8d0f6b318c9938c7b83ef7fef094daThe Android Open Source Project * Stop the service if the most recent time it was started was 3839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <var>startId</var>. This is the same as calling {@link 3849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * android.content.Context#stopService} for this particular service but allows you to 3859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * safely avoid stopping if there is a start request from a client that you 386105925376f8d0f6b318c9938c7b83ef7fef094daThe Android Open Source Project * haven't yet seen in {@link #onStart}. 3879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param startId The most recent start identifier received in {@link 3899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * #onStart}. 3909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns true if the startId matches the last start request 3919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * and the service will be stopped, else false. 3929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #stopSelf() 3949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final boolean stopSelfResult(int startId) { 3969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (mActivityManager == null) { 3979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 3989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 4009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mActivityManager.stopServiceToken( 4019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project new ComponentName(this, mClassName), mToken, startId); 4029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 4039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 4059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 408d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @deprecated This is a now a no-op, use 409d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * {@link #startForeground(int, Notification)} instead. 410d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn */ 411d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn @Deprecated 412d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void setForeground(boolean isForeground) { 413d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn Log.w(TAG, "setForeground: ignoring old API call on " + getClass().getName()); 414d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } 415d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn 416d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn /** 417d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * Make this service run in the foreground, supplying the ongoing 418d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * notification to be shown to the user while in this state. 4199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * By default services are background, meaning that if the system needs to 4209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * kill them to reclaim more memory (such as to display a large page in a 4219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * web browser), they can be killed without too much harm. You can set this 422d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * flag if killing your service would be disruptive to the user, such as 4239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if your service is performing background music playback, so the user 4249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * would notice if their music stopped playing. 4259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 426d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @param id The identifier for this notification as per 427d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * {@link NotificationManager#notify(int, Notification) 428d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * NotificationManager.notify(int, Notification)}. 429d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @param notification The Notification to be displayed. 430d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * 431d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @see #stopForeground(boolean) 4329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 433d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void startForeground(int id, Notification notification) { 434d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn try { 435d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn mActivityManager.setServiceForeground( 436d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn new ComponentName(this, mClassName), mToken, id, 437d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn notification, true); 438d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } catch (RemoteException ex) { 4399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 440d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn } 441d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn 442d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn /** 443d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * Remove this service from foreground state, allowing it to be killed if 444d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * more memory is needed. 4451066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * @param removeNotification If true, the notification previously provided 4461066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * to {@link #startForeground} will be removed. Otherwise it will remain 4471066cbcac08268e2254ed6818181949d83e9ba1cDianne Hackborn * until a later call removes it (or the service is destroyed). 448d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn * @see #startForeground(int, Notification) 449d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn */ 450d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn public final void stopForeground(boolean removeNotification) { 4519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project try { 4529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager.setServiceForeground( 453d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn new ComponentName(this, mClassName), mToken, 0, null, 454d8a43f61680bacf0d4b52a03ff3c7a07307377fcDianne Hackborn removeNotification); 4559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } catch (RemoteException ex) { 4569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Print the Service's state into the given stream. This gets invoked if 4619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you run "adb shell dumpsys activity service <yourservicename>". 4629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * This is distinct from "dumpsys <servicename>", which only works for 4639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * named system services and which invokes the {@link IBinder#dump} method 4649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * on the {@link IBinder} interface registered with ServiceManager. 4659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 4669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param fd The raw file descriptor that the dump is being sent to. 4679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param writer The PrintWriter to which you should dump your state. This will be 4689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * closed for you after you return. 4699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param args additional arguments to the dump request. 4709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project protected void dump(FileDescriptor fd, PrintWriter writer, String[] args) { 4729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project writer.println("nothing to dump"); 4739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 4769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project protected void finalize() throws Throwable { 4779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project super.finalize(); 4789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project //Log.i("Service", "Finalizing Service: " + this); 4799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // ------------------ Internal API ------------------ 4829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @hide 4859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public final void attach( 4879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Context context, 4889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ActivityThread thread, String className, IBinder token, 4899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Application application, Object activityManager) { 4909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project attachBaseContext(context); 4919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mThread = thread; // NOTE: unused - remove? 4929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mClassName = className; 4939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mToken = token; 4949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mApplication = application; 4959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mActivityManager = (IActivityManager)activityManager; 496f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn mStartCompatibility = getApplicationInfo().targetSdkVersion 497f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn < Build.VERSION_CODES.ECLAIR; 4989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 4999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project final String getClassName() { 5019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mClassName; 5029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 5039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // set by the thread after the constructor and before onCreate(Bundle icicle) is called. 5059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private ActivityThread mThread = null; 5069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private String mClassName = null; 5079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private IBinder mToken = null; 5089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private Application mApplication = null; 5099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project private IActivityManager mActivityManager = null; 510f6f9f2d0256930ce0bb4913b2260b8480914edc2Dianne Hackborn private boolean mStartCompatibility = false; 5119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 512