diff --git a/docs/xml/Android.App/Service.xml b/docs/xml/Android.App/Service.xml index dd306762b..d873ce358 100644 --- a/docs/xml/Android.App/Service.xml +++ b/docs/xml/Android.App/Service.xml @@ -57,39 +57,39 @@ as a standard implementation of Service that has its own thread where it schedules its work to be done. Topics covered here: - <ol> - <li>What is a Service?<li>Service Lifecycle<li>Permissions<li>Process Lifecycle<li>Local Service Sample<li>Remote Messenger Service Sample</ol> - - <div class="special reference"> - <h3>Developer Guides</h3> +
    +
  1. What is a Service?
  2. Service Lifecycle
  3. Permissions
  4. Process Lifecycle
  5. Local Service Sample
  6. Remote Messenger Service Sample
+ +
+

Developer Guides

For a detailed discussion about how to create services, read the Services developer guide. - </div> - - "WhatIsAService"><h3>What is a Service?</h3> + + +

What is a Service?

 Most confusion about the Service class actually revolves around what - it is <em>not</em>: - <ul> - <li> A Service is <b>not</b> a separate process. The Service object itself + it is not: + Thus a Service itself is actually very simple, providing two main features: - <ul> - <li>A facility for the application to tell the system <em>about</em> + When a Service component is actually created, for either of these reasons, all that the system actually does is instantiate the component and call its #onCreate and any other appropriate callbacks on the @@ -100,7 +100,7 @@ as a local Java object that you make direct method calls on (as illustrated by Local Service Sample), to providing a full remoteable interface using AIDL. - "ServiceLifecycle"><h3>Service Lifecycle</h3> +

Service Lifecycle

 There are two reasons that a service can be run by the system. If someone calls android.content.Context#startService Context.startService() then the system will retrieve the service (creating it and calling its #onCreate method @@ -133,14 +133,14 @@ in aidl. A service can be both started and have connections bound to it. In such a case, the system will keep the service running as long as either it is - started <em>or</em> there are one or more connections to it with the + started or there are one or more connections to it with the android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE flag. Once neither of these situations hold, the service's #onDestroy method is called and the service is effectively terminated. All cleanup (stopping threads, - unregistering receivers) should be complete upon returning from onDestroy(). - - "Permissions"><h3>Permissions</h3> + unregistering receivers) should be complete upon returning from onDestroy(). + +

Permissions

 Global access to a service can be enforced when it is declared in its manifest's android.R.styleable#AndroidManifestService &lt;service&gt; tag. By doing so, other applications will need to declare a corresponding @@ -163,49 +163,45 @@ #checkCallingPermission method before executing the implementation of that call. See the Security and Permissions - document for more information on permissions and security in general. - - "ProcessLifecycle"><h3>Process Lifecycle</h3> + document for more information on permissions and security in general. + +

Process Lifecycle

 The Android system will attempt to keep the process hosting a service around as long as the service has been started or has clients bound to it. When running low on memory and needing to kill existing processes, the priority of a process hosting the service will be the higher of the - following possibilities: - - <ul> - <li> - If the service is currently executing code in its - #onCreate onCreate(), #onStartCommand onStartCommand(), - or #onDestroy onDestroy() methods, then the hosting process will - be a foreground process to ensure this code can execute without - being killed. - <li> - If the service has been started, then its hosting process is considered - to be less important than any processes that are currently visible to the - user on-screen, but more important than any process not visible. Because - only a few processes are generally visible to the user, this means that - the service should not be killed except in low memory conditions. However, since - the user is not directly aware of a background service, in that state it <em>is</em> - considered a valid candidate to kill, and you should be prepared for this to - happen. In particular, long-running services will be increasingly likely to - kill and are guaranteed to be killed (and restarted if appropriate) if they - remain started long enough. - <li> - If there are clients bound to the service, then the service's hosting - process is never less important than the most important client. That is, - if one of its clients is visible to the user, then the service itself is - considered to be visible. The way a client's importance impacts the service's - importance can be adjusted through Context#BIND_ABOVE_CLIENT, - Context#BIND_ALLOW_OOM_MANAGEMENT, Context#BIND_WAIVE_PRIORITY, - Context#BIND_IMPORTANT, and Context#BIND_ADJUST_WITH_ACTIVITY. - <li> - A started service can use the #startForeground(int, Notification) - API to put the service in a foreground state, where the system considers - it to be something the user is actively aware of and thus not a candidate - for killing when low on memory. (It is still theoretically possible for - the service to be killed under extreme memory pressure from the current - foreground application, but in practice this should not be a concern.) - </ul> + following possibilities: + + Note this means that most of the time your service is running, it may be killed by the system if it is under heavy memory pressure. If this happens, the system will later try to restart the service. An important @@ -217,9 +213,9 @@ Other application components running in the same process as the service (such as an android.app.Activity) can, of course, increase the importance of the overall - process beyond just the importance of the service itself. - - "LocalServiceSample"><h3>Local Service Sample</h3> + process beyond just the importance of the service itself. + +

