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