service-element.jd revision 7f877069274c94b373478a8d0c969c9cfd93864f
1page.title=<service> 2@jd:body 3 4<dl class="xml"> 5<dt>syntax:</dt> 6<dd><pre class="stx"><service android:<a href="#enabled">enabled</a>=["true" | "false"] 7 android:<a href="#exported">exported[</a>="true" | "false"] 8 android:<a href="#icon">icon</a>="<i>drawable resource</i>" 9 android:<a href="#label">label</a>="<i>string resource</i>" 10 android:<a href="#nm">name</a>="<i>string</i>" 11 android:<a href="#prmsn">permission</a>="<i>string</i>" 12 android:<a href="#proc">process</a>="<i>string</i>" > 13 . . . 14</service></pre></dd> 15 16<dt>contained in:</dt> 17<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> 18 19<dt>can contain:</dt> 20<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 21<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> 22 23<dt>description:</dt> 24<dd>Declares a service (a {@link android.app.Service} subclass) as one 25of the application's components. Unlike activities, services lack a 26visual user interface. They're used to implement long-running background 27operations or a rich communications API that can be called by other 28applications. 29 30<p> 31All services must be represented by {@code <service>} elements in 32the manifest file. Any that are not declared there will not be seen 33by the system and will never be run. 34</p></dd> 35 36<dt>attributes:</dt> 37<dd><dl class="attr"> 38<dt><a name="enabled"></a>{@code android:enabled}</dt> 39<dd>Whether or not the service can be instantiated by the system — 40"{@code true}" if it can be, and "{@code false}" if not. The default value 41is "{@code true}". 42 43<p> 44The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own 45<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all 46application components, including services. The 47<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <service>} 48attributes must both be "{@code true}" (as they both 49are by default) for the service to be enabled. If either is 50"{@code false}", the service is disabled; it cannot be instantiated. 51</p></dd> 52 53<dt><a name="exported"></a>{@code android:exported}</dt> 54<dd>Whether or not components of other applications can invoke 55the service or interact with it — "{@code true}" if they can, and 56"{@code false}" if not. When the value is "{@code false}", only 57components of the same application or applications 58with the same user ID can start the service or bind to it. 59 60<p> 61The default value depends on whether the service contains intent filters. The 62absence of any filters means that it can be invoked only by specifying 63its exact class name. This implies that the service is intended only for 64application-internal use (since others would not know the class name). So in 65this case, the default value is "{@code false}". 66On the other hand, the presence of at least one filter implies that the service 67is intended for external use, so the default value is "{@code true}". 68</p> 69 70<p> 71This attribute is not the only way to limit the exposure of a service to other 72applications. You can also use a permission to limit the external entities that 73can interact with the service (see the <code><a href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">permission</a></code> 74attribute). 75</p></dd> 76 77<dt><a name="icon"></a>{@code android:icon}</dt> 78<dd>An icon representing the service. This attribute must be set as a 79reference to a drawable resource containing the image definition. 80If it is not set, the icon specified for the application 81as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 82element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). 83</p> 84 85<p> 86The service's icon — whether set here or by the 87<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the 88default icon for all the service's intent filters (see the 89<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's 90<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). 91</p></dd> 92 93<dt><a name="label"></a>{@code android:label}</dt> 94<dd>A name for the service that can be displayed to users. 95If this attribute is not set, the label set for the application as a whole is 96used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 97<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). 98 99<p> 100The service's label — whether set here or by the 101<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the 102default label for all the service's intent filters (see the 103<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's 104<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). 105</p> 106 107<p> 108The label should be set as a reference to a string resource, so that 109it can be localized like other strings in the user interface. 110However, as a convenience while you're developing the application, 111it can also be set as a raw string. 112</p></dd> 113 114<dt><a name="nm"></a>{@code android:name}</dt> 115<dd>The name of the {@link android.app.Service} subclass that implements 116the service. This should be a fully qualified class name (such as, 117"{@code com.example.project.RoomService}"). However, as a shorthand, if 118the first character of the name is a period (for example, "{@code .RoomService}"), 119it is appended to the package name specified in the 120<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. 121 122<p> 123There is no default. The name must be specified. 124</p></dd> 125 126<dt><a name="prmsn"></a>{@code android:permission}</dt> 127<dd>The name of a permission that that an entity must have in order to 128launch the service or bind to it. If a caller of 129<code>{@link android.content.Context#startService startService()}</code>, 130<code>{@link android.content.Context#bindService bindService()}</code>, or 131<code>{@link android.content.Context#stopService stopService()}</code>, 132has not been granted this permission, the method will not work and the 133Intent object will not be delivered to the service. 134 135<p> 136If this attribute is not set, the permission set by the 137<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 138<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> 139attribute applies to the service. If neither attribute is set, the service is 140not protected by a permission. 141</p> 142 143<p> 144For more information on permissions, see the 145<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> 146section in the introduction and a separate document, 147<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. 148</p></dd> 149 150<dt><a name="proc"></a>{@code android:process}</dt> 151<dd>The name of the process where the service is to run. Normally, 152all components of an application run in the default process created for the 153application. It has the same name as the application package. The 154<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 155<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> 156attribute can set a different 157default for all components. But component can override the default 158with its own {@code process} attribute, allowing you to spread your 159application across multiple processes. 160 161<p> 162If the name assigned to this attribute begins with a colon (':'), a new 163process, private to the application, is created when it's needed and 164the service runs in that process. 165If the process name begins with a lowercase character, the service will run 166in a global process of that name, provided that it has permission to do so. 167This allows components in different applications to share a process, reducing 168resource usage. 169</p></dd> 170</dl></dd> 171 172<dt>see also:</dt> 173<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 174<br><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code></dd> 175 176<!-- ##api level indication## --> 177<dt>introduced in:</dt> 178<dd>API Level 1</dd> 179 180</dl> 181