Home | History | Annotate | Download | only in providers
      1 page.title=Creating a Content Provider
      2 @jd:body
      3 <div id="qv-wrapper">
      4 <div id="qv">
      5 
      6 
      7 <h2>In this document</h2>
      8 <ol>
      9     <li>
     10         <a href="#DataStorage">Designing Data Storage</a>
     11     </li>
     12     <li>
     13         <a href="#ContentURI">Designing Content URIs</a>
     14     </li>
     15     <li>
     16         <a href="#ContentProvider">Implementing the ContentProvider Class</a>
     17         <ol>
     18             <li>
     19                 <a href="#RequiredAccess">Required Methods</a>
     20             </li>
     21             <li>
     22                 <a href="#Query">Implementing the query() method</a>
     23             </li>
     24             <li>
     25                 <a href="#Insert">Implementing the insert() method</a>
     26             </li>
     27             <li>
     28                 <a href="#Delete">Implementing the delete() method</a>
     29             </li>
     30             <li>
     31                 <a href="#Update">Implementing the update() method</a>
     32             </li>
     33             <li>
     34                 <a href="#OnCreate">Implementing the onCreate() method</a>
     35             </li>
     36         </ol>
     37     </li>
     38     <li>
     39         <a href="#MIMETypes">Implementing Content Provider MIME Types</a>
     40         <ol>
     41             <li>
     42                 <a href="#TableMIMETypes">MIME types for tables</a>
     43             </li>
     44             <li>
     45                 <a href="#FileMIMETypes">MIME types for files</a>
     46             </li>
     47         </ol>
     48     </li>
     49     <li>
     50         <a href="#ContractClass">Implementing a Contract Class</a>
     51     </li>
     52     <li>
     53         <a href="#Permissions">Implementing Content Provider Permissions</a>
     54     </li>
     55     <li>
     56         <a href="#ProviderElement">The &lt;provider&gt; Element</a>
     57     </li>
     58     <li>
     59         <a href="#Intents">Intents and Data Access</a>
     60     </li>
     61 </ol>
     62 <h2>Key classes</h2>
     63     <ol>
     64         <li>
     65             {@link android.content.ContentProvider}
     66         </li>
     67         <li>
     68             {@link android.database.Cursor}
     69         </li>
     70         <li>
     71             {@link android.net.Uri}
     72         </li>
     73     </ol>
     74 <h2>Related Samples</h2>
     75     <ol>
     76         <li>
     77             <a
     78                 href="{@docRoot}resources/samples/NotePad/index.html">
     79                 Note Pad sample application
     80             </a>
     81         </li>
     82     </ol>
     83 <h2>See also</h2>
     84     <ol>
     85         <li>
     86             <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
     87             Content Provider Basics</a>
     88         </li>
     89         <li>
     90             <a href="{@docRoot}guide/topics/providers/calendar-provider.html">
     91             Calendar Provider</a>
     92         </li>
     93     </ol>
     94 </div>
     95 </div>
     96 
     97 
     98 <p>
     99     A content provider manages access to a central repository of data. You implement a
    100     provider as one or more classes in an Android application, along with elements in
    101     the manifest file. One of your classes implements a subclass
    102     {@link android.content.ContentProvider}, which is the interface between your provider and
    103     other applications. Although content providers are meant to make data available to other
    104     applications, you may of course have activities in your application that allow the user
    105     to query and modify the data managed by your provider.
    106 </p>
    107 <p>
    108     The rest of this topic is a basic list of steps for building a content provider and a list
    109     of APIs to use.
    110 </p>
    111 
    112 
    113 <!-- Before You Start Building -->
    114 <h2 id="BeforeYouStart">Before You Start Building</h2>
    115 <p>
    116     Before you start building a provider, do the following:
    117 </p>
    118 <ol>
    119     <li>
    120         <strong>Decide if you need a content provider</strong>. You need to build a content
    121         provider if you want to provide one or more of the following features:
    122         <ul>
    123             <li>You want to offer complex data or files to other applications.</li>
    124             <li>You want to allow users to copy complex data from your app into other apps.</li>
    125             <li>You want to provide custom search suggestions using the search framework.</li>
    126         </ul>
    127     <p>
    128         You <em>don't</em> need a provider to use an SQLite database if the use is entirely within
    129         your own application.
    130     </p>
    131     </li>
    132     <li>
    133         If you haven't done so already, read the topic
    134         <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
    135         Content Provider Basics</a> to learn more about providers.
    136     </li>
    137 </ol>
    138 <p>
    139     Next, follow these steps to build your provider:
    140 </p>
    141 <ol>
    142     <li>
    143         Design the raw storage for your data. A content provider offers data in two ways:
    144         <dl>
    145             <dt>
    146                 File data
    147             </dt>
    148             <dd>
    149                 Data that normally goes into files, such as
    150                 photos, audio, or videos. Store the files in your application's private
    151                 space. In response to a request for a file from another application, your
    152                 provider can offer a handle to the file.
    153             </dd>
    154             <dt>
    155                 &quot;Structured&quot; data
    156             </dt>
    157             <dd>
    158                 Data that normally goes into a database, array, or similar structure.
    159                 Store the data in a form that's compatible with tables of rows and columns. A row
    160                 represents an entity, such as a person or an item in inventory. A column represents
    161                 some data for the entity, such a person's name or an item's price. A common way to
    162                 store this type of data is in an SQLite database, but you can use any type of
    163                 persistent storage. To learn more about the storage types available in the
    164                 Android system, see the section <a href="#DataStorage">
    165                 Designing Data Storage</a>.
    166             </dd>
    167         </dl>
    168     </li>
    169     <li>
    170         Define a concrete implementation of the {@link android.content.ContentProvider} class and
    171         its required methods. This class is the interface between your data and the rest of the
    172         Android system. For more information about this class, see the section
    173         <a href="#ContentProvider">Implementing the ContentProvider Class</a>.
    174     </li>
    175     <li>
    176         Define the provider's authority string, its content URIs, and column names. If you want
    177         the provider's application to handle intents, also define intent actions, extras data,
    178         and flags. Also define the permissions that you will require for applications that want
    179         to access your data. You should consider defining all of these values as constants in a
    180         separate contract class; later, you can expose this class to other developers. For more
    181         information about content URIs, see the
    182         section <a href="#ContentURI">Designing Content URIs</a>.
    183         For more information about intents, see the
    184         section <a href="#Intents">Intents and Data Access</a>.
    185     </li>
    186     <li>
    187         Add other optional pieces, such as sample data or an implementation
    188         of {@link android.content.AbstractThreadedSyncAdapter} that can synchronize data between
    189         the provider and cloud-based data.
    190     </li>
    191 </ol>
    192 
    193 
    194 <!-- Designing Data Storage -->
    195 <h2 id="DataStorage">Designing Data Storage</h2>
    196 <p>
    197     A content provider is the interface to data saved in a structured format. Before you create
    198     the interface, you must decide how to store the data. You can store the data in any form you
    199     like, and then design the interface to read and write the data as necessary.
    200 </p>
    201 <p>
    202     These are some of the data storage technologies that are available in Android:
    203 </p>
    204 <ul>
    205     <li>
    206         The Android system includes an SQLite database API that Android's own providers use
    207         to store table-oriented data. The
    208         {@link android.database.sqlite.SQLiteOpenHelper} class helps you create databases, and the
    209         {@link android.database.sqlite.SQLiteDatabase} class is the base class for accessing
    210         databases.
    211         <p>
    212             Remember that you don't have to use a database to implement your repository. A provider
    213             appears externally as a set of tables, similar to a relational database, but this is
    214             not a requirement for the provider's internal implementation.
    215         </p>
    216     </li>
    217     <li>
    218         For storing file data, Android has a variety of file-oriented APIs.
    219         To learn more about file storage, read the topic
    220         <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a>. If you're
    221         designing a provider that offers media-related data such as music or videos, you can
    222         have a provider that combines table data and files.
    223     </li>
    224     <li>
    225         For working with network-based data, use classes in {@link java.net} and
    226         {@link android.net}. You can also synchronize network-based data to a local data
    227         store such as a database, and then offer the data as tables or files.
    228         The <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">
    229         Sample Sync Adapter</a> sample application demonstrates this type of synchronization.
    230     </li>
    231 </ul>
    232 <h3 id="DataDesign">
    233     Data design considerations
    234 </h3>
    235 <p>
    236     Here are some tips for designing your provider's data structure:
    237 </p>
    238 <ul>
    239     <li>
    240         Table data should always have a &quot;primary key&quot; column that the provider maintains
    241         as a unique numeric value for each row. You can use this value to link the row to related
    242         rows in other tables (using it as a &quot;foreign key&quot;). Although you can use any name
    243         for this column, using {@link android.provider.BaseColumns#_ID BaseColumns._ID} is the best
    244         choice, because linking the results of a provider query to a
    245         {@link android.widget.ListView} requires one of the retrieved columns to have the name
    246         <code>_ID</code>.
    247     </li>
    248     <li>
    249         If you want to provide bitmap images or other very large pieces of file-oriented data, store
    250         the data in a file and then provide it indirectly rather than storing it directly in a
    251         table. If you do this, you need to tell users of your provider that they need to use a
    252         {@link android.content.ContentResolver} file method to access the data.
    253     </li>
    254     <li>
    255         Use the Binary Large OBject (BLOB) data type to store data that varies in size or has a
    256         varying structure. For example, you can use a BLOB column to store a
    257         <a href="http://code.google.com/p/protobuf">protocol buffer</a> or
    258         <a href="http://www.json.org">JSON structure</a>.
    259         <p>
    260             You can also use a BLOB to implement a <em>schema-independent</em> table. In
    261             this type of table, you define a primary key column, a MIME type column, and one or
    262             more generic columns as BLOB. The meaning of the data in the BLOB columns is indicated
    263             by the value in the MIME type column. This allows you to store different row types in
    264             the same table. The Contacts Provider's &quot;data&quot; table
    265             {@link android.provider.ContactsContract.Data} is an example of a schema-independent
    266             table.
    267         </p>
    268     </li>
    269 </ul>
    270 <!-- Designing Content URIs -->
    271 <h2 id="ContentURI">Designing Content URIs</h2>
    272 <p>
    273     A <strong>content URI</strong> is a URI that identifies data in a provider. Content URIs include
    274     the symbolic name of the entire provider (its <strong>authority</strong>) and a
    275     name that points to a table or file (a <strong>path</strong>). The optional id part points to
    276     an individual row in a table. Every data access method of
    277     {@link android.content.ContentProvider} has a content URI as an argument; this allows you to
    278     determine the table, row, or file to access.
    279 </p>
    280 <p>
    281     The basics of content URIs are described in the topic
    282     <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
    283     Content Provider Basics</a>.
    284 </p>
    285 <h3>Designing an authority</h3>
    286 <p>
    287     A provider usually has a single authority, which serves as its Android-internal name. To
    288     avoid conflicts with other providers, you should use Internet domain ownership (in reverse)
    289     as the basis of your provider authority. Because this recommendation is also true for Android
    290     package names, you can define your provider authority as an extension of the name
    291     of the package containing the provider. For example, if your Android package name is
    292     <code>com.example.&lt;appname&gt;</code>, you should give your provider the
    293     authority <code>com.example.&lt;appname&gt;.provider</code>.
    294 </p>
    295 <h3>Designing a path structure</h3>
    296 <p>
    297     Developers usually create content URIs from the authority by appending paths that point to
    298     individual tables. For example, if you have two tables <em>table1</em> and
    299     <em>table2</em>, you combine the authority from the previous example to yield the
    300     content URIs
    301     <code>com.example.&lt;appname&gt;.provider/table1</code> and
    302     <code>com.example.&lt;appname&gt;.provider/table2</code>. Paths aren't
    303     limited to a single segment, and there doesn't have to be a table for each level of the path.
    304 </p>
    305 <h3>Handling content URI IDs</h3>
    306 <p>
    307     By convention, providers offer access to a single row in a table by accepting a content URI
    308     with an ID value for the row at the end of the URI. Also by convention, providers match the
    309     ID value to the table's <code>_ID</code> column, and perform the requested access against the
    310     row that matches.
    311 </p>
    312 <p>
    313     This convention facilitates a common design pattern for apps accessing a provider. The app
    314     does a query against the provider and displays the resulting {@link android.database.Cursor}
    315     in a {@link android.widget.ListView} using a {@link android.widget.CursorAdapter}.
    316     The definition of {@link android.widget.CursorAdapter} requires one of the columns in the
    317     {@link android.database.Cursor} to be <code>_ID</code>
    318 </p>
    319 <p>
    320     The user then picks one of the displayed rows from the UI in order to look at or modify the
    321     data. The app gets the corresponding row from the {@link android.database.Cursor} backing the
    322     {@link android.widget.ListView}, gets the <code>_ID</code> value for this row, appends it to
    323     the content URI, and sends the access request to the provider. The provider can then do the
    324     query or modification against the exact row the user picked.
    325 </p>
    326 <h3>Content URI patterns</h3>
    327 <p>
    328     To help you choose which action to take for an incoming content URI, the provider API includes
    329     the convenience class {@link android.content.UriMatcher}, which maps content URI "patterns" to
    330     integer values. You can use the integer values in a <code>switch</code> statement that
    331     chooses the desired action for the content URI or URIs that match a particular pattern.
    332 </p>
    333 <p>
    334     A content URI pattern matches content URIs using wildcard characters:
    335 </p>
    336     <ul>
    337         <li>
    338             <strong><code>*</code>:</strong> Matches a string of any valid characters of any length.
    339         </li>
    340         <li>
    341             <strong><code>#</code>:</strong> Matches a string of numeric characters of any length.
    342         </li>
    343     </ul>
    344 <p>
    345     As an example of designing and coding content URI handling, consider a provider with the
    346     authority <code>com.example.app.provider</code> that recognizes the following content URIs
    347     pointing to tables:
    348 </p>
    349 <ul>
    350     <li>
    351         <code>content://com.example.app.provider/table1</code>: A table called <code>table1</code>.
    352     </li>
    353     <li>
    354         <code>content://com.example.app.provider/table2/dataset1</code>: A table called
    355         <code>dataset1</code>.
    356     </li>
    357     <li>
    358         <code>content://com.example.app.provider/table2/dataset2</code>: A table called
    359         <code>dataset2</code>.
    360     </li>
    361     <li>
    362         <code>content://com.example.app.provider/table3</code>: A table called <code>table3</code>.
    363     </li>
    364 </ul>
    365 <p>
    366     The provider also recognizes these content URIs if they have a row ID appended to them, as
    367     for example <code>content://com.example.app.provider/table3/1</code> for the row identified by
    368     <code>1</code> in <code>table3</code>.
    369 </p>
    370 <p>
    371     The following content URI patterns would be possible:
    372 </p>
    373 <dl>
    374     <dt>
    375         <code>content://com.example.app.provider/*</code>
    376     </dt>
    377     <dd>
    378         Matches any content URI in the provider.
    379     </dd>
    380     <dt>
    381         <code>content://com.example.app.provider/table2/*</code>:
    382     </dt>
    383     <dd>
    384         Matches a content URI for the tables <code>dataset1</code>
    385         and <code>dataset2</code>, but doesn't match content URIs for <code>table1</code> or
    386         <code>table3</code>.
    387     </dd>
    388     <dt>
    389         <code>content://com.example.app.provider/table3/#</code>: Matches a content URI
    390         for single rows in <code>table3</code>, such as
    391         <code>content://com.example.app.provider/table3/6</code> for the row identified by
    392         <code>6</code>.
    393     </dt>
    394 </dl>
    395 <p>
    396     The following code snippet shows how the methods in {@link android.content.UriMatcher} work.
    397     This code handles URIs for an entire table differently from URIs for a
    398     single row, by using the content URI pattern
    399     <code>content://&lt;authority&gt;/&lt;path&gt;</code> for tables, and
    400     <code>content://&lt;authority&gt;/&lt;path&gt;/&lt;id&gt;</code> for single rows.
    401 </p>
    402 <p>
    403     The method {@link android.content.UriMatcher#addURI(String, String, int) addURI()} maps an
    404     authority and path to an integer value. The method {@link android.content.UriMatcher#match(Uri)
    405     match()} returns the integer value for a URI. A <code>switch</code> statement
    406     chooses between querying the entire table, and querying for a single record:
    407 </p>
    408 <pre class="prettyprint">
    409 public class ExampleProvider extends ContentProvider {
    410 ...
    411     // Creates a UriMatcher object.
    412     private static final UriMatcher sUriMatcher;
    413 ...
    414     /*
    415      * The calls to addURI() go here, for all of the content URI patterns that the provider
    416      * should recognize. For this snippet, only the calls for table 3 are shown.
    417      */
    418 ...
    419     /*
    420      * Sets the integer value for multiple rows in table 3 to 1. Notice that no wildcard is used
    421      * in the path
    422      */
    423     sUriMatcher.addURI("com.example.app.provider", "table3", 1);
    424 
    425     /*
    426      * Sets the code for a single row to 2. In this case, the "#" wildcard is
    427      * used. "content://com.example.app.provider/table3/3" matches, but
    428      * "content://com.example.app.provider/table3 doesn't.
    429      */
    430     sUriMatcher.addURI("com.example.app.provider", "table3/#", 2);
    431 ...
    432     // Implements ContentProvider.query()
    433     public Cursor query(
    434         Uri uri,
    435         String[] projection,
    436         String selection,
    437         String[] selectionArgs,
    438         String sortOrder) {
    439 ...
    440         /*
    441          * Choose the table to query and a sort order based on the code returned for the incoming
    442          * URI. Here, too, only the statements for table 3 are shown.
    443          */
    444         switch (sUriMatcher.match(uri)) {
    445 
    446 
    447             // If the incoming URI was for all of table3
    448             case 1:
    449 
    450                 if (TextUtils.isEmpty(sortOrder)) sortOrder = "_ID ASC";
    451                 break;
    452 
    453             // If the incoming URI was for a single row
    454             case 2:
    455 
    456                 /*
    457                  * Because this URI was for a single row, the _ID value part is
    458                  * present. Get the last path segment from the URI; this is the _ID value.
    459                  * Then, append the value to the WHERE clause for the query
    460                  */
    461                 selection = selection + "_ID = " uri.getLastPathSegment();
    462                 break;
    463 
    464             default:
    465             ...
    466                 // If the URI is not recognized, you should do some error handling here.
    467         }
    468         // call the code to actually do the query
    469     }
    470 </pre>
    471 <p>
    472     Another class, {@link android.content.ContentUris}, provides convenience methods for working
    473     with the <code>id</code> part of content URIs. The classes {@link android.net.Uri} and
    474     {@link android.net.Uri.Builder} include convenience methods for parsing existing
    475     {@link android.net.Uri} objects and building new ones.
    476 </p>
    477 
    478 <!-- Implementing the ContentProvider class -->
    479 <h2 id="ContentProvider">Implementing the ContentProvider Class</h2>
    480 <p>
    481     The {@link android.content.ContentProvider} instance manages access
    482     to a structured set of data by handling requests from other applications. All forms
    483     of access eventually call {@link android.content.ContentResolver}, which then calls a concrete
    484     method of {@link android.content.ContentProvider} to get access.
    485 </p>
    486 <h3 id="RequiredAccess">Required methods</h3>
    487 <p>
    488     The abstract class {@link android.content.ContentProvider} defines six abstract methods that
    489     you must implement as part of your own concrete subclass. All of these methods except
    490     {@link android.content.ContentProvider#onCreate() onCreate()} are called by a client application
    491     that is attempting to access your content provider:
    492 </p>
    493 <dl>
    494     <dt>
    495         {@link android.content.ContentProvider#query(Uri, String[], String, String[], String)
    496         query()}
    497     </dt>
    498     <dd>
    499         Retrieve data from your provider. Use the arguments to select the table to
    500         query, the rows and columns to return, and the sort order of the result.
    501         Return the data as a {@link android.database.Cursor} object.
    502     </dd>
    503     <dt>
    504         {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()}
    505     </dt>
    506     <dd>
    507         Insert a new row into your provider. Use the arguments to select the
    508         destination table and to get the column values to use. Return a content URI for the
    509         newly-inserted row.
    510     </dd>
    511     <dt>
    512         {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[])
    513         update()}
    514     </dt>
    515     <dd>
    516         Update existing rows in your provider. Use the arguments to select the table and rows
    517         to update and to get the updated column values. Return the number of rows updated.
    518     </dd>
    519     <dt>
    520         {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()}
    521     </dt>
    522     <dd>
    523         Delete rows from your provider. Use the arguments to select the table and the rows to
    524         delete. Return the number of rows deleted.
    525     </dd>
    526     <dt>
    527         {@link android.content.ContentProvider#getType(Uri) getType()}
    528     </dt>
    529     <dd>
    530         Return the MIME type corresponding to a content URI. This method is described in more
    531         detail in the section <a href="#MIMETypes">Implementing Content Provider MIME Types</a>.
    532     </dd>
    533     <dt>
    534         {@link android.content.ContentProvider#onCreate() onCreate()}
    535     </dt>
    536     <dd>
    537         Initialize your provider. The Android system calls this method immediately after it
    538         creates your provider. Notice that your provider is not created until a
    539         {@link android.content.ContentResolver} object tries to access it.
    540     </dd>
    541 </dl>
    542 <p>
    543     Notice that these methods have the same signature as the identically-named
    544     {@link android.content.ContentResolver} methods.
    545 </p>
    546 <p>
    547     Your implementation of these methods should account for the following:
    548 </p>
    549 <ul>
    550     <li>
    551         All of these methods except {@link android.content.ContentProvider#onCreate() onCreate()}
    552         can be called by multiple threads at once, so they must be thread-safe. To learn
    553         more about multiple threads, see the topic
    554         <a href="{@docRoot}guide/components/processes-and-threads.html">
    555         Processes and Threads</a>.
    556     </li>
    557     <li>
    558         Avoid doing lengthy operations in {@link android.content.ContentProvider#onCreate()
    559         onCreate()}. Defer initialization tasks until they are actually needed.
    560         The section <a href="#OnCreate">Implementing the onCreate() method</a>
    561         discusses this in more detail.
    562     </li>
    563     <li>
    564         Although you must implement these methods, your code does not have to do anything except
    565         return the expected data type. For example, you may want to prevent other applications
    566         from inserting data into some tables. To do this, you can ignore the call to
    567         {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} and return
    568         0.
    569     </li>
    570 </ul>
    571 <h3 id="Query">Implementing the query() method</h3>
    572 <p>
    573     The
    574     {@link android.content.ContentProvider#query(Uri, String[], String, String[], String)
    575     ContentProvider.query()} method must return a {@link android.database.Cursor} object, or if it
    576     fails, throw an {@link java.lang.Exception}. If you are using an SQLite database as your data
    577     storage, you can simply return the {@link android.database.Cursor} returned by one of the
    578     <code>query()</code> methods of the {@link android.database.sqlite.SQLiteDatabase} class.
    579     If the query does not match any rows, you should return a {@link android.database.Cursor}
    580     instance whose {@link android.database.Cursor#getCount()} method returns 0.
    581     You should return <code>null</code> only if an internal error occurred during the query process.
    582 </p>
    583 <p>
    584     If you aren't using an SQLite database as your data storage, use one of the concrete subclasses
    585     of {@link android.database.Cursor}. For example, the {@link android.database.MatrixCursor} class
    586     implements a cursor in which each row is an array of {@link java.lang.Object}. With this class,
    587     use {@link android.database.MatrixCursor#addRow(Object[]) addRow()} to add a new row.
    588 </p>
    589 <p>
    590     Remember that the Android system must be able to communicate the {@link java.lang.Exception}
    591     across process boundaries. Android can do this for the following exceptions that may be useful
    592     in handling query errors:
    593 </p>
    594 <ul>
    595     <li>
    596         {@link java.lang.IllegalArgumentException} (You may choose to throw this if your provider
    597         receives an invalid content URI)
    598     </li>
    599     <li>
    600         {@link java.lang.NullPointerException}
    601     </li>
    602 </ul>
    603 <h3 id="Insert">Implementing the insert() method</h3>
    604 <p>
    605     The {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} method adds a
    606     new row to the appropriate table, using the values in the {@link android.content.ContentValues}
    607     argument. If a column name is not in the {@link android.content.ContentValues} argument, you
    608     may want to provide a default value for it either in your provider code or in your database
    609     schema.
    610 </p>
    611 <p>
    612     This method should return the content URI for the new row. To construct this, append the new
    613     row's <code>_ID</code> (or other primary key) value to the table's content URI, using
    614     {@link android.content.ContentUris#withAppendedId(Uri, long) withAppendedId()}.
    615 </p>
    616 <h3 id="Delete">Implementing the delete() method</h3>
    617 <p>
    618     The {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} method
    619     does not have to physically delete rows from your data storage. If you are using a sync adapter
    620     with your provider, you should consider marking a deleted row
    621     with a &quot;delete&quot; flag rather than removing the row entirely. The sync adapter can
    622     check for deleted rows and remove them from the server before deleting them from the provider.
    623 </p>
    624 <h3 id="Update">Implementing the update() method</h3>
    625 <p>
    626     The {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[])
    627     update()} method takes the same {@link android.content.ContentValues} argument used by
    628     {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()}, and the
    629     same <code>selection</code> and <code>selectionArgs</code> arguments used by
    630     {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} and
    631     {@link android.content.ContentProvider#query(Uri, String[], String, String[], String)
    632     ContentProvider.query()}. This may allow you to re-use code between these methods.
    633 </p>
    634 <h3 id="OnCreate">Implementing the onCreate() method</h3>
    635 <p>
    636     The Android system calls {@link android.content.ContentProvider#onCreate()
    637     onCreate()} when it starts up the provider. You should perform only fast-running initialization
    638     tasks in this method, and defer database creation and data loading until the provider actually
    639     receives a request for the data. If you do lengthy tasks in
    640     {@link android.content.ContentProvider#onCreate() onCreate()}, you will slow down your
    641     provider's startup. In turn, this will slow down the response from the provider to other
    642     applications.
    643 </p>
    644 <p>
    645     For example, if you are using an SQLite database you can create
    646     a new {@link android.database.sqlite.SQLiteOpenHelper} object in
    647     {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()},
    648     and then create the SQL tables the first time you open the database. To facilitate this, the
    649     first time you call {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase
    650     getWritableDatabase()}, it automatically calls the
    651     {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase)
    652     SQLiteOpenHelper.onCreate()} method.
    653 </p>
    654 <p>
    655     The following two snippets demonstrate the interaction between
    656     {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()} and
    657     {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase)
    658     SQLiteOpenHelper.onCreate()}. The first snippet is the implementation of
    659     {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}:
    660 </p>
    661 <pre class="prettyprint">
    662 public class ExampleProvider extends ContentProvider
    663 
    664     /*
    665      * Defines a handle to the database helper object. The MainDatabaseHelper class is defined
    666      * in a following snippet.
    667      */
    668     private MainDatabaseHelper mOpenHelper;
    669 
    670     // Defines the database name
    671     private static final String DBNAME = "mydb";
    672 
    673     // Holds the database object
    674     private SQLiteDatabase db;
    675 
    676     public boolean onCreate() {
    677 
    678         /*
    679          * Creates a new helper object. This method always returns quickly.
    680          * Notice that the database itself isn't created or opened
    681          * until SQLiteOpenHelper.getWritableDatabase is called
    682          */
    683         mOpenHelper = new SQLiteOpenHelper(
    684             getContext(),        // the application context
    685             DBNAME,              // the name of the database)
    686             null,                // uses the default SQLite cursor
    687             1                    // the version number
    688         );
    689 
    690         return true;
    691     }
    692 
    693     ...
    694 
    695     // Implements the provider's insert method
    696     public Cursor insert(Uri uri, ContentValues values) {
    697         // Insert code here to determine which table to open, handle error-checking, and so forth
    698 
    699         ...
    700 
    701         /*
    702          * Gets a writeable database. This will trigger its creation if it doesn't already exist.
    703          *
    704          */
    705         db = mOpenHelper.getWritableDatabase();
    706     }
    707 }
    708 </pre>
    709 <p>
    710     The next snippet is the implementation of
    711     {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase)
    712     SQLiteOpenHelper.onCreate()}, including a helper class:
    713 </p>
    714 <pre class="prettyprint">
    715 ...
    716 // A string that defines the SQL statement for creating a table
    717 private static final String SQL_CREATE_MAIN = "CREATE TABLE " +
    718     "main " +                       // Table's name
    719     "(" +                           // The columns in the table
    720     " _ID INTEGER PRIMARY KEY, " +
    721     " WORD TEXT"
    722     " FREQUENCY INTEGER " +
    723     " LOCALE TEXT )";
    724 ...
    725 /**
    726  * Helper class that actually creates and manages the provider's underlying data repository.
    727  */
    728 protected static final class MainDatabaseHelper extends SQLiteOpenHelper {
    729 
    730     /*
    731      * Instantiates an open helper for the provider's SQLite data repository
    732      * Do not do database creation and upgrade here.
    733      */
    734     MainDatabaseHelper(Context context) {
    735         super(context, DBNAME, null, 1);
    736     }
    737 
    738     /*
    739      * Creates the data repository. This is called when the provider attempts to open the
    740      * repository and SQLite reports that it doesn't exist.
    741      */
    742     public void onCreate(SQLiteDatabase db) {
    743 
    744         // Creates the main table
    745         db.execSQL(SQL_CREATE_MAIN);
    746     }
    747 }
    748 </pre>
    749 
    750 
    751 <!-- Implementing ContentProvider MIME Types -->
    752 <h2 id="MIMETypes">Implementing ContentProvider MIME Types</h2>
    753 <p>
    754     The {@link android.content.ContentProvider} class has two methods for returning MIME types:
    755 </p>
    756 <dl>
    757     <dt>
    758         {@link android.content.ContentProvider#getType(Uri) getType()}
    759     </dt>
    760     <dd>
    761         One of the required methods that you must implement for any provider.
    762     </dd>
    763     <dt>
    764         {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}
    765     </dt>
    766     <dd>
    767         A method that you're expected to implement if your provider offers files.
    768     </dd>
    769 </dl>
    770 <h3 id="TableMIMETypes">MIME types for tables</h3>
    771 <p>
    772     The {@link android.content.ContentProvider#getType(Uri) getType()} method returns a
    773     {@link java.lang.String} in MIME format that describes the type of data returned by the content
    774     URI argument. The {@link android.net.Uri} argument can be a pattern rather than a specific URI;
    775     in this case, you should return the type of data associated with content URIs that match the
    776     pattern.
    777 </p>
    778 <p>
    779     For common types of data such as as text, HTML, or JPEG,
    780     {@link android.content.ContentProvider#getType(Uri) getType()} should return the standard
    781     MIME type for that data. A full list of these standard types is available on the
    782     <a href="http://www.iana.org/assignments/media-types/index.htm">IANA MIME Media Types</a>
    783     website.
    784 </p>
    785 <p>
    786     For content URIs that point to a row or rows of table data,
    787     {@link android.content.ContentProvider#getType(Uri) getType()} should return
    788     a MIME type in Android's vendor-specific MIME format:
    789 </p>
    790 <ul>
    791     <li>
    792         Type part: <code>vnd</code>
    793     </li>
    794     <li>
    795         Subtype part:
    796         <ul>
    797             <li>
    798     If the URI pattern is for a single row: <code>android.cursor.<strong>item</strong>/</code>
    799             </li>
    800             <li>
    801     If the URI pattern is for more than one row: <code>android.cursor.<strong>dir</strong>/</code>
    802             </li>
    803         </ul>
    804     </li>
    805     <li>
    806         Provider-specific part: <code>vnd.&lt;name&gt;</code>.<code>&lt;type&gt;</code>
    807         <p>
    808             You supply the <code>&lt;name&gt;</code> and <code>&lt;type&gt;</code>.
    809             The <code>&lt;name&gt;</code> value should be globally unique,
    810             and the <code>&lt;type&gt;</code> value should be unique to the corresponding URI
    811             pattern. A good choice for <code>&lt;name&gt;</code> is your company's name or
    812             some part of your application's Android package name. A good choice for the
    813             <code>&lt;type&gt;</code> is a string that identifies the table associated with the
    814             URI.
    815         </p>
    816 
    817     </li>
    818 </ul>
    819 <p>
    820     For example, if a provider's authority is
    821     <code>com.example.app.provider</code>, and it exposes a table named
    822     <code>table1</code>, the MIME type for multiple rows in <code>table1</code> is:
    823 </p>
    824 <pre>
    825 vnd.android.cursor.<strong>dir</strong>/vnd.com.example.provider.table1
    826 </pre>
    827 <p>
    828     For a single row of <code>table1</code>, the MIME type is:
    829 </p>
    830 <pre>
    831 vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1
    832 </pre>
    833 <h3 id="FileMIMETypes">MIME types for files</h3>
    834 <p>
    835     If your provider offers files, implement
    836     {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}.
    837     The method returns a {@link java.lang.String} array of MIME types for the files your provider
    838     can return for a given content URI. You should filter the MIME types you offer by the MIME type
    839     filter argument, so that you return only those MIME types that the client wants to handle.
    840 </p>
    841 <p>
    842     For example, consider a provider that offers photo images as files in <code>.jpg</code>,
    843     <code>.png</code>, and <code>.gif</code> format.
    844     If an application calls {@link android.content.ContentResolver#getStreamTypes(Uri, String)
    845     ContentResolver.getStreamTypes()} with the filter string <code>image/*</code> (something that
    846     is an &quot;image&quot;),
    847     then the {@link android.content.ContentProvider#getStreamTypes(Uri, String)
    848     ContentProvider.getStreamTypes()} method should return the array:
    849 </p>
    850 <pre>
    851 { &quot;image/jpeg&quot;, &quot;image/png&quot;, &quot;image/gif&quot;}
    852 </pre>
    853 <p>
    854     If the app is only interested in <code>.jpg</code> files, then it can call
    855     {@link android.content.ContentResolver#getStreamTypes(Uri, String)
    856     ContentResolver.getStreamTypes()} with the filter string <code>*\/jpeg</code>, and
    857     {@link android.content.ContentProvider#getStreamTypes(Uri, String)
    858     ContentProvider.getStreamTypes()} should return:
    859 <pre>
    860 {&quot;image/jpeg&quot;}
    861 </pre>
    862 <p>
    863     If your provider doesn't offer any of the MIME types requested in the filter string,
    864     {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}
    865     should return <code>null</code>.
    866 </p>
    867 
    868 
    869 <!--  Implementing a Contract Class -->
    870 <h2 id="ContractClass">Implementing a Contract Class</h2>
    871 <p>
    872     A contract class is a <code>public final</code> class that contains constant definitions for the
    873     URIs, column names, MIME types, and other meta-data that pertain to the provider. The class
    874     establishes a contract between the provider and other applications by ensuring that the provider
    875     can be correctly accessed even if there are changes to the actual values of URIs, column names,
    876     and so forth.
    877 </p>
    878 <p>
    879     A contract class also helps developers because it usually has mnemonic names for its constants,
    880     so developers are less likely to use incorrect values for column names or URIs. Since it's a
    881     class, it can contain Javadoc documentation. Integrated development environments such as
    882     Eclipse can auto-complete constant names from the contract class and display Javadoc for the
    883     constants.
    884 </p>
    885 <p>
    886     Developers can't access the contract class's class file from your application, but they can
    887     statically compile it into their application from a <code>.jar</code> file you provide.
    888 </p>
    889 <p>
    890     The {@link android.provider.ContactsContract} class and its nested classes are examples of
    891     contract classes.
    892 </p>
    893 <h2 id="Permissions">Implementing Content Provider Permissions</h2>
    894 <p>
    895     Permissions and access for all aspects of the Android system are described in detail in the
    896     topic <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>.
    897     The topic <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a> also
    898     described the security and permissions in effect for various types of storage.
    899     In brief, the important points are:
    900 </p>
    901 <ul>
    902     <li>
    903         By default, data files stored on the device's internal storage are private to your
    904         application and provider.
    905     </li>
    906     <li>
    907         {@link android.database.sqlite.SQLiteDatabase} databases you create are private to your
    908         application and provider.
    909     </li>
    910     <li>
    911         By default, data files that you save to external storage are <em>public</em> and
    912         <em>world-readable</em>. You can't use a content provider to restrict access to files in
    913         external storage, because other applications can use other API calls to read and write them.
    914     </li>
    915     <li>
    916         The method calls for opening or creating files or SQLite databases on your device's internal
    917         storage can potentially give both read and write access to all other applications. If you
    918         use an internal file or database as your provider's repository, and you give it
    919         "world-readable" or "world-writeable" access, the permissions you set for your provider in
    920         its manifest won't protect your data. The default access for files and databases in
    921         internal storage is "private", and for your provider's repository you shouldn't change this.
    922     </li>
    923 </ul>
    924 <p>
    925     If you want to use content provider permissions to control access to your data, then you should
    926     store your data in internal files, SQLite databases, or the &quot;cloud&quot; (for example,
    927     on a remote server), and you should keep files and databases private to your application.
    928 </p>
    929 <h3>Implementing permissions</h3>
    930 <p>
    931     All applications can read from or write to your provider, even if the underlying data is
    932     private, because by default your provider does not have permissions set. To change this,
    933     set permissions for your provider in your manifest file, using attributes or child
    934     elements of the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
    935     &lt;provider&gt;</a></code> element. You can set permissions that apply to the entire provider,
    936     or to certain tables, or even to certain records, or all three.
    937 </p>
    938 <p>
    939     You define permissions for your provider with one or more
    940     <code><a href="{@docRoot}guide/topics/manifest/permission-element.html">
    941     &lt;permission&gt;</a></code> elements in your manifest file. To make the
    942     permission unique to your provider, use Java-style scoping for the
    943     <code><a href="{@docRoot}guide/topics/manifest/permission-element.html#nm">
    944     android:name</a></code> attribute. For example, name the read permission
    945     <code>com.example.app.provider.permission.READ_PROVIDER</code>.
    946 
    947 </p>
    948 <p>
    949     The following list describes the scope of provider permissions, starting with the
    950     permissions that apply to the entire provider and then becoming more fine-grained.
    951     More fine-grained permissions take precedence over ones with larger scope:
    952 </p>
    953 <dl>
    954     <dt>
    955         Single read-write provider-level permission
    956     </dt>
    957     <dd>
    958         One permission that controls both read and write access to the entire provider, specified
    959         with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">
    960         android:permission</a></code> attribute of the
    961         <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
    962         &lt;provider&gt;</a></code> element.
    963     </dd>
    964     <dt>
    965         Separate read and write provider-level permission
    966     </dt>
    967     <dd>
    968         A read permission and a write permission for the entire provider. You specify them
    969         with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">
    970         android:readPermission</a></code> and
    971         <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">
    972         android:writePermission</a></code> attributes of the
    973         <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
    974         &lt;provider&gt;</a></code> element. They take precedence over the permission required by
    975         <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">
    976         android:permission</a></code>.
    977     </dd>
    978     <dt>
    979         Path-level permission
    980     </dt>
    981     <dd>
    982         Read, write, or read/write permission for a content URI in your provider. You specify
    983         each URI you want to control with a
    984         <code><a href="{@docRoot}guide/topics/manifest/path-permission-element.html">
    985         &lt;path-permission&gt;</a></code> child element of the
    986         <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
    987         &lt;provider&gt;</a></code> element. For each content URI you specify, you can specify a
    988         read/write permission, a read permission, or a write permission, or all three. The read and
    989         write permissions take precedence over the read/write permission. Also, path-level
    990         permission takes precedence over provider-level permissions.
    991     </dd>
    992     <dt>
    993         Temporary permission
    994     </dt>
    995     <dd>
    996         A permission level that grants temporary access to an application, even if the application
    997         doesn't have the permissions that are normally required. The temporary
    998         access feature reduces the number of permissions an application has to request in
    999         its manifest. When you turn on temporary permissions, the only applications that need
   1000         &quot;permanent&quot; permissions for your provider are ones that continually access all
   1001         your data.
   1002         <p>
   1003             Consider the permissions you need to implement an email provider and app, when you
   1004             want to allow an outside image viewer application to display photo attachments from your
   1005             provider. To give the image viewer the necessary access without requiring permissions,
   1006             set up temporary permissions for content URIs for photos. Design your email app so
   1007             that when the user wants to display a photo, the app sends an intent containing the
   1008             photo's content URI and permission flags to the image viewer. The image viewer can
   1009             then query your email provider to retrieve the photo, even though the viewer doesn't
   1010             have the normal read permission for your provider.
   1011         </p>
   1012         <p>
   1013             To turn on temporary permissions, either set the
   1014             <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">
   1015             android:grantUriPermissions</a></code> attribute of the
   1016             <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
   1017             &lt;provider&gt;</a></code> element, or add one or more
   1018             <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">
   1019             &lt;grant-uri-permission&gt;</a></code> child elements to your
   1020             <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
   1021             &lt;provider&gt;</a></code> element. If you use temporary permissions, you have to call
   1022             {@link android.content.Context#revokeUriPermission(Uri, int)
   1023             Context.revokeUriPermission()} whenever you remove support for a content URI from your
   1024             provider, and the content URI is associated with a temporary permission.
   1025         </p>
   1026         <p>
   1027             The attribute's value determines how much of your provider is made accessible.
   1028             If the attribute is set to <code>true</code>, then the system will grant temporary
   1029             permission to your entire provider, overriding any other permissions that are required
   1030             by your provider-level or path-level permissions.
   1031         </p>
   1032         <p>
   1033             If this flag is set to <code>false</code>, then you must add
   1034             <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">
   1035             &lt;grant-uri-permission&gt;</a></code> child elements to your
   1036             <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
   1037             &lt;provider&gt;</a></code> element. Each child element specifies the content URI or
   1038             URIs for which temporary access is granted.
   1039         </p>
   1040         <p>
   1041             To delegate temporary access to an application, an intent must contain
   1042             the {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION} or the
   1043             {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION} flags, or both. These
   1044             are set with the {@link android.content.Intent#setFlags(int) setFlags()} method.
   1045         </p>
   1046         <p>
   1047             If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">
   1048             android:grantUriPermissions</a></code> attribute is not present, it's assumed to be
   1049             <code>false</code>.
   1050         </p>
   1051     </dd>
   1052 </dl>
   1053 
   1054 
   1055 
   1056 <!-- The Provider Element -->
   1057 <h2 id="ProviderElement">The &lt;provider&gt; Element</h2>
   1058 <p>
   1059     Like {@link android.app.Activity} and {@link android.app.Service} components,
   1060     a subclass of {@link android.content.ContentProvider}
   1061     must be defined in the manifest file for its application, using the
   1062     <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
   1063     &lt;provider&gt;</a></code> element. The Android system gets the following information from
   1064     the element:
   1065 <dl>
   1066     <dt>
   1067         Authority
   1068         (<a href="{@docRoot}guide/topics/manifest/provider-element.html#auth">{@code
   1069         android:authorities}</a>)
   1070     </dt>
   1071     <dd>
   1072         Symbolic names that identify the entire provider within the system. This
   1073         attribute is described in more detail in the section
   1074         <a href="#ContentURI">Designing Content URIs</a>.
   1075     </dd>
   1076     <dt>
   1077         Provider class name
   1078         (<code>
   1079 <a href="{@docRoot}guide/topics/manifest/provider-element.html#nm">android:name</a>
   1080         </code>)
   1081     </dt>
   1082     <dd>
   1083         The class that implements {@link android.content.ContentProvider}. This class is
   1084         described in more detail in the section
   1085         <a href="#ContentProvider">Implementing the ContentProvider Class</a>.
   1086     </dd>
   1087     <dt>
   1088         Permissions
   1089     </dt>
   1090     <dd>
   1091         Attributes that specify the permissions that other applications must have in order to access
   1092         the provider's data:
   1093         <ul>
   1094             <li>
   1095                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">
   1096                 android:grantUriPermssions</a></code>: Temporary permission flag.
   1097             </li>
   1098             <li>
   1099                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">
   1100                 android:permission</a></code>: Single provider-wide read/write permission.
   1101             </li>
   1102             <li>
   1103                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">
   1104                 android:readPermission</a></code>: Provider-wide read permission.
   1105             </li>
   1106             <li>
   1107                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">
   1108                 android:writePermission</a></code>: Provider-wide write permission.
   1109             </li>
   1110         </ul>
   1111         <p>
   1112             Permissions and their corresponding attributes are described in more
   1113             detail in the section
   1114             <a href="#Permissions">Implementing Content Provider Permissions</a>.
   1115         </p>
   1116     </dd>
   1117     <dt>
   1118         Startup and control attributes
   1119     </dt>
   1120     <dd>
   1121         These attributes determine how and when the Android system starts the provider, the
   1122         process characteristics of the provider, and other run-time settings:
   1123         <ul>
   1124             <li>
   1125                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#enabled">
   1126                 android:enabled</a></code>: Flag allowing the system to start the provider.
   1127             </li>
   1128               <li>
   1129                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#exported">
   1130                 android:exported</a></code>: Flag allowing other applications to use this provider.
   1131             </li>
   1132             <li>
   1133                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#init">
   1134                 android:initOrder</a></code>: The order in which this provider should be started,
   1135                 relative to other providers in the same process.
   1136             </li>
   1137             <li>
   1138                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#multi">
   1139                 android:multiProcess</a></code>: Flag allowing the system to start the provider
   1140                 in the same process as the calling client.
   1141             </li>
   1142             <li>
   1143                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#proc">
   1144                 android:process</a></code>: The name of the process in which the provider should
   1145                 run.
   1146             </li>
   1147             <li>
   1148                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#sync">
   1149                 android:syncable</a></code>: Flag indicating that the provider's data is to be
   1150                 sync'ed with data on a server.
   1151             </li>
   1152         </ul>
   1153         <p>
   1154             The attributes are fully documented in the dev guide topic for the
   1155             <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
   1156             &lt;provider&gt;</a></code>
   1157             element.
   1158         </p>
   1159     </dd>
   1160     <dt>
   1161         Informational attributes
   1162     </dt>
   1163     <dd>
   1164         An optional icon and label for the provider:
   1165         <ul>
   1166             <li>
   1167                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#icon">
   1168                 android:icon</a></code>: A drawable resource containing an icon for the provider.
   1169                 The icon appears next to the provider's label in the list of apps in
   1170                 <em>Settings</em> &gt; <em>Apps</em> &gt; <em>All</em>.
   1171             </li>
   1172             <li>
   1173                 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#label">
   1174                 android:label</a></code>: An informational label describing the provider or its
   1175                 data, or both. The label appears in the list of apps in
   1176                 <em>Settings</em> &gt; <em>Apps</em> &gt; <em>All</em>.
   1177             </li>
   1178         </ul>
   1179         <p>
   1180             The attributes are fully documented in the dev guide topic for the
   1181             <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
   1182             &lt;provider&gt;</a></code> element.
   1183         </p>
   1184     </dd>
   1185 </dl>
   1186 
   1187 <!-- Intent Access -->
   1188 <h2 id="Intents">Intents and Data Access</h2>
   1189 <p>
   1190     Applications can access a content provider indirectly with an {@link android.content.Intent}.
   1191     The application does not call any of the methods of {@link android.content.ContentResolver} or
   1192     {@link android.content.ContentProvider}. Instead, it sends an intent that starts an activity,
   1193     which is often part of the provider's own application. The destination activity is in charge of
   1194     retrieving and displaying the data in its UI. Depending on the action in the intent, the
   1195     destination activity may also prompt the user to make modifications to the provider's data.
   1196     An intent may also contain &quot;extras&quot; data that the destination activity displays
   1197     in the UI; the user then has the option of changing this data before using it to modify the
   1198     data in the provider.
   1199 </p>
   1200 <p>
   1201 
   1202 </p>
   1203 <p>
   1204     You may want to use intent access to help ensure data integrity. Your provider may depend
   1205     on having data inserted, updated, and deleted according to strictly defined business logic. If
   1206     this is the case, allowing other applications to directly modify your data may lead to
   1207     invalid data. If you want developers to use intent access, be sure to document it thoroughly.
   1208     Explain to them why intent access using your own application's UI is better than trying to
   1209     modify the data with their code.
   1210 </p>
   1211 <p>
   1212     Handling an incoming intent that wishes to modify your provider's data is no different from
   1213     handling other intents. You can learn more about using intents by reading the topic
   1214     <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>.
   1215 </p>
   1216