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