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