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