1 page.title=<provider> 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> 9 <pre class="stx"> 10 <provider android:<a href="#auth">authorities</a>="<i>list</i>" 11 android:<a href="#enabled">enabled</a>=["true" | "false"] 12 android:<a href="#exported">exported</a>=["true" | "false"] 13 android:<a href="#gprmsn">grantUriPermissions</a>=["true" | "false"] 14 android:<a href="#icon">icon</a>="<i>drawable resource</i>" 15 android:<a href="#init">initOrder</a>="<i>integer</i>" 16 android:<a href="#label">label</a>="<i>string resource</i>" 17 android:<a href="#multi">multiprocess</a>=["true" | "false"] 18 android:<a href="#nm">name</a>="<i>string</i>" 19 android:<a href="#prmsn">permission</a>="<i>string</i>" 20 android:<a href="#proc">process</a>="<i>string</i>" 21 android:<a href="#rprmsn">readPermission</a>="<i>string</i>" 22 android:<a href="#sync">syncable</a>=["true" | "false"] 23 android:<a href="#wprmsn">writePermission</a>="<i>string</i>" > 24 . . . 25 </provider></pre> 26 </dd> 27 28 <dt>contained in:</dt> 29 <dd> 30 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 31 </dd> 32 33 <dt>can contain:</dt> 34 <dd><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> 35 <br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> 36 <br/><code><a href="{@docRoot}guide/topics/manifest/path-permission-element.html"><path-permission></a></code></dd> 37 38 <dt>description:</dt> 39 <dd> 40 Declares a content provider component. A content provider is a subclass of 41 {@link android.content.ContentProvider} that supplies structured access to data managed by the 42 application. All content providers in your application must be defined in a 43 {@code <provider>} element in the manifest file; otherwise, the system is unaware of them 44 and doesn't run them. 45 <p> 46 You only declare content providers that are part of your application. Content providers in 47 other applications that you use in your application should not be declared. 48 </p> 49 <p> 50 The Android system stores references to content providers according to an <b>authority</b> 51 string, part of the provider's <b>content URI</b>. For example, suppose you want to 52 access a content provider that stores information about health care professionals. To do 53 this, you call the method 54 {@link android.content.ContentResolver#query ContentResolver.query()}, which among other 55 arguments takes a URI that identifies the provider: 56 </p> 57 <pre> 58 content://com.example.project.healthcareprovider/nurses/rn 59 </pre> 60 <p> 61 The <code>content:</code> <b>scheme</b> identifies the URI as a content URI pointing to 62 an Android content provider. The authority 63 <code>com.example.project.healthcareprovider</code> identifies the provider itself; the 64 Android system looks up the authority in its list of known providers and their authorities. 65 The substring <code>nurses/rn</code> is a <b>path</b>, which the content provider can use 66 to identify subsets of the provider data. 67 </p> 68 <p> 69 Notice that when you define your provider in the <code><provider></code> element, you 70 don't include the scheme or the path in the <code>android:name</code> argument, only the 71 authority. 72 </p> 73 <p> 74 For information on using and developing content providers, see the API Guide, 75 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. 76 </p> 77 </dd> 78 79 <dt>attributes:</dt> 80 <dd> 81 <dl class="attr"> 82 <dt><a name="auth"></a>{@code android:authorities}</dt> 83 <dd> 84 A list of one or more URI authorities that identify data offered by the content provider. 85 Multiple authorities are listed by separating their names with a semicolon. 86 To avoid conflicts, authority names should use a Java-style naming convention 87 (such as {@code com.example.provider.cartoonprovider}). Typically, it's the name 88 of the {@link android.content.ContentProvider} subclass that implements the provider 89 <p> 90 There is no default. At least one authority must be specified. 91 </p> 92 </dd> 93 94 <dt><a name="enabled"></a>{@code android:enabled}</dt> 95 <dd>Whether or not the content provider can be instantiated by the system — 96 "{@code true}" if it can be, and "{@code false}" if not. The default value 97 is "{@code true}". 98 99 <p> 100 The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own 101 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all 102 application components, including content providers. The 103 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <provider>} 104 attributes must both be "{@code true}" (as they both 105 are by default) for the content provider to be enabled. If either is 106 "{@code false}", the provider is disabled; it cannot be instantiated. 107 </p></dd> 108 109 <dt><a name="exported"></a>{@code android:exported}</dt> 110 <dd> 111 Whether the content provider is available for other applications to use: 112 <ul> 113 <li> 114 <code>true</code>: The provider is available to other applications. Any application can 115 use the provider's content URI to access it, subject to the permissions specified for 116 the provider. 117 </li> 118 <li> 119 <code>false</code>: The provider is not available to other applications. Set 120 <code>android:exported="false"</code> to limit access to the provider to your 121 applications. Only applications that have the same user ID (UID) as the provider will 122 have access to it. 123 </li> 124 </ul> 125 <p> 126 The default value is <code>"true"</code> for applications that set either 127 <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">android:minSdkVersion</a></code> 128 or 129 <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">android:targetSdkVersion</a></code> to 130 <code>"16"</code> or lower. For applications that 131 set either of these attributes to <code>"17"</code> or higher, the default is 132 <code>"false"</code>. 133 </p> 134 <p> 135 You can set <code>android:exported="false"</code> and still limit access to your 136 provider by setting permissions with the 137 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> 138 attribute. 139 </p> 140 </dd> 141 142 <dt><a name="gprmsn"></a>{@code android:grantUriPermissions}</dt> 143 <dd>Whether or not those who ordinarily would not have permission to 144 access the content provider's data can be granted permission to do so, 145 temporarily overcoming the restriction imposed by the 146 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code>, 147 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">writePermission</a></code>, and 148 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attributes 149 — 150 "{@code true}" if permission can be granted, and "{@code false}" if not. 151 If "{@code true}", permission can be granted to any of the content 152 provider's data. If "{@code false}", permission can be granted only 153 to the data subsets listed in 154 <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> subelements, 155 if any. The default value is "{@code false}". 156 157 <p> 158 Granting permission is a way of giving an application component one-time 159 access to data protected by a permission. For example, when an e-mail 160 message contains an attachment, the mail application may call upon the 161 appropriate viewer to open it, even though the viewer doesn't have general 162 permission to look at all the content provider's data. 163 </p> 164 165 <p> 166 In such cases, permission is granted by 167 <code>{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}</code> 168 and <code>{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}</code> 169 flags in the Intent object that activates the component. For example, the 170 mail application might put {@code FLAG_GRANT_READ_URI_PERMISSION} in the 171 Intent passed to {@code Context.startActivity()}. The permission is specific 172 to the URI in the Intent. 173 </p> 174 175 <p> 176 If you enable this feature, either by setting this attribute to "{@code true}" 177 or by defining <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> 178 subelements, you must call 179 <code>{@link android.content.Context#revokeUriPermission 180 Context.revokeUriPermission()}</code> when a covered URI is deleted from 181 the provider. 182 </p> 183 184 <p> 185 See also the <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> 186 element. 187 </p></dd> 188 189 <dt><a name="icon"></a>{@code android:icon}</dt> 190 <dd>An icon representing the content provider. 191 This attribute must be set as a reference to a drawable resource containing 192 the image definition. If it is not set, the icon specified for the application 193 as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 194 element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).</dd> 195 196 <dt><a name="init"></a>{@code android:initOrder}</dt> 197 <dd>The order in which the content provider should be instantiated, 198 relative to other content providers hosted by the same process. 199 When there are dependencies among content providers, setting this 200 attribute for each of them ensures that they are created in the order 201 required by those dependencies. The value is a simple integer, 202 with higher numbers being initialized first.</dd> 203 204 <dt><a name="label"></a>{@code android:label}</dt> 205 <dd>A user-readable label for the content provided. 206 If this attribute is not set, the label set for the application as a whole is 207 used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 208 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). 209 210 <p> 211 The label should be set as a reference to a string resource, so that 212 it can be localized like other strings in the user interface. 213 However, as a convenience while you're developing the application, 214 it can also be set as a raw string. 215 </p></dd> 216 217 <dt><a name="multi"></a>{@code android:multiprocess}</dt> 218 <dd>Whether or not an instance of the content provider can be created in 219 every client process — "{@code true}" if instances can run in multiple 220 processes, and "{@code false}" if not. The default value is "{@code false}". 221 222 <p> 223 Normally, a content provider is instantiated in the process of the 224 application that defined it. However, if this flag is set to "{@code true}", 225 the system can create an instance in every process where there's a client 226 that wants to interact with it, thus avoiding the overhead of interprocess 227 communication. 228 </p></dd> 229 230 <dt><a name="nm"></a>{@code android:name}</dt> 231 <dd>The name of the class that implements the content provider, a subclass of 232 {@link android.content.ContentProvider}. This should be a fully qualified 233 class name (such as, "{@code com.example.project.TransportationProvider}"). 234 However, as a shorthand, if the first character of the name is a period, 235 it is appended to the package name specified in the 236 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. 237 238 <p> 239 There is no default. The name must be specified. 240 </p></dd> 241 242 243 <dt><a name="prmsn"></a>{@code android:permission}</dt> 244 <dd>The name of a permission that clients must have to read or write the 245 content provider's data. This attribute is a convenient way of setting a 246 single permission for both reading and writing. However, the 247 <code><a href="#rprmsn">readPermission</a></code> and 248 <code><a href="#wprmsn">writePermission</a></code> attributes take precedence 249 over this one. If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code> 250 attribute is also set, it controls access for querying the content provider. 251 And if the <code><a href="#wprmsn">writePermission</a></code> attribute is set, 252 it controls access for modifying the provider's data. 253 254 <p> 255 For more information on permissions, see the 256 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> 257 section in the introduction and a separate document, 258 <a href="{@docRoot}guide/topics/security/security.html">Security and 259 Permissions</a>. 260 </p></dd> 261 262 <dt><a name="proc"></a>{@code android:process}</dt> 263 <dd>The name of the process in which the content provider should run. Normally, 264 all components of an application run in the default process created for the 265 application. It has the same name as the application package. The 266 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 267 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> 268 attribute can set a different 269 default for all components. But each component can override the default 270 with its own {@code process} attribute, allowing you to spread your 271 application across multiple processes. 272 273 <p> 274 If the name assigned to this attribute begins with a colon (':'), a new 275 process, private to the application, is created when it's needed and 276 the activity runs in that process. 277 If the process name begins with a lowercase character, the activity will run 278 in a global process of that name, provided that it has permission to do so. 279 This allows components in different applications to share a process, reducing 280 resource usage. 281 </p></dd> 282 283 <dt><a name="rprmsn"></a>{@code android:readPermission}</dt> 284 <dd>A permission that clients must have to query the content provider. 285 See also the <code><a href="#prmsn">permission</a></code> and 286 <code><a href="#wprmsn">writePermission</a></code> attributes.</dd> 287 288 <dt><a name="sync"></a>{@code android:syncable}</dt> 289 <dd>Whether or not the data under the content provider's control 290 is to be synchronized with data on a server — "{@code true}" 291 if it is to be synchronized, and "{@code false}" if not.</dd> 292 293 <dt><a name="wprmsn"></a>{@code android:writePermission}</dt> 294 <dd>A permission that clients must have to make changes to the data 295 controlled by the content provider. 296 See also the <code><a href="#prmsn">permission</a></code> and 297 <code><a href="#rprmsn">readPermission</a></code> attributes.</dd> 298 299 </dl></dd> 300 301 <!-- ##api level indication## --> 302 <dt>introduced in:</dt> 303 <dd>API Level 1</dd> 304 305 <dt>see also:</dt> 306 <dd><a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a></dd> 307 308 </dl> 309