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