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