Local Service Sample

 One of the most common uses of a Service is as a secondary component running alongside other parts of an application, in the same process as the rest of the components. All components of an .apk run in the same @@ -230,17 +226,17 @@ receive from it to a concrete class published by the service. An example of this use of a Service is shown here. First is the Service itself, publishing a custom class when bound: - - { + + Java documentation for android.app.Service. - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -324,9 +320,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -376,9 +372,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -428,9 +424,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -497,10 +493,10 @@ Context.bindService. Note that any extras that were included with the Intent at that point will <em>not</em> be seen here. Return the communication channel to the service. - Return an IBinder through which clients can call on to the + Return an IBinder through which clients can call on to the service. - Return the communication channel to the service. May return null if + Return the communication channel to the service. May return null if clients can not bind to the service. The returned android.os.IBinder is usually for a complex interface that has been described using @@ -516,9 +512,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -590,9 +586,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -631,9 +627,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -712,9 +708,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -759,9 +755,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -805,27 +801,27 @@ - The Intent supplied to android.content.Context#startService, + The Intent supplied to android.content.Context#startService, as given. This may be null if the service is being restarted after its process has gone away, and it had previously returned anything except #START_STICKY_COMPATIBILITY. Additional data about this start request. - A unique integer representing this specific request to + A unique integer representing this specific request to start. Use with #stopSelfResult(int). - Called by the system every time a client explicitly starts the service by calling - android.content.Context#startService, providing the arguments it supplied and a + Called by the system every time a client explicitly starts the service by calling + android.content.Context#startService, providing the arguments it supplied and a unique integer token representing the start request. The return value indicates what semantics the system should use for the service's current started state. It may be one of the constants associated with the #START_CONTINUATION_MASK bits. - Called by the system every time a client explicitly starts the service by calling - android.content.Context#startService, providing the arguments it supplied and a + Called by the system every time a client explicitly starts the service by calling + android.content.Context#startService, providing the arguments it supplied and a unique integer token representing the start request. Do not call this method directly. For backwards compatibility, the default implementation calls #onStart and returns either #START_STICKY or #START_STICKY_COMPATIBILITY. - + <p class="caution">Note that the system calls this on your service's main thread. A service's main thread is the same thread where UI operations take place for Activities running in the @@ -839,9 +835,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -887,9 +883,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -948,9 +944,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1044,9 +1040,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1094,9 +1090,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1165,7 +1161,7 @@ for more details. </div> - + <div class="caution"> <strong>Note:</strong> Beginning with SDK Version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, @@ -1185,9 +1181,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1262,7 +1258,7 @@ for more details. </div> - + <div class="caution"> <strong>Note:</strong> Beginning with SDK Version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, @@ -1283,9 +1279,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1351,9 +1347,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1400,9 +1396,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1450,9 +1446,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1499,9 +1495,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1546,9 +1542,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1584,9 +1580,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1626,9 +1622,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License. @@ -1659,14 +1655,14 @@ The most recent start identifier received in #onStart. - Stop the service if the most recent time it was started was + Stop the service if the most recent time it was started was <var>startId</var>. Returns true if the startId matches the last start request and the service will be stopped, else false. - Stop the service if the most recent time it was started was - <var>startId</var>. This is the same as calling android.content.Context#stopService for this particular service but allows you to - safely avoid stopping if there is a start request from a client that you + Stop the service if the most recent time it was started was + <var>startId</var>. This is the same as calling android.content.Context#stopService for this particular service but allows you to + safely avoid stopping if there is a start request from a client that you haven't yet seen in #onStart. <em>Be careful about ordering of your calls to this function.</em>. If you call this function with the most-recently received ID before @@ -1680,9 +1676,9 @@ - Portions of this page are modifications based on work created and shared by the + Portions of this page are modifications based on work created and shared by the Android Open Source Project - and used according to terms described in the + and used according to terms described in the Creative Commons 2.5 Attribution License.