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